TikTok API
Postproxy publishes single videos and photo posts (up to 35 images) to a connected TikTok account.
Every request below uses the base URL https://api.postproxy.dev and an Authorization: Bearer YOUR_API_KEY header. Replace YOUR_API_KEY and the example IDs with your own.
Profiles and profile groups
Section titled “Profiles and profile groups”Every post targets one or more profiles. A profile is one connected account — for TikTok, a TikTok account. Reference one in a request by its id (the prof_abc123 in the examples below) or by the platform name "tiktok", which selects the group’s TikTok profile (a group holds at most one profile per platform). List what’s connected with GET /api/profiles.
Profiles live in profile groups — containers that organize the accounts for one brand, client, or project. List groups with GET /api/profile_groups, and connect a new TikTok profile with the Initialize Connection endpoint.
Example: get profiles and profile groups
List the profiles you can post to — GET /api/profiles:
curl -X GET "https://api.postproxy.dev/api/profiles" \ -H "Authorization: Bearer YOUR_API_KEY"{ "data": [ { "id": "prof_abc123", "name": "@mycompany", "platform": "tiktok", "status": "active", "profile_group_id": "grp_xyz789", "expires_at": null, "post_count": 47, "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof_abc123.jpg" } ]}List your profile groups — GET /api/profile_groups:
curl -X GET "https://api.postproxy.dev/api/profile_groups" \ -H "Authorization: Bearer YOUR_API_KEY"{ "data": [ { "id": "grp_xyz789", "name": "Main Brand", "profiles_count": 5 }, { "id": "grp_def456", "name": "Client Project", "profiles_count": 3 } ]}Connecting TikTok
Section titled “Connecting TikTok”TikTok connections — from the app, onboarding, an “Ask colleague” link, or POST /api/profile_groups/:id/initialize_connection — run through TikTok’s Business API. The profile is still platform: "tiktok", so nothing changes in how you address it in a request.
Profiles connected on or after 2026-09-30 get two things earlier TikTok connections can’t have:
- Comments — list, reply, delete, hide/unhide, like/unlike, and pin/unpin through the Comments API.
- Reach and watch time —
reachon post stats, watch-time metrics inraw_stats, and dailyprofile_views. - Custom video covers —
cover_url/cover_fileon video posts.thumb_offsetworks on every profile. - Commercial music — attach a track from TikTok’s Commercial Music Library with
audio_id.
Profiles connected before that date keep working exactly as they are, Reconnect included, but they don’t get comments or reach. To move one over, disconnect it and connect TikTok again — it comes back as a new profile, so re-point anything scheduled against the old one.
Accounts that bring their own TikTok app (Integrations → TikTok) keep connecting through that app.
One publishing difference on Business API profiles: TikTok publishes videos publicly, so privacy_status applies to photo posts only.
At a glance
Section titled “At a glance”| Platform ID | tiktok |
| Formats | video (default), image |
| Character limit | 2,200 |
| Media | Required |
| Comments | List, reply, delete, hide/unhide, like/unlike, pin/unpin — profiles connected on or after 2026-09-30, see Connecting TikTok |
| Music | Commercial Music Library tracks via audio_id — profiles connected on or after 2026-09-30, see Trending music |
| Direct messages | No |
| Post chains | No |
Publishing
Section titled “Publishing”Formats
Section titled “Formats”| Format | Description |
|---|---|
video | Single video (default) |
image | Photo post, up to 35 images |
| Parameter | Type | Required | Description |
|---|---|---|---|
format | string | No | "video" (default) |
upload_as_draft | boolean | No | Upload to the creator’s TikTok inbox instead of publishing. Defaults to false. See Draft uploads |
privacy_status | string | No | See privacy values; defaults to PUBLIC_TO_EVERYONE |
made_with_ai | boolean | No | Mark content as AI-generated. Defaults to false |
disable_comment | boolean | No | Disable comments on the post. Defaults to true — pass false to allow comments |
disable_duet | boolean | No | Disable Duets. Defaults to true — pass false to allow Duets |
disable_stitch | boolean | No | Disable Stitches. Defaults to true — pass false to allow Stitches |
brand_content_toggle | boolean | No | Paid partnership promoting a third-party business. Defaults to false |
brand_organic_toggle | boolean | No | Paid partnership promoting your own brand. Defaults to false |
cover_url / cover_file | string / file | No | Custom cover image for the video. JPG, PNG, or WebP, 360×360 to 1080×1920 px, up to 20 MB. Pass cover_url (URL) in JSON or cover_file (file) in multipart. Rejected with a 422 on profiles connected before 2026-09-30 — see Connecting TikTok |
thumb_offset | string | No | Frame of the video to use as the cover, in milliseconds. Ignored if cover_url is set. Works on every TikTok profile |
audio_id | string | No | Commercial music track to attach: a song_clip_id from Trending music. Profiles connected on or after 2026-09-30 only |
audio_volume | integer | No | Volume of the attached music, 0–100. Defaults to 50. Profiles connected on or after 2026-09-30 only |
video_volume | integer | No | Volume of the video’s own audio when audio_id is set, 0–100. Profiles connected on or after 2026-09-30 only |
strip_audio | boolean | No | Remove the video’s own audio track before publishing |
| Media | Max size | Formats | Count | Duration |
|---|---|---|---|---|
| Video | 4 GB | mp4, mov, av, webm | 1 | 3 s – 10 min |
- A video is required. Minimum dimensions: 720×1280 px.
# Video postcurl -X POST "https://api.postproxy.dev/api/posts" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "post": { "body": "Quick tip: Building APIs just got easier! 🚀" }, "profiles": ["prof_abc123"], "media": ["https://example.com/video.mp4"], "platforms": { "tiktok": { "privacy_status": "PUBLIC_TO_EVERYONE", "disable_comment": false, "made_with_ai": false } } }'| Parameter | Type | Required | Description |
|---|---|---|---|
format | string | Yes | "image" |
upload_as_draft | boolean | No | Upload to the creator’s TikTok inbox instead of publishing. Defaults to false. See Draft uploads |
privacy_status | string | No | See privacy values; defaults to PUBLIC_TO_EVERYONE |
photo_cover_index | integer | No | Index (0-based) of the cover photo. Defaults to 0 (first photo) |
auto_add_music | boolean | No | Add music automatically. Defaults to false |
audio_id | string | No | Commercial music track to attach: a song_clip_id from Trending music. Profiles connected on or after 2026-09-30 only |
disable_comment | boolean | No | Disable comments on the post. Defaults to true — pass false to allow comments |
brand_content_toggle | boolean | No | Paid partnership promoting a third-party business. Defaults to false |
brand_organic_toggle | boolean | No | Paid partnership promoting your own brand. Defaults to false |
| Media | Max size | Formats | Count | Duration |
|---|---|---|---|---|
| Image | 20 MB | jpg, gif | 35 | — |
# Photo postcurl -X POST "https://api.postproxy.dev/api/posts" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "post": { "body": "Swipe through our 2026 lookbook 📸" }, "profiles": ["prof_abc123"], "media": [ "https://example.com/photo1.jpg", "https://example.com/photo2.jpg" ], "platforms": { "tiktok": { "format": "image", "privacy_status": "PUBLIC_TO_EVERYONE", "photo_cover_index": 0, "auto_add_music": true } } }'Draft uploads
Section titled “Draft uploads”With upload_as_draft: true the media is sent to the creator’s TikTok inbox instead of being published. The creator opens the notification in the TikTok app and finishes the post there. On profiles connected before 2026-09-30, this is the only way to add a trending sound from TikTok’s music library; newer profiles can attach a Commercial Music Library track with audio_id instead. Works for both video and photo posts.
- Video drafts ignore every other TikTok parameter, including the post body. TikTok’s upload endpoint accepts the video file and nothing else; caption, privacy, Duet/Stitch and content disclosure are all chosen by the creator in the app.
- Photo drafts keep every parameter except
privacy_status, which the creator picks when publishing. - The platform entry reaches
status: "published"once TikTok confirms the media landed in the inbox — read that as delivered to the creator, not live on TikTok. permalinkstaysnulland no insights are collected: neither exists until the creator publishes the post themselves.- An
audio_idtrack is dropped from drafts. Publish directly to keep it.
# Video sent to the creator's draftscurl -X POST "https://api.postproxy.dev/api/posts" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "post": { "body": "" }, "profiles": ["prof_abc123"], "media": ["https://example.com/video.mp4"], "platforms": { "tiktok": { "upload_as_draft": true } } }'Trending music
Section titled “Trending music”GET /api/profiles/:profile_id/tiktok/trending_music
Lists trending tracks from TikTok’s Commercial Music Library. To attach one to a post, pass its song_clip_id as audio_id in the video or image parameters. Business accounts can only use the Commercial Music Library, which is cleared for commercial use; its catalog differs from the general sound library in the TikTok app.
| Parameter | Type | Required | Description |
|---|---|---|---|
genre | string | No | Genre filter, e.g. POP, ROCK, HIP_HOP/RAP, ELECTRONIC, JAZZ. Without one, all genres are ranked together |
date_range | string | No | Ranking window: 1DAY, 7DAY (default) or 30DAY |
country_code | string | No | ISO 3166-1 alpha-2 country whose chart to return. Defaults to US |
curl "https://api.postproxy.dev/api/profiles/prof_abc123/tiktok/trending_music?genre=POP&country_code=GB" \ -H "Authorization: Bearer YOUR_API_KEY"{ "data": [ { "commercial_music_id": "7584036660708460560", "commercial_music_name": "Sunset in Girona", "artist": "Noah Preminger & Max Light", "genres": ["JAZZ"], "duration": 281, "rank_position": "1", "thumbnail_url": "https://...", "preview_url": "https://...", "trending_history": [ { "date": "2026-11-02", "rank_position_daily": "1" } ], "full_duration_song_clip": { "song_clip_id": "7584037896080902145", "duration": 281, "preview_url": "https://..." }, "trending_song_clip": { "song_clip_id": "7584037896080918529", "duration": 19, "preview_url": "https://..." } } ]}Items use TikTok’s own field names. The response holds up to 100 tracks and is not paginated.
trending_song_clipis the short, popular part of the track andfull_duration_song_clipis the whole track. Eithersong_clip_idworks asaudio_id.durationis in seconds.trending_historygives the daily rank for recent days.
Attach the track when you publish:
# Video with a Commercial Music Library trackcurl -X POST "https://api.postproxy.dev/api/posts" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "post": { "body": "New drop 🎧" }, "profiles": ["prof_abc123"], "media": ["https://example.com/video.mp4"], "platforms": { "tiktok": { "format": "video", "audio_id": "7584037896080918529", "audio_volume": 80, "video_volume": 20 } } }'audio_volume(0–100, default50) sets the music andvideo_volume(0–100) sets the video’s own audio. To hear only the music, passvideo_volume: 0orstrip_audio: true.- Image posts take
audio_idonly. - Draft uploads drop the track.
| Status | Meaning |
|---|---|
400 | date_range is not 1DAY, 7DAY or 30DAY, or country_code is not a two-letter code |
403 | The connection lacks permission for the music library |
404 | Profile not found |
422 | Not a TikTok profile connected on or after 2026-09-30, the connection needs re-authentication, or TikTok rejected the request (e.g. an unknown genre) |
429 | TikTok is rate-limiting; retry after the Retry-After header |
Privacy status
Section titled “Privacy status”| Value | Visibility |
|---|---|
PUBLIC_TO_EVERYONE | Everyone |
MUTUAL_FOLLOW_FRIENDS | Mutual followers |
FOLLOWER_OF_CREATOR | Followers only |
SELF_ONLY | Private (only you) |
privacy_status is optional — omit it and the post defaults to PUBLIC_TO_EVERYONE. That default is only accepted for production-audited TikTok apps; unaudited or sandbox apps must send a non-public value (such as SELF_ONLY), or TikTok rejects the post.
On profiles connected on or after 2026-09-30, TikTok publishes videos publicly and privacy_status applies to photo posts only — see Connecting TikTok.
Comments
Section titled “Comments”The full Comments API works on TikTok videos and photo posts — for profiles connected on or after 2026-09-30 (see Connecting TikTok). Earlier connections return 405.
| Action | Endpoint |
|---|---|
| List comments and replies | GET /api/posts/:post_id/comments |
| Comment or reply | POST /api/posts/:post_id/comments |
| Delete | DELETE /api/posts/:post_id/comments/:id |
| Hide / unhide | POST .../hide / /unhide |
| Like / unlike | POST .../like / /unlike |
| Pin / unpin | POST .../pin / /unpin |
# Reply to a comment on a TikTok videocurl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments?profile_id=prof_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "body": "Thanks for watching!", "parent_id": "7412345678901234567" }'- Pinning: TikTok keeps one pinned comment per video, so pinning a second comment moves the pin. Pin state is returned as
platform_data.pinned. - Editing a comment isn’t possible — TikTok has no comment-edit API.
- New comments and replies arrive in real time and fire
comment.created; a comment deleted on TikTok drops out of the API. - Comment actions are asynchronous, as on every other network — the response is
{ "accepted": true }.
Direct messages
Section titled “Direct messages”Not supported.
Postproxy records periodic stat snapshots you can pull as a timeseries; field names pass through from TikTok unchanged.
Profile stats
Section titled “Profile stats”Account-level metrics, refreshed roughly every 23 hours via the Profile stats endpoint (GET /api/profiles/:id/stats).
Fields: follower_count, following_count, likes_count, video_count
# Fetch the profile stats timeseriescurl "https://api.postproxy.dev/api/profiles/prof_abc123/stats" \ -H "Authorization: Bearer YOUR_API_KEY"Post stats
Section titled “Post stats”Per-post engagement, captured after publish via the Post stats endpoint (GET /api/posts/stats). Requires the post to have a public ID.
Fields: impressions, likes, comments, shares, plus reach — the number of unique accounts that saw the video — on profiles connected on or after 2026-09-30.
On those profiles raw_stats also carries video_duration, average_time_watched, total_time_watched, and full_video_watched_rate, and GET /api/profiles/:id/daily_stats reports daily profile_views under platform_stats.
# Fetch post statscurl "https://api.postproxy.dev/api/posts/stats?post_ids=post_abc123&profiles=tiktok" \ -H "Authorization: Bearer YOUR_API_KEY"Webhooks
Section titled “Webhooks”Subscribe with the Webhooks API:
curl -X POST "https://api.postproxy.dev/api/webhooks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/postproxy", "events": ["platform_post.published", "platform_post.failed", "platform_post.insights"] }'Events relevant to TikTok:
| Event | When |
|---|---|
post.processed | A post is ready to publish |
platform_post.published | A post was published to the platform |
platform_post.failed | A post failed to publish (retries exhausted) |
platform_post.failed_waiting_for_retry | A publish attempt failed; will retry |
platform_post.insights | New analytics snapshot |
comment.created | A new comment or reply arrived on a TikTok post |
profile.connected / .disconnected | Connection state changed |
profile.stats | New profile stats snapshot |
media.failed | A media attachment failed to process |
What you can’t do
Section titled “What you can’t do”TikTok’s API doesn’t expose these features, so they aren’t available through Postproxy:
- Edit a post after it’s published
- Publish text-only posts — media is always required
- Edit a comment after posting it
- Send or read direct messages
- Go Live
- Create Duets or Stitches
- Apply effects or filters
- Use TikTok’s general sound library. Profiles connected on or after 2026-09-30 can attach Commercial Music Library tracks; otherwise use
auto_add_musicon photo posts, or send the post to drafts for the creator to finish in the app - Create playlists
- Read For You Page analytics
privacy_statusis optional and defaults toPUBLIC_TO_EVERYONE— see Privacy status for the audited-app caveat.- Videos must be at least 720×1280 px.
- Comments,
reach, and watch-time metrics need a profile connected on or after 2026-09-30 — see Connecting TikTok. upload_as_draft: truedelivers to the creator’s TikTok inbox rather than publishing — see Draft uploads.- When a post is a paid partnership, set
brand_content_toggle(third-party) orbrand_organic_toggle(own brand) as required by TikTok.