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

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 }
  ]
}

At a glance


Platform ID	`tiktok`
Formats	`video` (default), `image`
Character limit	2,200
Media	Required
Comments	No (can be disabled per post)
Direct messages	No
Post chains	No

Publishing

Formats

Format	Description
`video`	Single video (default)
`image`	Photo post, up to 35 images

Video

Parameter	Type	Required	Description
`format`	string	No	`"video"` (default)
`privacy_status`	string	No	See privacy values; defaults to `PUBLIC_TO_EVERYONE`
`made_with_ai`	boolean	No	Mark content as AI-generated
`disable_comment`	boolean	No	Disable comments on the post
`disable_duet`	boolean	No	Disable Duets
`disable_stitch`	boolean	No	Disable Stitches
`brand_content_toggle`	boolean	No	Paid partnership promoting a third-party business
`brand_organic_toggle`	boolean	No	Paid partnership promoting your own brand

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 post
curl -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
         }
       }
     }'

Image

Parameter	Type	Required	Description
`format`	string	Yes	`"image"`
`privacy_status`	string	No	See privacy values; defaults to `PUBLIC_TO_EVERYONE`
`photo_cover_index`	integer	No	Index (0-based) of the cover photo
`auto_add_music`	boolean	No	Add music automatically
`disable_comment`	boolean	No	Disable comments on the post
`brand_content_toggle`	boolean	No	Paid partnership promoting a third-party business
`brand_organic_toggle`	boolean	No	Paid partnership promoting your own brand

Media	Max size	Formats	Count	Duration
Image	20 MB	jpg, gif	35	—

# Photo post
curl -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
         }
       }
     }'

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.

Comments

The Comments API does not support TikTok. You can, however, disable comments on a post at publish time with disable_comment: true.

Direct messages

Not supported.

Stats

Postproxy records periodic stat snapshots you can pull as a timeseries; field names pass through from TikTok unchanged.

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 timeseries
curl "https://api.postproxy.dev/api/profiles/prof_abc123/stats" \
     -H "Authorization: Bearer YOUR_API_KEY"

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

# Fetch post stats
curl "https://api.postproxy.dev/api/posts/stats?post_ids=post_abc123&profiles=tiktok" \
     -H "Authorization: Bearer YOUR_API_KEY"

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
`profile.connected` / `.disconnected`	Connection state changed
`profile.stats`	New profile stats snapshot
`media.failed`	A media attachment failed to process

Notes

privacy_status is optional and defaults to PUBLIC_TO_EVERYONE — see Privacy status for the audited-app caveat.
Videos must be at least 720×1280 px.
When a post is a paid partnership, set brand_content_toggle (third-party) or brand_organic_toggle (own brand) as required by TikTok.