Core concepts

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

Skill

A task-specific workflow an agent can run with UnifAPI MCP. A Skill starts from a desired output, such as a KOL pricing brief or creator shortlist, then lets the agent discover and call public-data operations when it needs evidence.

Skills are the recommended starting point for agent users. The API reference is the data layer behind them.

Provider

The public platform an API exposes data from — for example TikTok, Twitter/X, LinkedIn, YouTube, Reddit, or Instagram. Every provider has a top-level path prefix.

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

Operation

A single callable public-data endpoint inside a provider — for example GET /tiktok/videos/{id}. Every operation has its own page in the API reference, and MCP exposes operation discovery through list_operations and get_operation.

Canonical schemas

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 and hashtag ids are numeric-looking strings. TikTok user endpoints accept the public handle, numeric user id, or sec_uid where supported.

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

Public response envelope

Successful responses use the same top-level envelope:

{
  "request_id": "req_...",
  "data": {
    /* resource or list payload */
  },
  "pagination": {
    "cursor": "1711494099000",
    "has_more": true
  },
  "billing": {
    "credits_charged": 10,
    "records_charged": 10,
    "balance_remaining": 90,
    "truncated_due_to_balance": false
  }
}

• request_id — the UnifAPI request id for support and tracing.
• data — the business payload.
• pagination — present when a list operation can continue.
• billing — credits and records charged for the call.

Pagination

• pagination.has_more — true when at least one more page exists.
• pagination.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 sources use integer offsets, others use timestamps, others use page tokens. UnifAPI hides the variation. Don't try to parse pagination.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. OAuth MCP sessions, API keys, usage, and invoices all live at the workspace level. Invite teammates from the dashboard — they share the same keys and usage counter.

Public data boundary

UnifAPI serves public data. OAuth authorizes UnifAPI MCP access and workspace credits; it does not authorize private source accounts. If a workflow needs a user's private SaaS data, pair UnifAPI with a connector platform instead of treating UnifAPI as that OAuth integration layer.