Posts

Create a post

Creates a draft, unless you send publish_at. A draft comes back with issues (anything that still needs fixing) and a review_url that opens it in Deploy. With publish_at it goes out now or at that time, and the video has to be ready.

post/posts

Request

  • Base URL: https://api.deploy.social/v1
  • URL: https://api.deploy.social/v1/posts
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Any unique string, like a UUID. Send the same request again with the same key within 24 hours and you get the first response back instead of a second post.

Example:5f0c7a1e-8d0b-4c0e-9d8a-1c2b3a4d5e6f

Request body

kind'video' | 'photos' | 'text'

video, photos or text. Defaults to video. New kinds may be added.

media_idstring

The video to post. Required when kind is video (the default); not used otherwise.

captionstring

The caption every destination uses unless it has its own. Required for a video post, up to 2,200 characters; optional for photos and text, up to 65,536 (the platform's own limit, checked when you post, may be shorter).

titlestring

YouTube's title. Video only.

descriptionstring

YouTube's description. Video only.

tagsstring[]

Tags, without the #. YouTube only, video only.

first_commentstring

Posted as the first comment where the platform takes one. Video only.

notify_emailboolean

Email the workspace when the post has gone out.

publish_atstring

When to post: "now", or a time with a timezone (like 2026-11-30T09:00:00-07:00), up to a year ahead.

Example request

{
  "media_id": "media_cmf3k0m2b0000ab12cd34ef56",
  "caption": "A quick look around the studio.",
  "title": "Studio update",
  "destinations": [
    {
      "destination_id": "dest_cmf3k1q7z0000ab12cd34ef56",
      "options": {
        "privacy": "public"
      }
    },
    {
      "destination_id": "dest_cmf3k1q7z0001ab12cd34ef56",
      "options": {
        "privacy": "public_to_everyone"
      }
    }
  ]
}

Response

The new post.

idstring required

The post's id. Starts with post_.

statusstring required

draft, scheduled, publishing, published, partially_published, failed or cancelled. New values may be added.

kindstring required

video, photos or text. New values may be added.

media_idstring nullable required

The video's id. Starts with media_.

captionstring required
titlestring nullable required
descriptionstring nullable required
tagsstring[] nullable required
first_commentstring nullable required
scheduled_atstring date-time nullable required

When it's set to go out.

notify_emailboolean required
created_viastring required

Where it was made: app (the web app), mobile (the phone app), api or mcp.

created_atstring date-time required

When it was created.

updated_atstring date-time required

When it last changed.

review_urlstring

Drafts only: opens the draft in Deploy, to check it over and post it from there.

Example response

{
  "id": "post_cmf3k2x9a0001ab12cd34ef56",
  "status": "scheduled",
  "kind": "video",
  "media_id": "media_cmf3k0m2b0000ab12cd34ef56",
  "media": [
    {
      "media_id": "media_cmf3k0m2b0000ab12cd34ef56"
    }
  ],
  "caption": "A quick look around the studio.",
  "scheduled_at": "2026-10-01T15:00:00.000Z",
  "created_via": "api",
  "created_at": "2026-10-01T15:00:00.000Z",
  "updated_at": "2026-10-01T15:00:00.000Z",
  "destinations": [
    {
      "destination_id": "dest_cmf3k1q7z0000ab12cd34ef56",
      "platform": "youtube",
      "handle": "northsidestudio",
      "options": {
        "privacy": "public"
      },
      "status": "published",
      "progress": {
        "phase": "uploading",
        "percent": 40
      },
      "published_at": "2026-10-01T15:00:00.000Z"
    }
  ],
  "issues": [
    {
      "path": "destinations[1].options.privacy",
      "code": "required",
      "message": "TikTok needs you to choose who can watch."
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.