# Referencia de la API

URL canónica: https://texttree.ai/es-419/docs/api-reference/
URL de Markdown: https://texttree.ai/es-419/docs/api-reference.md
Tipo de página: docs
Translation status: draft
Legal status: english_controls

## Resumen

Referencia indexable para SEO de las APIs de mensajes, números, webhooks, contactos y facturación de TextTree.

## Contenido de la página

## Autenticación

Usa un token de acceso bearer `txt_...` emitido por TextTree. Los tokens deben incluir el
scope requerido por la ruta, como `messages:write`, `numbers:read`,
`numbers:write`, `mcp:read` o `mcp:execute`. Las claves de API heredadas `txk_...` no
son aceptadas por las rutas de la API para desarrolladores ni por las rutas MCP.

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

## Crear una cuenta headless

```http
POST /api/v1/accounts
POST /mcp/accounts
```

Estos endpoints JSON públicos crean una cuenta de agente con nombre de usuario y contraseña sin
correo electrónico, OAuth de Google ni autenticación con billetera. Ambas rutas invocan el mismo flujo
de arranque y devuelven códigos de respaldo de un solo uso más un token bearer `txt_...` de
TextTree.

Campos requeridos:

- `username`
- `password`

`/api/v1/accounts` acepta los campos en el nivel superior. `/mcp/accounts` acepta los
mismos campos en el nivel superior o anidados dentro de `account`.

### curl

```bash
curl https://api.texttree.ai/api/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent-demo",
    "password": "correct horse battery staple"
  }'
```

Respuesta:

```json
{
  "account": {
    "id": "9d7d9df7-58a0-4716-b82e-7ad5e73f7b36",
    "username": "agent-demo"
  },
  "backup_codes": ["AAAA-BBBB-CCCC-DDDD"],
  "token": {
    "type": "Bearer",
    "access_token": "txt_...",
    "scopes": ["mcp:read", "mcp:execute", "messages:write"],
    "expires_at": "2026-06-03T15:30:00Z"
  }
}
```

El arranque de cuentas está limitado a una creación de cuenta exitosa por dirección IP
cada cinco minutos. Los intentos de creación exitosa repetidos devuelven
`429 account_creation_rate_limited` con `retry_after_seconds`.

## Enviar SMS

```http
POST /api/v1/messages
```

Campos requeridos:

- `phone_number`
- `body`

Campos opcionales:

- `idempotency_key`
- `metadata`

Los envíos por API usan selección automática de remitente. Los envíos originados en la app pueden
seleccionar un número de marca conectado; TextTree trata al remitente seleccionado como parte de la
solicitud de mensaje idempotente.

### curl

```bash
curl https://api.texttree.ai/api/v1/messages \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "body": "Your appointment is tomorrow at 9 AM.",
    "idempotency_key": "appointment-123-reminder"
  }'
```

### JavaScript

```js
const response = await fetch("https://api.texttree.ai/api/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TEXTREE_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+15551234567",
    body: "Your appointment is tomorrow at 9 AM.",
    idempotency_key: "appointment-123-reminder",
  }),
});

const { message } = await response.json();
```

### Python

```py
import os
import requests

response = requests.post(
    "https://api.texttree.ai/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['TEXTREE_ACCESS_TOKEN']}"},
    json={
        "phone_number": "+15551234567",
        "body": "Your appointment is tomorrow at 9 AM.",
        "idempotency_key": "appointment-123-reminder",
    },
    timeout=10,
)

message = response.json()["message"]
```

### Elixir

```elixir
Mix.install([:req])

%{body: %{"message" => message}} =
  Req.post!(
    "https://api.texttree.ai/api/v1/messages",
    auth: {:bearer, System.fetch_env!("TEXTREE_ACCESS_TOKEN")},
    json: %{
      phone_number: "+15551234567",
      body: "Your appointment is tomorrow at 9 AM.",
      idempotency_key: "appointment-123-reminder"
    }
  )
```

Respuesta:

```json
{
  "message": {
    "id": "msg_123",
    "status": "queued"
  }
}
```

## Estado del mensaje

```http
GET /api/v1/messages/{id}
```

### curl

```bash
curl https://api.texttree.ai/api/v1/messages/msg_123 \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN"
```

Respuesta:

```json
{
  "message": {
    "id": "msg_123",
    "status": "delivered",
    "phone_number": "+15551234567",
    "segments": 1,
    "cost_cents": 1,
    "created_at": "2026-04-28T14:00:00Z"
  }
}
```

Usa la página de Mensajes para depurar la línea de tiempo, los webhooks y las fallas.

Reutilizar una `idempotency_key` con un destinatario, cuerpo, costo o remitente seleccionado
diferente devuelve un conflicto de idempotencia.

## Números de teléfono

```http
GET /api/v1/numbers
POST /api/v1/numbers
```

`GET` requiere `numbers:read`. `POST` requiere `numbers:write` y compra un
número a través del límite del proveedor de mensajería de TextTree. `area_code` es compatible
para la intención de compra de números locales. Las compras en vivo requieren la barrera de protección
explícita de compra de números en vivo del despliegue.

```bash
curl https://api.texttree.ai/api/v1/numbers \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "area_code": "415",
    "friendly_name": "Support line"
  }'
```

Respuesta:

```json
{
  "number": {
    "id": "num_123",
    "number": "+14155550123",
    "friendly_name": "Support line",
    "status": "connected",
    "compliance_status": "pending"
  },
  "webhook_configured": false,
  "warning": "provider_inbound_webhook_configuration_api_not_documented"
}
```