# Especificação da API

URL canônica: https://texttree.ai/pt-br/docs/api-spec/
URL em Markdown: https://texttree.ai/pt-br/docs/api-spec.md
Tipo de página: docs
Translation status: draft
Legal status: english_controls

## Resumo

Contrato OpenAPI legível por máquina e contrato API REST voltado para o cliente para TextTree.

## Conteúdo fonte

# Especificação da API

TextTree publica um contrato estático OpenAPI 3.1 para a API REST atual:

- [OpenAPI JSON](/openapi.json)
- Servidor de produção: `https://api.texttree.ai`
- Servidor Phoenix local: `http://localhost:4001`

A especificação é baseada no mapa de rotas Phoenix e no registro do protocolo MCP. É
destinado à revisão do cliente, geração de código e planejamento de integração.

## Autenticação

Solicitações autenticadas de API REST e MCP exigem a emissão de um token de acesso ao portador
por TextTree:

```http
Authorization: Bearer $TEXTREE_ACCESS_TOKEN
```

Os tokens de acesso ao portador atuais começam com `txt_...` e incluem escopos como
`messages:write`, `campaigns:read`, `campaigns:write`, `numbers:read`,
`numbers:write`, `onboarding:read`, `onboarding:write`, `mcp:read` e
`mcp:execute`.

As chaves de API herdadas `txk_...` são mantidas como registros internos para fluxos de trabalho
histórico. Eles não são aceitos por `/api/v1/messages`, `/api/v1/numbers`,
`/api/v1/campaigns`, `/mcp` ou `/mcp/tools`.

## Migração de chave legada

Se um cliente ainda tiver uma chave herdada `txk_...`, troque-a uma vez por um token
portador `txt_...` atual:

```bash
curl https://api.texttree.ai/api/v1/auth/migrate-legacy-key \
  -H "Authorization: Bearer $TEXTREE_LEGACY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production bearer token"}'
```

Em caso de sucesso, TextTree retorna o novo token ao portador uma vez e revoga a chave
herdado. Se a criação do token falhar, a chave herdada não será revogada.

## Superfícies REST atuais

O arquivo OpenAPI abrange:

- verificações de saúde pública
- inicialização de conta sem cabeça
- enfileiramento de mensagens de saída e consulta de status
- rotas de campanha, snippets e listas de contatos
- listagem de números e rotas de provisionamento
- integração programática e rotas de financiamento
- Rotas de gerenciamento de cliente MCP OAuth
- Registro OAuth, troca e revogação de tokens
- endpoints de recebimento de webhook para SMS e provedores de financiamento
- Transporte JSON-RPC nativo do MCP e rotas REST herdadas de ferramentas MCP

Para obter detalhes sobre métodos MCP nativos, use os documentos [Compatibilidade OpenAI MCP](/docs/openai-mcp/)
e de [MCP](/docs/mcp/). OpenAPI documenta endpoints de transporte HTTP;
Descritores e esquemas de ferramentas MCP residem em documentos MCP porque são
retornado via `tools/list` de JSON-RPC.

## Invólucros de erro

A maioria das falhas de API retorna um objeto JSON com uma string `error`:

```json
{
  "error": "unauthorized"
}
```

As falhas de escopo incluem caminho ou escopo de ferramenta ausente:

```json
{
  "error": "insufficient_scope",
  "required_scope": "messages:write"
}
```

As falhas de validação incluem detalhes em nível de campo:

```json
{
  "error": "validation_failed",
  "details": {
    "phone_number": ["should be at least 7 character(s)"]
  }
}
```

## Idempotência

`POST /api/v1/messages` aceita um `idempotency_key` opcional. Reutilize
chave com o mesmo destinatário, corpo e custo retorna a mensagem existente com
`"replayed": true`. Reutilizar a mesma chave com retornos de carga útil diferentes
`409 idempotency_conflict`.

## Verificação

As verificações públicas ao vivo para este contrato são:

```bash
curl https://api.texttree.ai/health
curl https://api.texttree.ai/api/v1/health
curl https://api.texttree.ai/mcp/health
curl https://api.texttree.ai/.well-known/oauth-protected-resource/mcp
curl https://api.texttree.ai/.well-known/oauth-authorization-server/mcp
```

O comportamento dos endpoints autenticados é abordado pelos testes de driver.
Phoenix e MCP, porque este repositório não usa tokens de cliente ou de produção
para verificação de documentação.