Docs
Conceito

Introdução - API

O TagServer expõe uma API HTTP que cobre os mesmos recursos que você gerencia no painel: contas, servidores de rastreamento, pixels e destinos de conversão, regras de tag, Smart Links, relatórios e dashboards de BI. Ela cobre também os fluxos (flowjutsu). Esta seção é a referência para integrar com o TagServer de forma programática.

Como a API se organiza

Os recursos são endereçados por nome, não por um id interno. Cada chamada com escopo de conta recebe a conta pelo nome, e servidores, links, parâmetros e fluxos seguem o mesmo padrão; o id inteiro de cada registro não aparece nas respostas.

As respostas seguem um envelope comum: um sucesso vem como { "Ok": <valor> } e um erro como { "Err": <mensagem> }. As convenções detalhadas, incluindo a concorrência otimista com ETag e If-Match, estão em Convenções e erros.

Autenticação

Um login (HTTP Basic com usuário e senha ou, se você entrou com login social pelo Google, um código de login de uso único) gera um user token, que gera um bearer token com escopo de conta enviado no header Authorization; o token prova o nível que cada rota exige (Owner, Admin, Standard ou ReadOnly), e algumas rotas também exigem um recurso (feature flag) habilitado na conta. O detalhe completo (como obter cada token, expiração, escopos e recursos por plano) está em Autenticação.

Onde a API vive (modelo multi-tenant)

As rotas ficam na raiz da autoridade do servidor, não sob um caminho-base global, e é essa autoridade que identifica o tenant. Ela é o hostname (host) resolvido a partir do server_name do TLS (SNI) e do header Host, que precisam concordar; se divergirem, a requisição é recusada.

O TagServer é multi-tenant na própria conexão: a identidade da conta pode chegar pelo certificado TLS da conexão, de forma independente do bearer token.

API ou MCP?

O TagServer também publica um MCP montado em /mcp, que espelha boa parte desta API como ferramentas para clientes de IA, como Claude Desktop e Claude Code, entre outros. As ferramentas com escopo de conta recebem a conta pelo nome, como nas chamadas REST; já as de documentação e skills (search_docs, search_skills, list_skills, load_skill) não são escopadas por conta.

Use a API REST quando a integração é programática e direta: um serviço seu falando HTTP com o TagServer. Use o MCP quando quem precisa operar a conta é uma IA. A autenticação também difere: o MCP não reaproveita a cadeia bearer da REST e tem porta de entrada OAuth própria. O catálogo ferramenta por ferramenta e o detalhe de autenticação do lado MCP estão em Referência de ferramentas MCP.

Veja também

AnteriorReferência das ferramentas MCPPróxima Início rápido