README

REST API extension for Mixpost - Enable powerful automation with n8n and external integrations

📖 About

Mixpost REST API is a powerful Laravel package that extends Mixpost with comprehensive REST API capabilities. Built specifically to enable seamless integration with workflow automation tools like n8n, this add-on transforms Mixpost into a fully API-driven social media management platform.

🎯 Perfect For

Workflow Automation: Integrate with n8n, Zapier, Make.com
Custom Applications: Build your own social media management tools
AI-Powered Content: Auto-generate and publish content with AI services
Content Pipelines: Automate blog-to-social workflows
Team Collaboration: External tools can interact with Mixpost programmatically
Scheduled Automation: Time-based social media campaigns

✨ Features

🚀 API Coverage (v1.0.0)

✅ Posts Management: Full CRUD operations, scheduling, and publishing
✅ Media Handling: Upload files, download from URLs, manage library
✅ Account Management: List and manage social media accounts
✅ Tags & Organization: Create, update, delete tags

🔮 Planned Features (Future Releases)

📅 Analytics & Reports: Dashboard metrics, account stats, post performance
📅 Calendar Integration: View and manage scheduled content
📅 System Monitoring: Check status, queue health, service configuration

🔐 Security & Performance

✅ Laravel Sanctum Authentication: Secure token-based API access
✅ Rate Limiting: Configurable request throttling (default: 60/min)
✅ Permission System: Token abilities for granular access control
✅ HTTPS Enforcement: Production-ready security
✅ IP Whitelisting: Optional IP restriction
✅ Input Validation: Comprehensive server-side validation

🎨 Developer Experience

✅ RESTful Design: Clean, predictable API structure
✅ JSON Responses: Consistent response formats
✅ Pagination: Efficient data handling for large datasets
✅ Error Handling: Detailed, actionable error messages
✅ Comprehensive Documentation: Full API specification and examples
✅ n8n Ready: Pre-built workflow examples included

📋 Requirements

PHP: ^8.2
Laravel: ^10.47 | ^11.0
Mixpost: ^1.0 (installed automatically as dev dependency)
Laravel Sanctum: ^3.0 | ^4.0

🚀 Installation

Step 1: Install via Composer

composer require inovector/mixpost-api

Step 2: Publish Configuration (Optional)

php artisan vendor:publish --tag=mixpost-api-config

This creates config/mixpost-api.php where you can customize:

API prefix
Rate limiting
Token expiration
Security settings
Pagination defaults

Step 3: Run Migrations

php artisan migrate

This creates the personal_access_tokens table for Laravel Sanctum.

Step 4: Update User Model

Add the HasApiTokens trait to your User model:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;

    // ... rest of your model
}

Step 5: You're Ready! 🎉

Your Mixpost installation now has REST API endpoints available at:

https://your-domain.com/api/mixpost/*

🔧 Configuration

Environment Variables

Add to your .env file:

# API Configuration
MIXPOST_API_RATE_LIMIT=60
MIXPOST_API_HTTPS_ONLY=true

# Token Configuration
MIXPOST_API_TOKEN_EXPIRATION=null  # null = never expire

Configuration File

Edit config/mixpost-api.php:

return [
    'prefix' => 'api/mixpost',

    'rate_limit' => [
        'enabled' => true,
        'max_attempts' => env('MIXPOST_API_RATE_LIMIT', 60),
        'decay_minutes' => 1,
    ],

    'token' => [
        'expiration' => env('MIXPOST_API_TOKEN_EXPIRATION'),
        'abilities_enabled' => true,
    ],

    'pagination' => [
        'default_per_page' => 20,
        'max_per_page' => 100,
    ],

    'security' => [
        'ip_whitelist_enabled' => false,
        'ip_whitelist' => [],
        'https_only' => env('MIXPOST_API_HTTPS_ONLY', true),
    ],
];

📚 Quick Start Guide

1. Generate API Token

Using cURL:

curl -X POST https://your-domain.com/api/mixpost/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "your-password",
    "token_name": "n8n-integration"
  }'

Response:

{
  "token": "1|abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "token_type": "Bearer",
  "expires_at": null
}

2. Use Token in Requests

curl -X GET https://your-domain.com/api/mixpost/posts \
  -H "Authorization: Bearer 1|abc123def456..." \
  -H "Accept: application/json"

3. Create a Post

curl -X POST https://your-domain.com/api/mixpost/posts \
  -H "Authorization: Bearer 1|abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [1, 2, 3],
    "tags": [1],
    "date": "2025-10-24",
    "time": "10:00",
    "versions": [
      {
        "is_original": true,
        "account_id": null,
        "content": [
          {
            "body": "Check out our latest blog post! 🚀",
            "media": []
          }
        ]
      }
    ]
  }'

🎯 API Endpoints Overview

Authentication

POST /api/mixpost/auth/tokens - Generate API token
GET /api/mixpost/auth/tokens - List user tokens
DELETE /api/mixpost/auth/tokens/{id} - Revoke token

Posts

GET /api/mixpost/posts - List posts (with filtering & pagination)
POST /api/mixpost/posts - Create post
GET /api/mixpost/posts/{id} - Get post details
PUT /api/mixpost/posts/{id} - Update post
DELETE /api/mixpost/posts/{id} - Delete post
POST /api/mixpost/posts/{id}/schedule - Schedule post
POST /api/mixpost/posts/{id}/publish - Publish immediately
POST /api/mixpost/posts/{id}/duplicate - Duplicate post
DELETE /api/mixpost/posts - Bulk delete posts

Media

GET /api/mixpost/media - List media files
POST /api/mixpost/media - Upload media file
POST /api/mixpost/media/download - Download from URL
GET /api/mixpost/media/{id} - Get media details
DELETE /api/mixpost/media/{id} - Delete media file
DELETE /api/mixpost/media - Bulk delete media

Accounts

GET /api/mixpost/accounts - List social media accounts
GET /api/mixpost/accounts/{id} - Get account details
PUT /api/mixpost/accounts/{id} - Update account
DELETE /api/mixpost/accounts/{id} - Delete account

Planned Endpoints (Future Releases)

Reports & Analytics

GET /api/mixpost/reports/dashboard - Dashboard summary
GET /api/mixpost/reports/accounts/{id} - Account analytics
GET /api/mixpost/reports/posts/{id} - Post performance

Calendar

GET /api/mixpost/calendar - Get scheduled posts

System Monitoring

GET /api/mixpost/system/status - System health check

🔌 n8n Integration

Quick Setup

Create n8n Credential
- Type: Header Auth
- Name: Authorization
- Value: Bearer YOUR_TOKEN_HERE
Use HTTP Request Node
- Method: POST
- URL: https://your-domain.com/api/mixpost/posts
- Authentication: Use the credential from step 1
- Body: JSON with post data

Example Workflows

📝 Auto-Post from Blog Publication

Webhook (Blog Published)
  ↓
Upload Featured Image
  ↓
Create Social Post
  ↓
Publish Immediately

🤖 AI Content Generation

Schedule Trigger (Daily 9am)
  ↓
OpenAI (Generate Content)
  ↓
DALL-E (Generate Image)
  ↓
Upload to Mixpost
  ↓
Create Scheduled Post

📊 Performance Monitoring

Schedule Trigger (Daily 6pm)
  ↓
Get Dashboard Stats
  ↓
Check for Failed Posts
  ↓
Send Slack Notification

📖 Complete n8n Examples: N8N_INTEGRATION_EXAMPLES.md

📖 Documentation

Core Documentation

API Specification - Complete endpoint reference
Authentication Guide - Laravel Sanctum setup
n8n Integration - Workflow examples
Implementation Plan - Package architecture

Example Use Cases

Use Case 1: Blog to Social Media

Automatically create social media posts when new blog articles are published.

Use Case 2: AI-Powered Content

Generate content with OpenAI and schedule posts across multiple platforms.

Use Case 3: Content Curation

Monitor RSS feeds and share relevant content automatically.

Use Case 4: Bulk Scheduling

Schedule multiple posts from CSV files or spreadsheets.

Use Case 5: Emergency Announcements

Publish urgent content immediately across all platforms.

🧪 Testing

Run Tests

# Run all tests
composer test

# Run with coverage
composer test-coverage

# Run specific test
vendor/bin/pest tests/Feature/PostsApiTest.php

Example Test

public function test_can_create_post_via_api()
{
    Sanctum::actingAs($this->user, ['*']);

    $response = $this->postJson('/api/mixpost/posts', [
        'accounts' => [1, 2],
        'versions' => [
            [
                'is_original' => true,
                'content' => [
                    ['body' => 'Test post', 'media' => []]
                ]
            ]
        ]
    ]);

    $response->assertStatus(201)
             ->assertJsonStructure(['data', 'message']);
}

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (composer test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow PSR-12 coding standards
Write tests for new features
Update documentation for API changes
Keep backward compatibility when possible
Add changelog entries for notable changes

Code Style

# Format code
composer format

# Check code style
./vendor/bin/pint --test

🐛 Security Vulnerabilities

If you discover a security vulnerability, please send an email to security@example.com. All security vulnerabilities will be promptly addressed.

Do not open public issues for security vulnerabilities.

📜 Changelog

Please see CHANGELOG.md for recent changes.

Recent Updates

v1.0.0 (2025-10-23)

Initial release
Complete REST API for Mixpost
Laravel Sanctum authentication
n8n integration support
Comprehensive documentation

🙏 Credits

Mixpost - The amazing social media management platform this extends
Laravel - The PHP framework
Laravel Sanctum - API authentication
n8n - Workflow automation platform

Built With

Laravel - Web application framework
Laravel Sanctum - API token authentication
Pest PHP - Testing framework
Laravel Pint - Code style fixer

📄 License

The MIT License (MIT). Please see LICENSE.md for more information.

MIT License

Copyright (c) 2025 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

💬 Support

Documentation: docs/
Issues: GitHub Issues
Discussions: GitHub Discussions
Mixpost Discord: Join Community

🌟 Star History

If you find this package useful, please consider giving it a ⭐ on GitHub!

🔗 Links

Mixpost: https://mixpost.app
Mixpost GitHub: https://github.com/inovector/mixpost
Mixpost Documentation: https://docs.mixpost.app
n8n: https://n8n.io
Laravel: https://laravel.com

Made with ❤️ for the Mixpost community

Transform your social media management with powerful API automation

btafoya / mixpost-api

Maintainers

Details