API Reference

Complete reference documentation for all SocialHub API endpoints, including parameters, request/response formats, and error codes.

Base URL

https://your-domain.com/api/agents/v1

Authentication

All API requests require authentication using an API Key. Include your API Key in one of the following headers:

X-API-Key: your_api_key_here
Authorization: Bearer your_api_key_here

Endpoints

POST/auth/validate

Validate your API Key and retrieve user information

Request

No request body required

Response

{
  "valid": true,
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com"
  }
}

POST/media/prepare

Prepare media files from external URLs for publication

Request Body

{
  "urls": [
    "https://example.com/image1.jpg",
    "https://drive.google.com/file/d/ABC123/view",
    "https://s3.amazonaws.com/bucket/video.mp4"
  ]
}

Response

{
  "success": true,
  "task_id": "task_abc123",
  "message": "Media preparation started"
}

Limits: Max 10 URLs, 500MB per file, 10 minute timeout

GET/media/status/{taskId}

Check the status of a media preparation task

Path Parameters

taskId - The task ID returned from the prepare endpoint

Response (Processing)

{
  "status": "processing",
  "progress": {
    "total": 3,
    "completed": 1,
    "failed": 0
  }
}

Response (Completed)

{
  "status": "completed",
  "files": [
    {
      "original_url": "https://example.com/image1.jpg",
      "prepared_url": "https://your-s3.amazonaws.com/uploads/image1.jpg",
      "type": "image",
      "size": 2048576
    }
  ]
}

POST/content/publish

Publish or schedule content to one or multiple social media platforms

Request Body

{
  "caption": "Default caption for all platforms",
  "platforms": ["instagram", "facebook", "twitter"],
  "platform_captions": {
    "instagram": "Instagram-specific caption #hashtags",
    "twitter": "Twitter-specific caption @mentions"
  },
  "platform_types": {
    "instagram": ["feed", "story"],
    "facebook": ["feed"]
  },
  "media_urls": [
    "https://your-s3.amazonaws.com/uploads/image1.jpg"
  ],
  "publish_now": false,
  "scheduled_for": "2024-12-25T10:00:00Z",
  "type_schedule": {
    "story": "+0h",
    "feed": "+1h"
  },
  "require_approval": false
}

Parameter	Type	Required	Description
`caption`	string	Yes	Default caption
`platforms`	string[]	Yes	Target platforms
`media_urls`	string[]	No	Media file URLs
`publish_now`	boolean	No	Publish immediately
`scheduled_for`	string	No	ISO 8601 datetime

Response

{
  "success": true,
  "message": "Publication created successfully",
  "job_id": "pub_abc123",
  "scheduled_for": "2024-12-25T10:00:00Z",
  "platforms": ["instagram", "facebook"]
}

GET/content/scheduled

List scheduled publications

Query Parameters

status - Filter by status: scheduled, pending_approval, completed
limit - Number of results (default: 50, max: 100)
offset - Pagination offset (default: 0)

Response

{
  "success": true,
  "jobs": [
    {
      "id": "pub_abc123",
      "caption": "Scheduled post",
      "platforms": ["instagram"],
      "scheduled_for": "2024-12-25T10:00:00Z",
      "status": "scheduled"
    }
  ],
  "total": 1
}

PATCH/content/scheduled

Update a scheduled publication

Query Parameters

job_id - The publication job ID to update

Request Body

{
  "caption": "Updated caption",
  "scheduled_for": "2024-12-26T10:00:00Z"
}

Response

{
  "success": true,
  "message": "Publication updated successfully"
}

DELETE/content/scheduled

Cancel a scheduled publication

Query Parameters

job_id - The publication job ID to cancel

Response

{
  "success": true,
  "message": "Publication cancelled successfully"
}

Error Responses

All error responses follow this format:

{
  "error": "Error message",
  "details": "Additional error details (optional)"
}

Status Code	Error	Description
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Missing or invalid API Key
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource not found
`413`	Payload Too Large	Request body exceeds size limit
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server-side error

Rate Limits

Authentication: 10 requests/minute
Publishing: 60 requests/hour
Media Preparation: 30 requests/hour
Scheduled Content: 100 requests/hour

When rate limited, responses include a Retry-After header indicating when you can retry.

Need Help?

Having issues? Check the Troubleshooting section for common problems and solutions.