TikTok

​

Quick reference

​

Connect an account

1. Calls GET /v2/user/info/ to pin platformAccountId to the real TikTok open_id.
2. Calls POST /v2/post/publish/creator_info/query/ to snapshot the privacy allowlist; accounts with only SELF_ONLY are flagged as auditState: "audit" and the publisher forces SELF_ONLY on every post until that flips.

​

Scopes

user.info.basic     — required to mint platform_account_id at connect
video.upload        — upload-inbox path (push_by_file)

​

Token lifecycle

​

Post a video

{
  "targets": [
    {
      "accountId": "...",
      "options": {
        "platform": "tiktok",
        "privacy": "self_only",
        "disableComment": false,
        "disableDuet": false,
        "disableStitch": false
      }
    }
  ],
  "text": "Walkthrough #demo",
  "media": [{ "kind": "video", "mediaId": "med_…" }]
}

​

Privacy

​

Branded content

​

Code samples

curl https://api.letmepost.dev/v1/posts \
  -H "Authorization: Bearer lmp_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      {
        "accountId": "acc_…",
        "options": { "platform": "tiktok", "privacy": "self_only" }
      }
    ],
    "text": "Walkthrough #demo",
    "media": [{ "kind": "video", "mediaId": "med_…" }]
  }'

import { Letmepost } from "@letmepost/sdk";

const lmp = new Letmepost({ apiKey: process.env.LETMEPOST_API_KEY! });

await lmp.posts.create({
  targets: [
    {
      accountId: "acc_…",
      options: { platform: "tiktok", privacy: "self_only" },
    },
  ],
  text: "Walkthrough #demo",
  media: [{ kind: "video", mediaId: "med_…" }],
});

from letmepost import Letmepost

lmp = Letmepost(api_key=os.environ["LETMEPOST_API_KEY"])

lmp.posts.create(
    targets=[
        {
            "accountId": "acc_…",
            "options": {"platform": "tiktok", "privacy": "self_only"},
        }
    ],
    text="Walkthrough #demo",
    media=[{"kind": "video", "mediaId": "med_…"}],
)

client := letmepost.New(os.Getenv("LETMEPOST_API_KEY"))

client.Posts.Create(ctx, letmepost.CreatePostRequest{
    Targets: []letmepost.PostTarget{{
        AccountID: "acc_…",
        Options: &letmepost.TargetOptions{
            Platform: "tiktok",
            Privacy:  "self_only",
        },
    }},
    Text:  "Walkthrough #demo",
    Media: []letmepost.MediaInput{{Kind: "video", MediaID: "med_…"}},
})

​

How publishing works under the hood

1. Calls POST /v2/post/publish/inbox/video/init/ with source: "FILE_UPLOAD", video_size, chunk_size, total_chunk_count. Returns upload_url + publish_id.
2. PUTs the video bytes to upload_url. Files under 64 MiB go in one request; larger files chunk at 10 MiB with explicit Content-Range headers.
3. Returns status: "publishing" with the publish_id stamped on cid so the caller can correlate by id.
4. A BullMQ worker polls POST /v2/post/publish/status/fetch/ on a bucketed schedule (5 s → 30 s → 2 min) until TikTok reaches a terminal state.
5. Terminal PUBLISH_COMPLETE → post.published webhook with the public TikTok URL. Terminal FAILED → post.failed with the upstream reason. The 30-minute deadline turns into post.failed with tiktok.publish.pending.

​

Wisdom (platform-specific things that bite)

​

Common errors

​

What you can’t do (yet)

• Photo carousels (unaudited apps).
• Direct Post (public publishing without user confirmation) until video.publish clears review.
• pull_by_url uploads (domain verification gate).
• Reading post engagement, comments, or analytics.
• TikTok Live, Shop, DMs.

​

API reference

• POST /v1/posts — primary publish.
• POST /v1/media — upload video bytes for mediaId references.
• POST /v1/accounts/connect/tiktok — start a TikTok OAuth flow.