A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The TikTok API is how an app or AI agent works with a creator's TikTok account: reading their profile and follower stats, listing the videos they have posted, and publishing new videos or photos to their profile. Access is granted through OAuth 2.0, where the creator signs in and approves a set of scopes, and the resulting token reaches only what those scopes allow and only that creator's own account. The scopes that post content go through a TikTok review first, and TikTok can push events to a callback URL when a connection or a post changes.
How an app or AI agent connects to TikTok determines what it can reach. Access runs through a user access token from the OAuth 2.0 login flow, and the token carries only the scopes the user agreed to.
The v2 API answers at https://open.tiktokapis.com. A call carries a user access token in the Authorization header as a Bearer token, and the scopes on that token decide which methods it can reach. It covers user info, the creator's own videos, and content posting.
TikTok POSTs JSON events to a callback URL set in the developer portal, like authorization.removed when a user disconnects or video.publish.completed when a post finishes. Delivery is at-least-once, so the same event can arrive more than once, and the receiver returns 200 to acknowledge.
A separate, vetted track at https://open.tiktokapis.com for querying public TikTok data, including public videos and comments. It authenticates with a client access token and is open only to approved academic researchers in eligible regions.
A user signs in through TikTok's authorization page and grants a set of scopes, which the app exchanges for a user access token. The token reaches only what those scopes allow, and toggleable scopes let a user deny one while granting another. The token is refreshed through the same token endpoint.
The Research API uses a client access token, obtained from the token endpoint with the app's client_key and client_secret, rather than a user token. It reaches only public data and only the research.data scopes granted to an approved research application.
The TikTok API is split into areas an agent can act on, like a creator's profile, their own videos, and posting new content. Each method needs its own scope, and the scopes that post to a profile go through a separate app review before they work outside private mode.
Exchange an authorization code for a user access token, refresh it, and revoke a connection.
Read a creator's profile fields and statistics for the connected account.
List the connected creator's own videos and query specific videos by id.
Query creator settings, then directly post or upload videos and photos to the creator's account.
Query public comments and other public data through the vetted Research API.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
AuthorizationExchange an authorization code for a user access token, refresh it, and revoke a connection.2 | ||||||
| POST | /v2/oauth/token/ | Exchange an authorization code for a user access token, or refresh an existing token. | write | — | Current | |
Authenticated with the app's client_key and client_secret, not a user scope. The same endpoint mints a fresh access token from a refresh token. Sent as application/x-www-form-urlencoded. Acts onaccess token Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/oauth/revoke/ | Revoke a user access token and disconnect the app from the user's account. | write | — | Current | |
Authenticated with the app's client_key and client_secret. Revoking fires the authorization.removed webhook event. Acts onaccess token Permission (capability)None required VersionAvailable since the API’s base version Webhook event authorization-removedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
User infoRead a creator's profile fields and statistics for the connected account.1 | ||||||
| GET | /v2/user/info/ | Get the connected creator's profile fields, chosen through the fields query parameter. | read | user.info.basic | Current | |
user.info.basic returns open_id, union_id, avatar, and display_name. The profile_deep_link, bio_description, is_verified, and username fields additionally need user.info.profile. The follower_count, following_count, likes_count, and video_count fields additionally need user.info.stats. Acts onuser Permission (capability) user.info.basicVersionAvailable since the API’s base version Webhook eventNone Rate limit600 requests per minute per access token SourceOfficial documentation ↗ | ||||||
VideosList the connected creator's own videos and query specific videos by id.2 | ||||||
| POST | /v2/video/list/ | List the connected creator's own public videos, newest first, in pages. | read | video.list | Current | |
Returns only the connected creator's own videos, not other accounts. Paged with a cursor and a has_more flag, up to 20 videos per page. Acts onvideo Permission (capability) video.listVersionAvailable since the API’s base version Webhook eventNone Rate limit600 requests per minute per access token SourceOfficial documentation ↗ | ||||||
| POST | /v2/video/query/ | Query specific videos by their ids to confirm they belong to the connected creator and read their details. | read | video.list | Current | |
Up to 20 video ids per request, and only videos owned by the connected creator are returned. Acts onvideo Permission (capability) video.listVersionAvailable since the API’s base version Webhook eventNone Rate limit600 requests per minute per access token SourceOfficial documentation ↗ | ||||||
Content postingQuery creator settings, then directly post or upload videos and photos to the creator's account.5 | ||||||
| POST | /v2/post/publish/creator_info/query/ | Query the creator's posting settings, such as available privacy levels and interaction toggles, before posting. | read | video.publish | Current | |
Required before a direct post, so the app can render the privacy and interaction options TikTok mandates on the posting screen. Also accepted with video.upload for the upload flow. Acts oncreator info Permission (capability) video.publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/post/publish/video/init/ | Initialize a direct post of a video to the creator's TikTok profile. | write | video.publish | Current | |
Accepts the video by direct file upload or by a pre-verified pull-from-URL. Returns a publish_id to track. Until the app passes TikTok's content audit, posts are forced to private viewing only. Acts onvideo post Permission (capability) video.publishVersionAvailable since the API’s base version Webhook event video-publish-completedRate limit6 requests per minute per access token SourceOfficial documentation ↗ | ||||||
| POST | /v2/post/publish/inbox/video/init/ | Initialize an upload of a video to the creator's TikTok inbox as a draft to edit and post inside the app. | write | video.upload | Current | |
The creator finishes and publishes inside TikTok, rather than the app posting directly. Returns a publish_id and an upload_url valid for one hour. Acts onvideo upload Permission (capability) video.uploadVersionAvailable since the API’s base version Webhook event video-upload-failedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/post/publish/content/init/ | Initialize a photo post, either directly to the profile or as a draft, with up to 35 images. | write | video.publish | Current | |
The post_mode field selects DIRECT_POST, which needs video.publish, or MEDIA_UPLOAD, which needs video.upload. Photo URLs must be publicly accessible. Title is capped at 90 characters and description at 4,000. Acts onphoto post Permission (capability) video.publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/post/publish/status/fetch/ | Fetch the status of a post or upload by its publish_id. | read | video.publish | Current | |
Reports whether a post is processing, published, or failed. Accepted with video.publish or video.upload, matching the scope that started the post. Acts onpost status Permission (capability) video.publishVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ResearchQuery public comments and other public data through the vetted Research API.1 | ||||||
| POST | /v2/research/video/comment/list/ | List public comments on a video, or replies to a comment, through the Research API. | read | research.data.basic | Current | |
Part of the Research API, not the consumer Login Kit. Access is limited to approved academic researchers in eligible regions, and uses a client access token rather than a user token. There is no general comment.list scope for posting or moderating comments. Acts oncomment Permission (capability) research.data.basicVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TikTok can notify an app or AI agent when something happens to a connection, like a user removing authorization or a video finishing publishing. It posts a JSON event to a callback URL registered for the app, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
authorization.removed | Fires when a user deauthorizes the app, whether by their own action, account deletion, an age change, an account ban, or the developer revoking access. A reason code says which. | /v2/oauth/revoke/ |
video.publish.completed | Fires when a video posted through the Content Posting API has finished publishing on the creator's profile. | /v2/post/publish/video/init/ |
video.upload.failed | Fires when a video sent through the Content Posting API fails to process on the platform. | /v2/post/publish/inbox/video/init/ |
portability.download.ready | Fires when data requested through the Data Portability API has finished preparing and is ready to download. | In-app only |
TikTok limits how fast an app or AI agent can call, through a per-method request quota measured over a sliding window, with separate per-user ceilings on the posting endpoints.
TikTok meters each method against its own quota over a one-minute sliding window per user access token. The read endpoints for user info, the video list, and the video query allow about 600 requests per minute each. The direct-post initialization for content posting is far tighter, at about 6 requests per minute per token. Going over returns HTTP 429 with the error code rate_limit_exceeded. An app that needs higher limits can ask TikTok to review and raise them.
List endpoints are cursor-based. A response carries a cursor and a has_more flag, and the cursor is passed to the next request to fetch the following page. The video list returns up to 20 videos per page, set through max_count with a default of 10, and the video query takes up to 20 video ids in one request.
A photo post accepts up to 35 images, a title up to 90 characters, and a description up to 4,000 characters. An upload_url returned for a video upload is valid for one hour. Media must meet TikTok's format, resolution, and size requirements, and a pull-from-URL source must be publicly reachable.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_params | One or more fields in the request is invalid. | Correct the named fields against the method's reference and resend. |
| 400 | scope_permission_missed | The access token is missing a scope that some requested fields need, such as asking for stats fields without user.info.stats. | Request the missing scope in the authorization flow, or drop the fields that need it. |
| 400 | invalid_file_upload | The uploaded file does not meet the format, size, or chunking specification. | Check the file against the media requirements for the endpoint and re-upload. |
| 401 | access_token_invalid | The access token is invalid, expired, or not found in the request. | Refresh the token through the token endpoint and retry, or re-run the authorization flow. |
| 401 | scope_not_authorized | The user did not authorize the scope this request needs, often because the app has not passed review for that scope. | Add the scope to the authorization request, and complete app review where the scope requires it. |
| 429 | rate_limit_exceeded | The request exceeded the rate limit for the method. | Back off and retry after the window, and smooth the request rate. |
| 500 | internal_error | A generic error on TikTok's side. | Retry with backoff, and quote the log_id to TikTok support if it persists. |
TikTok groups its current developer platform under a single v2 namespace, replacing the retired v1 API, and ships dated changes through its changelog rather than minting new version numbers.
The v2 namespace is the current TikTok developer platform, served at open.tiktokapis.com, and it replaced the retired v1 API. It uses OAuth 2.0 through Login Kit for user access tokens and covers Login Kit, Display API methods for user info and the creator's own videos, the Content Posting API, and a separate Research API. There is no per-request version header; changes ship additively through the changelog.
The original v1 API and its older authorization page have been retired in favor of v2. Integrations on the v1 endpoints and the deprecated www.tiktok.com/auth/authorize/ flow were directed to migrate to the v2 namespace and the www.tiktok.com/v2/auth/authorize/ flow.
An integration calls the v2 endpoints directly; there is no per-request version header to pin.
TikTok API changelog ↗Bollard AI sits between a team's AI agents and TikTok. Grant each agent exactly the access it needs, read or write, scope by scope, and every call is checked and logged.