Conceitos fundamentais

Algumas palavras aparecem em todos os lugares no UnifAPI. Aprenda-as uma vez e o resto da documentação fica mais fácil de ler.

Skill

Um fluxo de trabalho específico de cada tarefa que um agente pode executar com o UnifAPI MCP. Uma Skill parte de uma saída desejada, como um briefing de precificação de KOL ou uma shortlist de creators, e então deixa o agente descobrir e chamar operações de dados públicos quando precisa de evidências.

As Skills são o ponto de partida recomendado para usuários de agentes. A referência da API é a camada de dados por trás delas.

Provider

A plataforma pública da qual uma API expõe dados — por exemplo TikTok, Twitter/X, LinkedIn, YouTube, Reddit ou Instagram. Todo provider tem um prefixo de caminho de nível superior.

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

Operation

Um único endpoint de dados públicos chamável dentro de um provider — por exemplo GET /tiktok/videos/{id}. Toda operation tem sua própria página na referência da API, e o MCP expõe a descoberta de operations via list_operations e get_operation.

Schemas canônicos

Toda operation que retorna o mesmo tipo de recurso — um Video, um User, um Comment — usa o mesmo schema canônico. Então GET /tiktok/videos/{id} e GET /tiktok/users/{id}/videos retornam ambos objetos Video com nomes e tipos de campo idênticos.

As formas canônicas ficam em components.schemas da spec OpenAPI e incluem: Video, Author, Music, MusicDetail, Comment, User, Hashtag, LiveRoom.

Identificadores

Os IDs são strings opacas. Parecem números longos, mas trate-os como strings para preservar a precisão (alguns são > 2^53).

• O id de usuário do TikTok (sec_uid) é um token base64 longo, por exemplo MS4wLjABAAAA....
• Os ids de vídeo, música e hashtag do TikTok são strings que parecem numéricas. Os endpoints de usuário do TikTok aceitam o handle público, o id de usuário numérico ou o sec_uid onde houver suporte.

Resolva um username para um id de usuário estável com /tiktok/users/resolve?username=jennmelon. Resolva uma URL de compartilhamento para um vídeo com /tiktok/videos/resolve?url=....

Envelope público de resposta

As respostas bem-sucedidas usam o mesmo envelope de nível superior:

{
  "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 — o id de request do UnifAPI para suporte e rastreamento.
• data — o payload de negócio.
• pagination — presente quando uma operation de lista pode continuar.
• billing — créditos e registros cobrados pela chamada.

Paginação

• pagination.has_more — true quando existe pelo menos mais uma página.
• pagination.cursor — string opaca para passar de volta como ?cursor= para a próxima página. null quando has_more é false.

O parâmetro de query limit é limitado a 50.

Os cursors são deliberadamente opacos: algumas origens usam offsets inteiros, outras usam timestamps, outras usam tokens de página. O UnifAPI esconde a variação. Não tente fazer parse de pagination.cursor.

Envelope de erro

Todos os erros compartilham um único envelope aninhado:

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

error.type é um vocabulário fechado (validation_error, not_found, unauthorized, ...). Veja Erros.

Workspace

A fronteira de cobrança e acesso. Sessões MCP OAuth, API keys, uso e faturas vivem todos no nível do workspace. Convide colegas de equipe pelo dashboard — eles compartilham as mesmas chaves e o mesmo contador de uso.

Fronteira de dados públicos

O UnifAPI serve dados públicos. O OAuth autoriza o acesso MCP e os créditos do workspace do UnifAPI; ele não autoriza contas de origem privadas. Se um fluxo de trabalho precisar dos dados privados de SaaS de um usuário, combine o UnifAPI com uma plataforma de conectores em vez de tratar o UnifAPI como essa camada de integração OAuth.