Creator OSDocs

API resource

Posts

One post can go to several networks at once. Each entry in platforms carries its own status (pending, published, failed) and, once live, the network’s platformPostId and platformPostUrl.

Create a post

POST/v1/posts

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn. Post types vary by network (see the Post to all platforms guide).

Publish now, schedule (see Schedule a post), or save a draft. Name networks in platforms and Creator OS picks the connected account for each and applies every network’s formatting rules (Reels, Shorts, TikTok consent flags) for you.

For per-account control, pass objects instead: {"platform": "youtube", "account_id": "acc_...", "options": {"title": "..."}}. In that form any other post fields you send are passed through too: tags, threadItems, facebookSettings, instagramSettings, and queuedFromProfile: true to drop the post into your next open queue slot.

Networks you name that aren’t connected come back in missing_platforms; the rest still go out.

Body

contentstring

Caption or post text. Required unless media is given.

platformsstring[] | object[]required

Networks to post to, e.g. ["instagram","tiktok"], or target objects for full control.

mediastring[]

Media ids from Upload media (med_...) or public URLs. One video, or up to 10 images for a carousel.

post_typestring

text, image, carousel, short_video, long_video or story. Inferred from the media when omitted.

titlestring

Used where the network has titles (YouTube).

schedule_atISO 8601

Publish at this time. Omit to publish now.

timezoneIANA zone

Timezone for schedule_at, e.g. America/New_York. Defaults to UTC.

draftboolean

Save without publishing.

hashtagsstring[]

Hashtags to append.

coverstring

Video posts: a cover image (med_ id or public JPG/PNG URL). See Add a video cover.

cover_timestamp_msinteger

Video posts: use this frame as the cover instead (Instagram and TikTok).

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/posts" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Three hooks that doubled my watch time 👇",
    "platforms": [
      "instagram",
      "tiktok"
    ],
    "media": [
      "med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0"
    ],
    "schedule_at": "2026-10-02T18:00:00",
    "timezone": "America/New_York"
  }'
Response 201
{
  "id": "post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO",
  "content": "Three hooks that doubled my watch time 👇",
  "status": "scheduled",
  "scheduledFor": "2026-10-02T22:00:00.000Z",
  "timezone": "America/New_York",
  "platforms": [
    {
      "platform": "instagram",
      "accountId": {
        "id": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "platform": "instagram",
        "username": "kevbuildsapps"
      },
      "status": "pending"
    },
    {
      "platform": "tiktok",
      "accountId": {
        "id": "acc_Q3n1PvR8dKc0Zb7LwY4sHx2mJt9Eg6Ua5Nf1Ck8Tq3Vz",
        "platform": "tiktok",
        "username": "kevbuildsapps"
      },
      "status": "pending"
    }
  ],
  "mediaItems": [
    {
      "type": "video",
      "url": "https://creatoros-production-5658.up.railway.app/v1/media/med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0.mp4"
    }
  ],
  "createdAt": "2026-09-25T18:40:12.000Z"
}

Schedule a post

POST/v1/posts

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Same endpoint as Create a post, with schedule_at set. Creator OS publishes it at that moment on every network you named, so nothing on your side has to stay running. The post comes back with status scheduled; its per-network entries move to published (or failed) when the time comes.

Give schedule_at as a local time with timezone (as below), or as a UTC timestamp ending in Z. To move a scheduled post, use Update a post; to cancel it, Delete a post. Subscribe to the post.published and post.failed webhooks to hear back without polling.

Body

schedule_atISO 8601required

When to publish, e.g. 2026-10-02T18:00:00. Must be in the future.

timezoneIANA zone

Timezone for schedule_at, e.g. America/New_York. Defaults to UTC.

platformsstring[] | object[]required

Networks to post to.

contentstring

Caption or post text.

mediastring[]

Media ids from Upload media.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/posts" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New episode drops tonight 🎙️",
    "platforms": [
      "instagram",
      "tiktok",
      "youtube",
      "linkedin"
    ],
    "media": [
      "med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0"
    ],
    "title": "Episode 12: Hooks that work",
    "schedule_at": "2026-10-02T18:00:00",
    "timezone": "America/New_York"
  }'
Response 201
{
  "id": "post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO",
  "content": "New episode drops tonight 🎙️",
  "status": "scheduled",
  "scheduledFor": "2026-10-02T22:00:00.000Z",
  "timezone": "America/New_York",
  "platforms": [
    {
      "platform": "instagram",
      "accountId": {
        "id": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "platform": "instagram",
        "username": "kevbuildsapps"
      },
      "status": "pending"
    },
    {
      "platform": "tiktok",
      "accountId": {
        "id": "acc_Q3n1PvR8dKc0Zb7LwY4sHx2mJt9Eg6Ua5Nf1Ck8Tq3Vz",
        "platform": "tiktok",
        "username": "kevbuildsapps"
      },
      "status": "pending"
    }
  ],
  "mediaItems": [
    {
      "type": "video",
      "url": "https://creatoros-production-5658.up.railway.app/v1/media/med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0.mp4"
    }
  ],
  "createdAt": "2026-09-25T18:40:12.000Z"
}

Add a video cover

POST/v1/posts

Works on: Instagram (Reels), TikTok, Facebook (videos and Reels), LinkedIn (videos), YouTube (long videos). Not X, Threads or YouTube Shorts.

Upload the cover image with Upload media, then pass its id as cover on any video post (short or long). Every network stores covers somewhere different; Creator OS sends the one image to each of them: the Reel cover on Instagram, the cover image on TikTok, and the video thumbnail on Facebook, LinkedIn and YouTube.

Use JPG or PNG, 2 MB at most (YouTube’s limit), 1080 x 1920 for vertical video. YouTube only takes custom thumbnails on long videos from phone-verified channels; Shorts, X and Threads pick their own frame. On an unsupported network the post still goes out, just without your cover.

To pick a frame of the video instead of an image, send cover_timestamp_ms (Instagram and TikTok). With per-account targets, you can also set thumbnail on a single media item: {"url": "med_...", "thumbnail": "med_..."}.

Body

coverstring

A med_ id from Upload media, or a public JPG/PNG URL.

cover_timestamp_msinteger

Frame of the video to use as the cover, in milliseconds. Ignored when cover is set.

platformsstring[] | object[]required

Networks to post to.

mediastring[]required

The video, as a med_ id or public URL.

contentstring

Caption.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/posts" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The full breakdown 🎬",
    "platforms": [
      "instagram",
      "tiktok",
      "facebook"
    ],
    "media": [
      "med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0"
    ],
    "cover": "med_Qx4Tn8Lb2Wd6Hs0Rv3Kc7Jm1Pf5Gy9Ze4Au8Oi2Ns6"
  }'
Response 201
{
  "id": "post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO",
  "content": "Three hooks that doubled my watch time 👇",
  "status": "scheduled",
  "scheduledFor": "2026-10-02T22:00:00.000Z",
  "timezone": "America/New_York",
  "platforms": [
    {
      "platform": "instagram",
      "accountId": {
        "id": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "platform": "instagram",
        "username": "kevbuildsapps"
      },
      "status": "pending"
    },
    {
      "platform": "tiktok",
      "accountId": {
        "id": "acc_Q3n1PvR8dKc0Zb7LwY4sHx2mJt9Eg6Ua5Nf1Ck8Tq3Vz",
        "platform": "tiktok",
        "username": "kevbuildsapps"
      },
      "status": "pending"
    }
  ],
  "mediaItems": [
    {
      "type": "video",
      "url": "https://creatoros-production-5658.up.railway.app/v1/media/med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0.mp4"
    }
  ],
  "createdAt": "2026-09-25T18:40:12.000Z"
}

List posts

GET/v1/posts

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Your queue and history, newest scheduled first.

Query parameters

statusstring

draft, scheduled, published or failed.

platformstring

Only posts that include this network.

fromDateYYYY-MM-DD

Scheduled or published on or after this date.

toDateYYYY-MM-DD

Scheduled or published on or before this date.

searchstring

Match text in the caption.

pageinteger

Page number, starting at 1.

limitinteger

Page size.

curl "https://creatoros-production-5658.up.railway.app/v1/posts?status=scheduled&limit=20" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "posts": [
    {
      "id": "post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO",
      "content": "Three hooks that doubled my watch time 👇",
      "status": "scheduled",
      "scheduledFor": "2026-10-02T22:00:00.000Z",
      "timezone": "America/New_York",
      "platforms": [
        {
          "platform": "instagram",
          "accountId": {
            "id": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
            "platform": "instagram",
            "username": "kevbuildsapps"
          },
          "status": "pending"
        },
        {
          "platform": "tiktok",
          "accountId": {
            "id": "acc_Q3n1PvR8dKc0Zb7LwY4sHx2mJt9Eg6Ua5Nf1Ck8Tq3Vz",
            "platform": "tiktok",
            "username": "kevbuildsapps"
          },
          "status": "pending"
        }
      ],
      "mediaItems": [
        {
          "type": "video",
          "url": "https://creatoros-production-5658.up.railway.app/v1/media/med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0.mp4"
        }
      ],
      "createdAt": "2026-09-25T18:40:12.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Retrieve a post

GET/v1/posts/{postId}

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

One post with the live status of every network it targets. Poll this after publishing to confirm each network went through.

Path parameters

postIdstringrequired

The post_ id.

curl "https://creatoros-production-5658.up.railway.app/v1/posts/post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "id": "post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO",
  "content": "Three hooks that doubled my watch time 👇",
  "status": "published",
  "scheduledFor": "2026-10-02T22:00:00.000Z",
  "timezone": "America/New_York",
  "platforms": [
    {
      "platform": "instagram",
      "accountId": {
        "id": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "platform": "instagram",
        "username": "kevbuildsapps"
      },
      "status": "published",
      "platformPostId": "18053924711234567",
      "platformPostUrl": "https://www.instagram.com/reel/C9xYz/",
      "publishedAt": "2026-10-02T22:00:04.000Z"
    }
  ],
  "mediaItems": [
    {
      "type": "video",
      "url": "https://creatoros-production-5658.up.railway.app/v1/media/med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0.mp4"
    }
  ],
  "createdAt": "2026-09-25T18:40:12.000Z"
}

Update a post

PATCH/v1/posts/{postId}

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Change a draft, scheduled or failed post: caption, time, media, cover or networks. It takes the same field names as Create a post, and only the fields you send change. For posts that are already live, use Edit a published post.

Giving a draft a schedule_at (or publish_now: true) schedules it; send draft: true as well to keep it a draft. media replaces the post’s media; platforms replaces its networks.

Path parameters

postIdstringrequired

The post_ id.

Body

contentstring

New caption.

schedule_atISO 8601

New publish time. Schedules a draft.

timezoneIANA zone

Timezone for schedule_at.

mediastring[]

Replacement media: med_ ids or public URLs.

coverstring

Video posts: new cover image (med_ id or URL), placed on every network that supports one.

cover_timestamp_msinteger

Video posts: use this frame as the cover (Instagram and TikTok).

platformsobject[]

Replacement targets: [{ platform, account_id, options }].

draftboolean

true keeps (or makes) it a draft; false schedules or publishes it.

publish_nowboolean

Publish immediately instead of at the scheduled time.

curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/posts/post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_at": "2026-10-03T18:00:00",
    "timezone": "America/New_York",
    "cover": "med_Qx4Tn8Lb2Wd6Hs0Rv3Kc7Jm1Pf5Gy9Ze4Au8Oi2Ns6"
  }'
Response 200
{
  "id": "post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO",
  "content": "Three hooks that doubled my watch time 👇",
  "status": "scheduled",
  "scheduledFor": "2026-10-03T22:00:00.000Z",
  "timezone": "America/New_York",
  "platforms": [
    {
      "platform": "instagram",
      "accountId": {
        "id": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "platform": "instagram",
        "username": "kevbuildsapps"
      },
      "status": "pending"
    },
    {
      "platform": "tiktok",
      "accountId": {
        "id": "acc_Q3n1PvR8dKc0Zb7LwY4sHx2mJt9Eg6Ua5Nf1Ck8Tq3Vz",
        "platform": "tiktok",
        "username": "kevbuildsapps"
      },
      "status": "pending"
    }
  ],
  "mediaItems": [
    {
      "type": "video",
      "url": "https://creatoros-production-5658.up.railway.app/v1/media/med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0.mp4"
    }
  ],
  "createdAt": "2026-09-25T18:40:12.000Z"
}

Delete a post

DELETE/v1/posts/{postId}

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Deletes a draft or scheduled post. To take down something already published, use Unpublish.

Path parameters

postIdstringrequired

The post_ id.

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/posts/post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "message": "Post deleted successfully"
}

Retry failed networks

POST/v1/posts/{postId}/retry

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Re-attempts every network that failed on this post. Networks that already published are left alone.

Path parameters

postIdstringrequired

The post_ id.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/posts/post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO/retry" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response 200
{
  "message": "Retry initiated",
  "post": {
    "id": "post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO",
    "status": "scheduled"
  }
}

Edit a published post

POST/v1/posts/{postId}/edit

Works on: X (Premium accounts, within 1 hour), Facebook, LinkedIn, YouTube (description only)

Changes the text of a post that is already live, without deleting it. Media can’t be swapped. X gives the edited post a new id; the other networks keep it.

Path parameters

postIdstringrequired

The post_ id.

Body

platformstringrequired

twitter, facebook, linkedin or youtube.

contentstringrequired

The new text.

accountIdstring

Which account’s copy to edit when the post went to several accounts on the same network.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/posts/post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO/edit" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "content": "Three hooks that doubled my watch time (updated with a fourth!) 👇"
  }'
Response 200
{
  "success": true,
  "message": "Post updated on linkedin"
}

Unpublish a post

POST/v1/posts/{postId}/unpublish

Works on: Facebook, X, Threads, LinkedIn, YouTube (not Instagram or TikTok)

Deletes a published post from one network. The post stays in Creator OS with status cancelled. Call once per network. On YouTube the deletion is permanent.

Path parameters

postIdstringrequired

The post_ id.

Body

platformstringrequired

facebook, twitter, threads, linkedin or youtube.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/posts/post_3JSJJWvgHKZH-Vjy_ggeP792GJbvjQ1pZzbqlPEgKJOO/unpublish" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "facebook"
  }'
Response 200
{
  "success": true,
  "message": "Post deleted from facebook"
}
PreviousAccountsNextMedia