Social Media Publishing API

Before your first request

1. Connect your Meta accounts in Social Media Hub.
2. Create an API key in My API Keys.
3. List your connected accounts and copy the IDs you want to target.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

These endpoints accept API keys or Firebase ID tokens through the Bearer header. Browser session cookies alone are not accepted. Keep keys on your server. Responses use a data envelope or an error object and are never publicly cached. These endpoints do not generate AI content or deduct AI generation credits.

Limits are shared across API keys for your user: 300 read requests and 60 write requests per minute. HTTP 429 includes a Retry-After header. Space status polling a few seconds apart and reuse uploaded media IDs.

1. Discover connected accounts

GET https://codingmantra.com/api/v1/social/accounts

Use the returned id in accountIds. Facebook and Instagram IDs use explicit platform prefixes. A human account name is a label and is not an identifier. canPublish indicates current connection readiness; Meta may still reject a request due to permissions or platform limits.

{
  "data": {
    "connectionStatus": "connected",
    "accounts": [
      {
        "id": "facebook:123456",
        "platform": "facebook",
        "platformAccountId": "123456",
        "name": "Example Brand",
        "selected": true,
        "canPublish": true,
        "tokenStatus": "active",
        "capabilities": {
          "text": true,
          "maxImages": 10,
          "maxCaptionLength": 63206
        }
      }
    ]
  }
}

2. Upload or reference an image

POST https://codingmantra.com/api/v1/social/media

{"url":"https://example.com/product.png"}

// Or raw base64 with an optional MIME type:
{"base64":"BASE64_IMAGE_BYTES","mimeType":"image/png"}

// Or a JSON string containing a data URI:
"data:image/png;base64,BASE64_IMAGE_BYTES"

The response contains id, a prepared image url, mimeType, width, height, bytes and createdAt. Retrieve this metadata with GET /api/v1/social/media/{id}. Images are stored as dedicated API assets so removing an item from the generated-image gallery does not remove queued API media.

Images must be static JPEG, PNG or WebP, no more than 10 MB each and 40 million pixels. JSON requests are limited to 20 MB, including base64 encoding. Public HTTPS URLs must return the image directly on port 443; redirects, private network addresses and URL credentials are rejected. Use reusable media IDs to avoid sending large base64 bodies repeatedly. Normalized JPEGs are resized to at most 1440 × 1800 pixels and remain under 8 MB; small widths are enlarged to 320 pixels. Extremely narrow images that would exceed the height limit during enlargement are rejected.

3. Create a post for one or several accounts

POST https://codingmantra.com/api/v1/social/posts
Idempotency-Key: campaign-2027-launch-001

{
  "accountIds": [
    "facebook:123456",
    "instagram:17890000000000000"
  ],
  "caption": "Meet our new collection.",
  "hashtags": [
    "NewCollection"
  ],
  "images": [
    {
      "url": "https://example.com/product.jpg"
    }
  ],
  "scheduledFor": "2027-01-15T10:00:00+05:30"
}

accountIds accepts a single string or an array of up to 20 distinct IDs. Omit scheduledFor to queue immediate delivery, or provide a future ISO-8601 timestamp with Z or an explicit timezone offset. All targets are checked before image processing or queue creation. A failed target validation rejects the entire submission.

Each images item can be a URL string, a base64 string, a data URI, {url}, {base64, mimeType?}, or {mediaId}. Uploaded media IDs are scoped to your API key’s owner. Facebook supports text and up to ten images; Instagram currently supports exactly one image. Video, carousels, Stories, Reels and direct messages are not supported by this contract.

// Single Facebook target with an already uploaded image:
{
  "accountIds": "facebook:123456",
  "caption": "Our latest product.",
  "images": [
    {
      "mediaId": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

A new immediate request returns 202; a new scheduled request returns 201. The Location header points to its status endpoint. An identical retry returns 200 and Idempotency-Replayed: true. Keys are scoped to your user and retained. A key stays consumed after cancellation or removal of the post record; use a new key only for an intentional new post.

4. Track or cancel delivery

GET /api/v1/social/posts/{id}
GET /api/v1/social/posts?status=scheduled&platform=facebook&limit=20&offset=0
DELETE /api/v1/social/posts/{id}

The post response includes ISO timestamps, caption, hashtags, prepared image URLs, retry details and an accounts array. Each account reports pending, publishing, published, failed or cancelled, with jobId, providerPostId, publishedAt and error when available. A failed account can be awaiting the queue’s next retry while another account is already published.

The list supports status, platform, fromDate, toDate, limit (1–100) and offset (0–10,000). Its response contains items, total, hasMore, limit and offset. Unsupported query fields are rejected.

DELETE cancels outstanding queue deliveries and retains the record. It does not delete a live Facebook or Instagram post. Cancellation is rejected while the worker is publishing or after the whole post is published. For a partially delivered post, successful accounts remain published and only remaining targets are cancelled.

Errors and retries

{
  "error": {
    "code": "ACCOUNT_NEEDS_RECONNECT",
    "message": "Reconnect your account in Social Media Hub before publishing."
  }
}

• 400: invalid JSON or missing idempotency key.
• 401: missing or invalid Bearer credentials.
• 404: account, media or post not found for your user.
• 409: reconnect required, conflicting key, request already processing, or a post mutation conflict. REQUEST_IN_PROGRESS includes Retry-After: 10.
• 410: the original keyed post record was removed.
• 413: image or request exceeds the documented size limits.
• 415: request body is not JSON.
• 422: invalid fields, image content, image URL, dimensions or schedule.
• 429: request limit reached; wait for Retry-After seconds.
• 500: internal failure; retry the same request with the same key.

Frequently asked questions