Especificación de la API

Respuesta directa

Contrato OpenAPI legible por máquinas y contrato de la API REST orientada al cliente para TextTree.

Contenido de la página

# Especificación de la API

TextTree publica un contrato estático OpenAPI 3.1 para la API REST actual:

- [OpenAPI JSON](/openapi.json)
- Servidor de producción: `https://api.texttree.ai`
- Servidor Phoenix local: `http://localhost:4001`

La especificación se basa en el mapa de rutas de Phoenix y en el registro del protocolo MCP. Está
pensada para revisión de clientes, generación de código y planificación de integraciones.

## Autenticación

Las solicitudes autenticadas de la API REST y de MCP requieren un token de acceso bearer emitido
por TextTree:

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

Los tokens de acceso bearer actuales comienzan con `txt_...` e incluyen scopes como
`messages:write`, `campaigns:read`, `campaigns:write`, `numbers:read`,
`numbers:write`, `onboarding:read`, `onboarding:write`, `mcp:read` y
`mcp:execute`.

Las claves de API heredadas `txk_...` se conservan como registros internos para flujos de trabajo
históricos. No son aceptadas por `/api/v1/messages`, `/api/v1/numbers`,
`/api/v1/campaigns`, `/mcp` ni `/mcp/tools`.

## Migración de claves heredadas

Si un cliente todavía tiene una clave heredada `txk_...`, cámbiala una sola vez por un token
bearer `txt_...` actual:

```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"}'
```

En caso de éxito, TextTree devuelve el nuevo token bearer una sola vez y revoca la clave
heredada. Si la creación del token falla, la clave heredada no se revoca.

## Superficies REST actuales

El archivo OpenAPI cubre:

- verificaciones de salud públicas
- arranque de cuentas headless
- encolamiento de mensajes salientes y consulta de estado
- rutas de campañas, snippets y listas de contactos
- rutas de listado y aprovisionamiento de números
- rutas programáticas de onboarding y financiamiento
- rutas de gestión de clientes OAuth de MCP
- registro OAuth, intercambio de tokens y revocación
- endpoints receptores de webhooks para proveedores de SMS y de financiamiento
- transporte JSON-RPC nativo de MCP y rutas REST heredadas de herramientas MCP

Para los detalles de los métodos nativos de MCP, usa los documentos de [compatibilidad MCP de OpenAI](/docs/openai-mcp/)
y de [MCP](/docs/mcp/). OpenAPI documenta los endpoints de transporte HTTP;
los descriptores y esquemas de herramientas MCP viven en los documentos de MCP porque se
devuelven a través de `tools/list` de JSON-RPC.

## Envolturas de error

La mayoría de las fallas de la API devuelven un objeto JSON con una cadena `error`:

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

Las fallas de scope incluyen el scope de ruta o de herramienta faltante:

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

Las fallas de validación incluyen detalles a nivel de campo:

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

## Idempotencia

`POST /api/v1/messages` acepta una `idempotency_key` opcional. Reutilizar la misma
clave con el mismo destinatario, cuerpo y costo devuelve el mensaje existente con
`"replayed": true`. Reutilizar la misma clave con un payload diferente devuelve
`409 idempotency_conflict`.

## Verificación

Las verificaciones públicas en vivo para este contrato son:

```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
```

El comportamiento de los endpoints autenticados está cubierto por las pruebas del controlador de
Phoenix y de MCP, porque este repositorio no usa tokens bearer de clientes ni de producción
para la verificación de la documentación.