Core concepts

A few words show up everywhere in UnifAPI. Learn them once and the rest of the docs read faster.

Provider

The upstream service an API exposes data from — TikTok today, and (roadmap) Instagram, YouTube, Google, etc. Every provider has a top-level path prefix.

https://api.unifapi.com/tiktok/...

Operation

A single callable endpoint inside a provider — for example GET /tiktok/videos/{id}. Every operation has its own page in the API reference.

Every operation that returns the same kind of resource — a Video, a User, a Comment — uses the same canonical schema. So GET /tiktok/videos/{id} and GET /tiktok/users/{id}/videos both return Video objects with identical field names and types.

The canonical shapes live in components.schemas of the OpenAPI spec and include: Video, Author, Music, MusicDetail, Comment, User, Hashtag, LiveRoom.

Identifiers

IDs are opaque strings. They look like long numbers, but treat them as strings to preserve precision (some are > 2^53).

TikTok user id (sec_uid) is a long base64 token, e.g. MS4wLjABAAAA....
TikTok video / music / hashtag / live ids are numeric-looking strings.

Resolve a username to a sec_uid with /tiktok/users/resolve?username=jennmelon. Resolve a share URL to a video with /tiktok/videos/resolve?url=....

List envelope and pagination

Every list endpoint returns the same envelope:

{
  "items": [/* ... */],
  "has_more": true,
  "next_cursor": "1711494099000"
}

items — the resource list.
has_more — true when at least one more page exists.
next_cursor — opaque string to pass back as ?cursor= for the next page. null when has_more is false.

The limit query parameter is capped at 50.

Cursors are deliberately opaque: some upstreams use integer offsets, others use timestamps, others use page tokens. UnifAPI hides the variation. Don't try to parse next_cursor.

Error envelope

All errors share a single nested envelope:

{ "error": { "type": "...", "message": "...", "request_id": "...", "issues": [/* validation only */] } }

error.type is a closed vocabulary (validation_error, not_found, unauthorized, ...). See Errors.

Workspace

The billing and access boundary. API keys, usage, and invoices all live at the workspace level. Invite teammates from the dashboard — they share the same keys and the same usage counter.