API Reference & Workflow

This API allows you to programmatically upload content to TikTok, Instagram, YouTube, Facebook, Pinterest, Bluesky and more. The process is asynchronous to handle large files and platform-specific processing times efficiently.

Architecture Overview

Workflow Overview

The general workflow for uploading content involves two main steps:

1. Initiate Upload: Send your media file(s) and metadata to the upload endpoint. The server queues the job and returns an uploadId.
2. Check Status: Poll the status endpoint using the uploadId, or receive a webhook when the upload is complete.

Sequence Diagram

Base URL

https://api.multi-upload-tool.com/api/v1

Authentication

All requests require an API key in the header:

x-api-key: YOUR_API_TOKEN

API Key Access (Scopes)

Each key carries a list of scopes, chosen when you create it under Settings > API Keys. Give each integration only what it needs: a reporting dashboard needs analytics:read, not the right to publish.

• write includes read; posts:publish includes posts:write and posts:read.
• The dashboard offers presets: Full access, Publishing, Drafts only (AI agent), Read only, or Custom.
• Drafts only (posts:write without posts:publish) is made for AI agents: they prepare posts, a human approves them. See Drafts & Approval.
• Every operation states the scope it needs in the OpenAPI document  (x-required-scope).
• Existing keys keep full access: nothing changes for them unless you edit them.
• A key must hold at least one scope: an empty list is refused (* is full access).
• A key without webhooks:write does not see the webhooks’ signing secret.
• On the MCP endpoint, the same scopes decide which tools the key sees.

A call the key is not allowed to make returns 403:

{ "success": false, "error": "This API key does not have the \"webhooks:write\" scope needed here. …", "code": "INSUFFICIENT_SCOPE", "requiredScope": "webhooks:write" }

Rotate a key

Rotate in the key’s menu creates a new secret with the same name and access. The old secret stops working immediately, so update every tool that uses it.

Rate Limiting

Idempotency (safe retries)

A request that times out may still have gone through. Send an Idempotency-Key header on POST /upload and POST /upload/bulk so a retry never publishes twice:

curl -X POST https://api.multi-upload-tool.com/api/v1/upload/bulk \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Idempotency-Key: 5f0c2a8e-7d1b-4c3e-9a61-2b8f4e1d9c07" \
  -F 'accounts=["cmf3k9x2a0001l408q7vbn2hd"]' \
  -F "video=@/path/to/video.mp4"

• Use a new unique value (a UUID) for each post you intend to create, and the same value when you retry that post.
• For 24 hours, a retry with the same key returns the first response unchanged, with the header Idempotent-Replay: true. Nothing is published again.
• If the first request is still running, the retry gets 409 IDEMPOTENCY_IN_PROGRESS: wait and retry.
• If the first request failed with an error, the key is released: the retry runs normally.
• With async=false, if the post takes more than 10 minutes to publish, the response is status: "processing" with its uploadId (check it with GET /upload/:id). That response is the one replayed: a retry never publishes twice.
• Keys are scoped to your account and to the endpoint, and are at most 255 characters. The body is not compared: a different body sent with a used key still gets the first response.

Over MCP, pass the same value as the idempotencyKey argument of create_post.

Response Format

All responses follow a standard JSON structure:

{
  "success": true,
  "message": "Optional message",
  "data": { ... },
  "error": "Error message (if success is false)"
}