> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Introducción a la API
> Autentícate en la API REST y empieza a construir
OurAiCalling expone una API REST bajo el dominio de tu plataforma. Todo lo que puedes hacer desde el Panel —gestionar asistentes, iniciar llamadas, ejecutar campañas, leer transcripciones— está disponible mediante programación.
## URL base
```text theme={null}
https://app.famulor.io/api/v1
```
`app.famulor.io` es la plataforma alojada. Si inicias sesión en un dominio de tenant de marca blanca, usa ese dominio: la API funciona bajo él con la marca del tenant y se aplican las mismas rutas.
## Autenticación
Todas las solicitudes requieren un token Bearer en el encabezado `Authorization`. Se aceptan dos tipos de tokens:
* **Claves de API** (`fam_...`) — créalas en **Configuración → Claves de API**. La clave completa se muestra una única vez al crearla; después solo se guarda un hash. Opcionalmente puedes restringir las claves a permisos concretos (por ejemplo, `assistants:read`, `calls:write`, `campaigns:write`, `dashboards:read`, `dashboards:write`, `leads:write`, `phone_numbers:write`, `sip_trunks:write`, `knowledge:write`, `voices:read`, `billing:read`) y asignarles una fecha de caducidad. Una clave sin restricciones de permisos tiene acceso completo; un permiso `*:write` incluye automáticamente el `*:read` correspondiente. Es la mejor opción para integraciones servidor a servidor. Los endpoints del Panel también aceptan `calls:read/write`, así que los clientes OAuth que usan los cuatro permisos estándar siguen siendo compatibles.
* **Tokens de acceso OAuth 2.0** (`fam_at_...`) — se emiten a través del flujo OAuth de la plataforma (authorization code + PKCE, registro dinámico de clientes). Tienen permisos acotados y vida corta (1 hora, con refresh tokens). Son la mejor opción para apps de terceros que actúan en nombre de un usuario.
```bash theme={null}
curl https://app.famulor.io/api/v1/assistants \
-H "Authorization: Bearer fam_XXXXXXXXXXXX"
```
Trata las claves de API como contraseñas. Nunca las incluyas en código del lado del cliente — para casos de uso en el navegador, usa el flujo OAuth.
## Estructura de la respuesta
Todos los endpoints devuelven una estructura JSON coherente. Las respuestas correctas envuelven el payload en `data` (más un `meta` opcional):
```json theme={null}
{
"data": [ { "id": "…", "name": "Support Agent" } ],
"meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } }
}
```
## Qué devuelve la API y qué no
La API REST y el endpoint MCP devuelven la misma vista deliberadamente curada de los datos de tu espacio de trabajo: todo lo que necesitas para construir, nada sobre cómo funciona la plataforma internamente.
No se incluye en ninguna respuesta:
* **Identificadores de infraestructura**: identificadores de sesión de medios, sala, troncal, enrutamiento y operador de la pila de telefonía subyacente.
* **Rutas de almacenamiento internas**: las grabaciones se sirven como URL firmada con caducidad (`GET /calls/{id}/recording`), nunca como ruta del bucket.
* **Costes de plataforma e interioridades de facturación**: costes de proveedores, contadores de tokens/caracteres/segundos y estado de los cargos. Tu propio consumo se informa en las unidades que se te facturan: minutos y créditos (`GET /balance`, `GET /transactions`).
* **Detalles internos de modelos**: qué modelo evaluó una llamada o escribió el resumen. Se devuelven el veredicto, la puntuación y el resumen, no el motor que los generó.
* **Secretos**: contraseñas, tokens y credenciales de operador nunca se pueden volver a leer una vez guardados; como máximo obtienes una pista enmascarada.
* **Diagnóstico operativo**: los eventos internos de llamada (conmutaciones de componentes, errores de sesión, registros de consumo) se filtran de los eventos de `GET /calls/{id}`.
Todo lo demás está a tu disposición: transcripciones, resúmenes, veredictos de análisis, campos extraídos, puntuaciones de QA, contactos, campañas, números y la configuración completa del asistente.
## Paginación
Los endpoints de listado se paginan con los parámetros de consulta `limit` y `offset`:
| Parámetro | Valor por defecto | Máximo | Descripción |
| --------- | ----------------- | ------ | ------------------ |
| `limit` | `50` | `200` | Tamaño de página |
| `offset` | `0` | — | Elementos a omitir |
El `meta.pagination.total` de la respuesta indica el número total de coincidencias (sin tener en cuenta `limit`/`offset`), así que puedes seguir paginando hasta que `offset + limit >= total`:
```bash theme={null}
curl "https://app.famulor.io/api/v1/calls?limit=100&offset=200" \
-H "Authorization: Bearer fam_XXXXXXXXXXXX"
```
## Errores
Los fallos devuelven una estructura de error con un `code` estable y legible por máquina, y un `message` legible para humanos:
```json theme={null}
{
"error": {
"code": "invalid_request",
"message": "\"to_number\" is required (E.164 format, e.g. +4930123456)."
}
}
```
| Estado | Código | Significado |
| ------ | ----------------- | ---------------------------------------------------------------------------------------------------- |
| `400` | `invalid_request` | Cuerpo o parámetros de la solicitud no válidos |
| `401` | `unauthorized` | Token ausente, no válido, caducado o revocado |
| `403` | `forbidden` | Falta el permiso necesario, o tu plan no incluye esta función |
| `404` | `not_found` | Recurso no encontrado (o no te pertenece) |
| `409` | `conflict` | El recurso está en un estado conflictivo (por ejemplo, detener una campaña que no está en ejecución) |
| `429` | `rate_limited` | Se superó el límite de solicitudes — reduce la frecuencia y vuelve a intentarlo |
| `500` | `internal_error` | Error inesperado del servidor |
## Límites de solicitudes
Se aplican límites de uso razonable por cuenta. Si los superas, la API responde con `429 Too Many Requests`; reduce la frecuencia y vuelve a intentarlo con un retraso exponencial. Los límites publicados por plan se documentarán aquí.
## MCP: usa la API como herramientas de IA
Todo lo que aparece en esta referencia también está disponible a través del **endpoint MCP** de la plataforma (Model Context Protocol, HTTP en streaming):
```text theme={null}
https://app.famulor.io/mcp
```
Conecta Claude, ChatGPT, Cursor o cualquier cliente MCP y usa las mismas funciones como herramientas de IA: los mismos servicios, la misma validación (límites del plan, catálogo de modelos, comprobaciones DNC) y el mismo modelo de permisos (claves de API u OAuth). Requiere la función de plan **Connect AI / MCP**. Guía de configuración completa: [endpoint MCP](/api/mcp).
**Conexión rápida** — Claude y ChatGPT descubren la autenticación automáticamente (OAuth); otros clientes pueden pasar una clave de API como encabezado Bearer estático:
```bash Claude Code theme={null}
claude mcp add --transport http voice-ai https://app.famulor.io/mcp \
--header "Authorization: Bearer fam_XXXXXXXXXXXX"
```
```json Cursor (~/.cursor/mcp.json) theme={null}
{
"mcpServers": {
"voice-ai": {
"url": "https://app.famulor.io/mcp",
"headers": { "Authorization": "Bearer fam_XXXXXXXXXXXX" }
}
}
}
```
```json mcp-remote (OAuth) theme={null}
{
"mcpServers": {
"voice-ai": {
"command": "npx",
"args": ["mcp-remote", "https://app.famulor.io/mcp"]
}
}
}
```
### Herramientas MCP disponibles
| Área | Herramientas |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Asistentes | `list_assistants`, `get_assistant`, `create_assistant`, `update_assistant`, `delete_assistant` |
| Voces | `get_voices` |
| Llamadas | `list_calls`, `get_call`, `make_call` |
| Historial | `list_history`, `get_email_history_item` |
| Configuración del espacio de trabajo | `list_email_senders`, `get_custom_domain`, `add_custom_domain`, `verify_custom_domain`, `remove_custom_domain`, `get_memory_settings`, `update_memory_settings` |
| Campañas | `list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `delete_campaign`, `start_campaign`, `stop_campaign` |
| Leads | `list_leads`, `add_lead`, `add_leads`, `delete_lead` |
| Números de teléfono | `list_phone_numbers`, `search_phone_numbers`, `buy_phone_number`, `release_phone_number`, `assign_phone_number` |
| Troncales SIP | `list_sip_trunks`, `get_sip_trunk`, `create_sip_trunk`, `delete_sip_trunk` |
| Bases de conocimiento | `list_knowledge_bases`, `get_knowledge_base`, `create_knowledge_base`, `delete_knowledge_base`, `add_document` |
| Cuenta y facturación | `get_balance`, `get_me`, `get_usage_summary` |