Create Post

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Behind the scenes",
    "media": {
      "type": "video",
      "url": "https://cdn.example.com/reel.mp4",
      "cover_url": "https://cdn.example.com/cover.jpg"
    },
    "accounts": [{ "id": "YOUR_INSTAGRAM_ACCOUNT_ID" }]
  }'

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Quick tip",
    "media": {
      "type": "video",
      "url": "https://cdn.example.com/tip.mp4"
    },
    "accounts": [{ "id": "YOUR_TIKTOK_ACCOUNT_ID" }]
  }'

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "3 looks for the weekend",
    "media": {
      "type": "slideshow",
      "urls": [
        "https://cdn.example.com/1.jpg",
        "https://cdn.example.com/2.jpg"
      ]
    },
    "accounts": [{ "id": "YOUR_INSTAGRAM_ACCOUNT_ID" }]
  }'

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "3 outfits for the long weekend",
    "media": {
      "type": "slideshow",
      "urls": [
        "https://cdn.example.com/look-1.jpg",
        "https://cdn.example.com/look-2.jpg",
        "https://cdn.example.com/look-3.jpg"
      ]
    },
    "accounts": [{ "id": "YOUR_TIKTOK_ACCOUNT_ID" }],
    "tiktok": {
      "post_mode": "MEDIA_UPLOAD",
      "music_usage_confirmation": true,
      "privacy_level": "SELF_ONLY"
    },
    "external_id": "tiktok-draft-001"
  }'

{
  "success": true,
  "message": "<string>",
  "data": {
    "id": "<string>",
    "status": "draft",
    "type": "video",
    "caption": "<string>",
    "scheduled_at": "2023-11-07T05:31:56Z",
    "accounts": [
      "<string>"
    ]
  }
}

{
  "error": "<string>",
  "success": true,
  "code": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "success": true,
  "code": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "success": true,
  "code": "<string>",
  "message": "<string>"
}

POST

posts

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Behind the scenes",
    "media": {
      "type": "video",
      "url": "https://cdn.example.com/reel.mp4",
      "cover_url": "https://cdn.example.com/cover.jpg"
    },
    "accounts": [{ "id": "YOUR_INSTAGRAM_ACCOUNT_ID" }]
  }'

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Quick tip",
    "media": {
      "type": "video",
      "url": "https://cdn.example.com/tip.mp4"
    },
    "accounts": [{ "id": "YOUR_TIKTOK_ACCOUNT_ID" }]
  }'

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "3 looks for the weekend",
    "media": {
      "type": "slideshow",
      "urls": [
        "https://cdn.example.com/1.jpg",
        "https://cdn.example.com/2.jpg"
      ]
    },
    "accounts": [{ "id": "YOUR_INSTAGRAM_ACCOUNT_ID" }]
  }'

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "3 outfits for the long weekend",
    "media": {
      "type": "slideshow",
      "urls": [
        "https://cdn.example.com/look-1.jpg",
        "https://cdn.example.com/look-2.jpg",
        "https://cdn.example.com/look-3.jpg"
      ]
    },
    "accounts": [{ "id": "YOUR_TIKTOK_ACCOUNT_ID" }],
    "tiktok": {
      "post_mode": "MEDIA_UPLOAD",
      "music_usage_confirmation": true,
      "privacy_level": "SELF_ONLY"
    },
    "external_id": "tiktok-draft-001"
  }'

{
  "success": true,
  "message": "<string>",
  "data": {
    "id": "<string>",
    "status": "draft",
    "type": "video",
    "caption": "<string>",
    "scheduled_at": "2023-11-07T05:31:56Z",
    "accounts": [
      "<string>"
    ]
  }
}

{
  "error": "<string>",
  "success": true,
  "code": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "success": true,
  "code": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "success": true,
  "code": "<string>",
  "message": "<string>"
}

Schedule a post for later or save it as a draft. Publishing runs through Unsora when the post is published from the scheduler. Posts can target any connected account on: YouTube, TikTok, Instagram, Facebook, LinkedIn, Bluesky, Threads, Pinterest (up to 10 accounts per post, mixed platforms allowed).

Supported content

`media.type`	Use for	Response `type`
`video`	Instagram Reel, TikTok Reel	`video`
`slideshow`	Instagram carousel, TikTok photo post	`slideshow`

Connect accounts in the Unsora app, then list them via Get accounts. Note: YouTube accepts video posts only; text-only posts work on Facebook, LinkedIn, Bluesky, and Threads.

Media requirements

Make sure media matches each platform’s rules before creating the post. Media that violates them fails at publish time: the post ends up FAILED (or PARTIALLY_PUBLISHED) with the platform’s error on the affected account — fix the media and create a new post, or use Retry post for accounts that failed for other reasons.

Placement	Allowed aspect ratio	Recommended size
Instagram feed image / carousel item	4:5 to 1.91:1	1080×1350, 1080×1080, 1080×566
Instagram Reel (video)	9:16 recommended	1080×1920
TikTok slideshow / video	9:16 recommended	1080×1920

Instagram rejects feed/carousel images outside 4:5 – 1.91:1 (e.g. 9:16 images). When posting the same slideshow to Instagram and TikTok, use 4:5 images (both platforms accept them) — or create separate posts per platform.

Images should be JPEG — Instagram’s API only accepts JPEG, and TikTok photo posts accept JPEG/WebP. PNG images posted to TikTok are converted to JPEG automatically at publish time. Videos should be MP4/MOV (H.264 + AAC) at a publicly reachable URL.

Before you post

Active paid plan + API key or Clerk JWT.
Get accounts → copy each account id.
Pick video or slideshow. For Instagram reels, optional cover_url.

Request body

string

required

Post caption. Legacy alias: mainCaption.

array

required

[{ "id": "<account-uuid>" }] — up to 10 accounts. Each account object also accepts optional title (YouTube video title / Pinterest pin title) and customCaption (overrides caption for that account only).

object | null

Show Video (reel)

string

required

video

string

required

MP4/MOV URL reachable by Unsora.

number

Video length in seconds.

string

Optional Instagram Reel cover image (JPG/PNG URL). Ignored by TikTok.

Show Slideshow

string

required

slideshow

string[]

required

1–35 image URLs in order.

object

Optional publish options for Instagram, TikTok, YouTube, and Pinterest. You can also send instagram, tiktok, youtube, or pinterest at the top level of the body (same shape as below). Other keys under settings return 400.

Show Instagram — settings.instagram

string

Custom Reel cover image URL (JPG/PNG). Same as media.cover_url.

Show TikTok — settings.tiktok

string

DIRECT_POST (default) or MEDIA_UPLOAD (inbox draft — user finishes in TikTok).

string

e.g. PUBLIC_TO_EVERYONE, SELF_ONLY. Must match creator info for the account.

boolean

Confirm music usage when TikTok requires it.

boolean

Paid partnership (third-party brand).

boolean

Promoting creator’s own business.

boolean

AI-generated content flag.

boolean

Slideshow only — TikTok adds background music.

integer

Slideshow only — cover image index (0-based).

integer

Reel only — cover frame time in ms.

Show YouTube — settings.youtube

string

public (default), private, or unlisted.

string[]

Video tags.

string

YouTube category id.

boolean

COPPA made-for-kids flag.

Show Pinterest — settings.pinterest

string

Board to pin to. Defaults to the account’s first board.

string

ISO 8601 with timezone, ≥ 2 minutes ahead. Omit for draft.

string

Idempotency key (max 128 chars) or use Idempotency-Key header.

Instagram reel cover

Only cover_url — a public image URL:

"media": {
  "type": "video",
  "url": "https://cdn.example.com/reel.mp4",
  "cover_url": "https://cdn.example.com/cover.jpg"
}

TikTok reel cover frame: optional settings.tiktok.video_cover_timestamp_ms.

Platform settings (optional)

Supported providers: Instagram, TikTok, YouTube, Pinterest — via settings.<provider> (or the same keys at the top level of the body). Nothing is required; omit settings if you do not need them. YouTube video titles and Pinterest pin titles go on the account object (accounts[].title), not in settings.

Top-level tiktok / instagram / youtube / pinterest keys work the same as their settings.* equivalents.

"settings": {
  "instagram": { "cover_url": "https://cdn.example.com/cover.jpg" },
  "tiktok": {
    "post_mode": "MEDIA_UPLOAD",
    "privacy_level": "SELF_ONLY",
    "music_usage_confirmation": true
  },
  "youtube": {
    "privacy_status": "unlisted",
    "tags": ["ai", "shorts"]
  },
  "pinterest": { "board_id": "1234567890" }
}

Response

{
  "success": true,
  "message": "Post saved as draft",
  "data": {
    "id": "cm123abc",
    "status": "draft",
    "type": "video",
    "caption": "Behind the scenes",
    "scheduled_at": null,
    "accounts": ["acc_instagram"]
  }
}

Examples

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Behind the scenes",
    "media": {
      "type": "video",
      "url": "https://cdn.example.com/reel.mp4",
      "cover_url": "https://cdn.example.com/cover.jpg"
    },
    "accounts": [{ "id": "YOUR_INSTAGRAM_ACCOUNT_ID" }]
  }'

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Quick tip",
    "media": {
      "type": "video",
      "url": "https://cdn.example.com/tip.mp4"
    },
    "accounts": [{ "id": "YOUR_TIKTOK_ACCOUNT_ID" }]
  }'

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "3 looks for the weekend",
    "media": {
      "type": "slideshow",
      "urls": [
        "https://cdn.example.com/1.jpg",
        "https://cdn.example.com/2.jpg"
      ]
    },
    "accounts": [{ "id": "YOUR_INSTAGRAM_ACCOUNT_ID" }]
  }'

curl -X POST "https://mvp2.tryunsora.com/api/v1/posts" \
  -H "Authorization: Bearer uns_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "3 outfits for the long weekend",
    "media": {
      "type": "slideshow",
      "urls": [
        "https://cdn.example.com/look-1.jpg",
        "https://cdn.example.com/look-2.jpg",
        "https://cdn.example.com/look-3.jpg"
      ]
    },
    "accounts": [{ "id": "YOUR_TIKTOK_ACCOUNT_ID" }],
    "tiktok": {
      "post_mode": "MEDIA_UPLOAD",
      "music_usage_confirmation": true,
      "privacy_level": "SELF_ONLY"
    },
    "external_id": "tiktok-draft-001"
  }'

Post lifecycle

DRAFT → SCHEDULED → PUBLISHING → one of:

Status	Meaning
`PUBLISHED`	Every account published
`PARTIALLY_PUBLISHED`	Some accounts published, some failed
`FAILED`	No account published

For FAILED or PARTIALLY_PUBLISHED posts, call Retry post — it re-attempts only the failed accounts and never double-posts. Per-account results (including publishedUrl and error) are on each post’s postAccounts.

Errors

HTTP	When
`400`	Validation failed
`401`	Invalid auth
`403`	No paid plan or unknown account
`404`	User not found
`409`	Idempotency conflict
`500`	Server error

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

Idempotency key, up to 128 characters. Used only with API keys. Longer keys are ignored.

Maximum string length: 128

X-Unsora-Client

string

The Unsora MCP server sends mcp, which records the post source as MCP. Any other value, or no header, records API.

Body

application/json

caption

string

required

Post text, used for every account that has no customCaption. Must not be empty. Alias: mainCaption.

accounts

object[]

required

Accounts to publish to. Platforms can be mixed. Every account must belong to the caller.

Required array length: 1 - 10 elements

Show child attributes

media

object

Omit or send null for a text post. Send a video object, a slideshow object, or an array of media items.

Option 1 · object
Option 2 · object
Option 3 · object[]

Show child attributes

type

enum<string>

Overrides the post type inferred from media. Inferred type: no media is TEXT; a video object is VIDEO; a slideshow object is CAROUSEL; an array is CAROUSEL when it has more than one item, VIDEO when its single item is a VIDEO, otherwise IMAGE.

Available options:

VIDEO,

IMAGE,

CAROUSEL,

TEXT

scheduled_at

When to publish, as an ISO 8601 date-time with a UTC offset (Unix time in milliseconds is also accepted). Must be at least 2 minutes in the future. Omit, or send null or an empty string, to save a draft. Alias: scheduledFor.

timezone

string

IANA time zone name, e.g. Europe/Berlin. Stored with the schedule for display; it does not change how scheduled_at is read.

settings

object

Per-platform options. Each account receives only the options for its own platform; accounts on other platforms ignore them. Any other key is rejected with 400.

Show child attributes

instagram

object

Same as settings.instagram. Ignored when settings.instagram is present.

Show child attributes

tiktok

object

Same as settings.tiktok. Ignored when settings.tiktok is present.

Show child attributes

youtube

object

Same as settings.youtube. Ignored when settings.youtube is present.

Show child attributes

object

Same as settings.pinterest. Ignored when settings.pinterest is present.

Show child attributes

google_business

object

Same as settings.google_business. Ignored when settings.google_business is present.

Show child attributes

external_id

string

Your own identifier for this request. With an API key and no Idempotency-Key header, its first 128 characters are used as the idempotency key. Not stored on the post.

Response

Post created

success

boolean

required

message

string

required

"Post scheduled" or "Post saved as draft".

data

object

required

Short form of a post returned by POST /posts. Uses lowercase values; GET /posts/{id} returns the full record.

Show child attributes

API documentation

CLI

User

Accounts

Posts

Generation status

Video generator

Image generator

Music generator

Voiceover

AI influencer

Thumbnail generator

Clipping

Uploads

Supported content

Media requirements

Before you post

Request body

Instagram reel cover

Platform settings (optional)

Response

Examples

Post lifecycle

Errors

Authorizations

Headers

Body

Response

​Supported content

​Media requirements

​Before you post

​Request body

​Instagram reel cover

​Platform settings (optional)

​Response

​Examples

​Post lifecycle

​Errors

Authorizations

Headers

Body

Response

Supported content

Media requirements

Before you post

Request body

Instagram reel cover

Platform settings (optional)

Response

Examples

Post lifecycle

Errors