Introducción a la API

La API REST de Famulor te permite gestionar los mismos recursos de cliente disponibles en el panel, incluidos asistentes, llamadas, campañas, transcripciones, conocimiento y configuración del espacio de trabajo.

Para un proceso de negocio de varios pasos — enriquecer un lead, luego llamar, luego actualizar un CRM, luego avisar en un canal — una automatización suele requerir menos código de mantenimiento que conectar los pasos tú mismo. Recurre directamente a la API cuando necesites un control programático simple e inmediato, como disparar una única llamada desde tu propia app.

URL base

https://app.famulor.io/api/v1

Si usas un dominio de marca blanca, sustituye app.famulor.io por ese dominio. Las rutas son las mismas.

Acceso a la API

Las solicitudes REST requieren API Access mediante el plan del espacio de trabajo o un complemento recurrente. Si se retira el acceso, las claves de API y credenciales OAuth existentes siguen disponibles para que los administradores del espacio las revisen y revoquen, pero las solicitudes normales a /api/v1 devuelven 403 api_access_required. Después de un pago de plan fallido, POST /api/v1/billing/invoice-payment y POST /api/v1/billing/portal siguen disponibles con una credencial válida para que un propietario pueda recuperar la facturación. Las comprobaciones de autenticación, rol y alcance siguen aplicándose.

Autenticación

Envía un token Bearer en el encabezado Authorization:

curl https://app.famulor.io/api/v1/assistants \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Se admiten dos tipos de credencial:

Workspace API keys (fam_...) — créalas en Settings → API & MCP para integraciones de servidor a servidor. La clave completa se muestra una sola vez. El panel no tiene selector de alcances, así que una clave creada ahí siempre lleva todos los alcances. Para generar una clave más restringida, llama a POST /api/v1/api-keys o POST /api/v1/workspaces/{workspace_id}/api-keys con un array scopes explícito — los alcances de la nueva clave deben ser un subconjunto de los de la credencial que la crea.
OAuth 2.0 access tokens (fam_at_...) — usa Authorization Code con PKCE-S256 para aplicaciones que actúan en nombre de un usuario con sesión iniciada.

El acceso autorizado por un usuario sigue su pertenencia y su rol actuales en el espacio de trabajo. Las claves de API del espacio de trabajo siguen su propio estado y alcances hasta que un administrador autorizado del espacio las revoque.

Trata las claves de API como contraseñas. Nunca las incluyas en código de navegador o de aplicaciones móviles; usa OAuth para aplicaciones orientadas al usuario final.

Higiene de las claves

Guarda las claves en variables de entorno o en un gestor de secretos, nunca en el control de versiones.
Limita el alcance de cada clave a lo que necesite la integración — una clave que solo lee llamadas no debería tener también assistants:write. Las claves creadas desde el panel siempre tienen acceso completo; usa el método de la API anterior para generar una con alcance limitado.
Rota las claves periódicamente, y de inmediato cuando alguien con acceso a una deje el equipo.
Revocar una clave desde Settings → API & MCP tiene efecto inmediato; las solicitudes ya en curso pueden completarse igualmente.

Requisitos de clientes OAuth

Un cliente construido a mano interactúa directamente con los endpoints de autorización y de token:

https://app.famulor.io/api/oauth/authorize
https://app.famulor.io/api/oauth/token

Usa URL de redirección HTTPS. Las aplicaciones nativas también pueden usar direcciones HTTP de loopback literales como 127.0.0.1. Las solicitudes de autorización OAuth deben usar PKCE-S256 y pedir solo los alcances registrados para el cliente. Cuando una solicitud se limite por frecuencia, reinténtala tras el retraso indicado en la respuesta. El cliente usa credenciales preaprobadas para tu espacio de trabajo, o se registra a sí mismo de forma dinámica con POST /api/oauth/register — indica entre 1 y 10 redirect_uris únicos. Los endpoints, los alcances admitidos y los tipos de concesión se pueden consultar en /.well-known/oauth-authorization-server. Un cliente registrado dinámicamente que el usuario aún no ha aprobado no recibe errores en su URL de redirección: una solicitud de autorización no válida se responde directamente en la página de autorización. Una vez aprobado, los inicios de sesión posteriores reciben solo los grupos de herramientas que el usuario eligió; si pide más, la pantalla de consentimiento vuelve a aparecer. Los tokens de acceso se renuevan con la concesión refresh_token. Los tokens de actualización rotan en cada uso: solicitar un nuevo token de acceso también emite un nuevo token de actualización e invalida de inmediato el que enviaste.

Formato de respuesta

Las respuestas correctas envuelven el resultado en data y pueden incluir meta:

{
  "data": [{ "id": "…", "name": "Support Agent" }],
  "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } }
}

Las respuestas contienen únicamente datos del espacio de trabajo orientados al cliente. Los secretos nunca se devuelven después de guardarse, y los valores sensibles se enmascaran cuando resulta útil. Las grabaciones se entregan mediante enlaces temporales. El uso y la facturación se reportan en los minutos y créditos que aparecen en tu cuenta.

Paginación

Los endpoints de lista usan limit y offset:

Parámetro	Predeterminado	Máximo	Descripción
`limit`	`50`	`200`	Número de elementos a devolver
`offset`	`0`	—	Número de elementos a omitir

Usa meta.pagination.total para saber si hay más páginas disponibles.

Errores

Los fallos devuelven un código estable y un mensaje legible:

{
  "error": {
    "code": "invalid_request",
    "message": "A destination phone number is required."
  }
}

Estado	Código	Significado
`400`	`invalid_request`	Cuerpo o parámetros de la solicitud no válidos
`401`	`unauthorized`	Credencial ausente, no válida, caducada o revocada
`403`	`forbidden`	El alcance, el rol o el plan no permiten la acción
`403`	`api_access_required`	API Access no está disponible para este espacio de trabajo
`404`	`not_found`	Recurso no encontrado o no visible para este espacio de trabajo
`409`	`conflict`	El recurso está en un estado conflictivo
`429`	`rate_limited`	Demasiadas solicitudes; espera y vuelve a intentarlo
`500`	`internal_error`	Error inesperado

Gestión de clientes de marca blanca

Los revendedores autorizados pueden usar los endpoints platform para gestionar a sus propios clientes finales, emitir y revocar tokens de API de clientes, transferir créditos y gestionar su dominio personalizado. Estos endpoints requieren los alcances platform:read o platform:write; las operaciones de dominio personalizado usan el alcance de configuración correspondiente.

Endpoint	Finalidad
`GET /api/v1/platform/users`	Listar tus clientes finales
`POST /api/v1/platform/users`	Registrar un cliente final
`GET /api/v1/platform/users/{user_id}`	Leer el resumen de cuenta de un cliente final
`POST /api/v1/platform/users/{user_id}/token`	Emitir un token de API para ese cliente
`POST /api/v1/platform/users/login`	Autenticar a un cliente
`POST /api/v1/platform/users/{user_id}/logout`	Revocar los tokens de API de ese cliente
`POST /api/v1/platform/users/{user_id}/balance`	Transferir créditos entre tu saldo de revendedor y el cliente
`GET /api/v1/custom-domain`	Consultar el estado del dominio personalizado
`POST /api/v1/custom-domain`	Añadir un dominio personalizado y recibir los registros DNS necesarios
`POST /api/v1/custom-domain/verify`	Comprobar el DNS y activar un dominio listo
`DELETE /api/v1/custom-domain`	Eliminar el dominio personalizado

Consulta la guía de la API de marca blanca para ver ejemplos.

CLI

Cada operación de la API también es un comando en la Famulor CLI, con tu clave de API guardada en el llavero del sistema:

npm install --global famulor
famulor auth login
famulor list-assistants --output table

La CLI usa las mismas claves de API, alcances, API Access y límites de solicitudes que la API REST.

MCP

Las mismas funciones orientadas al cliente están disponibles como herramientas de IA a través del endpoint de MCP:

https://app.famulor.io/mcp

MCP usa las mismas claves de API, consentimiento OAuth, alcances y acceso al espacio de trabajo. Su disponibilidad se controla por separado mediante Connect AI / MCP, no mediante API Access.

Variantes Realtime y voces de conversación

Crea o actualiza un asistente con mode: "realtime" y realtime_variant: "full_duplex" cuando tu espacio de trabajo tenga acceso. Si omites la variante, los nuevos asistentes usan Standard y las actualizaciones conservan la variante existente. El modelo de razonamiento se gestiona centralmente; las preferencias Pipeline del asistente no lo sustituyen. Utiliza GET /api/v1/voices?mode=realtime&realtime_variant=full_duplex para descubrir voces compatibles. Envía el id devuelto como realtime_voice; Full Duplex también lo usa para saludos, consentimiento y anuncios de herramientas. Conserva tts_voice como voz de respaldo de Pipeline. Los saludos de audio subidos conservan su voz grabada. Los identificadores de voz son opacos; no deduzcas un proveedor a partir de ellos. Las voces o variantes no disponibles se rechazan. Para voces TTS, usa GET /api/v1/voices?mode=tts&language=de sin realtime_variant. Combinar mode=tts con una variante Realtime devuelve 400. CLI: famulor list-voices --mode tts --language de; para Full Duplex: famulor list-voices --mode realtime --realtime-variant full_duplex --language de. Cuando existe una muestra nativa grabada, preview_url contiene una ruta de API relativa. Resuélvela respecto a tu dominio de API y descárgala con el mismo token Bearer y el permiso voices:read. GET /api/v1/voices/{id}/preview?realtime_variant=full_duplex devuelve audio WAV sin generar otra muestra. El catálogo de voces MCP incluye la misma referencia de vista previa. Las muestras TTS guardadas están disponibles en GET /api/v1/voices/{id}/preview?mode=tts, o con famulor get-voice-preview --id <voice-id> --mode tts en la CLI. Usa el valor devuelto en preview_url; será null si no hay muestra. La descarga no genera audio nuevo. Si tu plan permite seleccionar modelos, GET /api/v1/models?type=realtime&realtime_variant=full_duplex muestra los modelos de voz compatibles. Esto no habilita un selector del modelo de razonamiento. La respuesta Usage incluye las tarifas actuales en créditos. Los recargos de Full Duplex y avatar se suman cuando ambos están activos. Disponibilidad regional: Full Duplex depende de los modelos habilitados para la región seleccionada del espacio, incluidas EU, US y Global. Requiere acceso beta, un plan con Realtime y modelos de voz y razonamiento compatibles. El editor, la API y MCP aplican las mismas reglas de disponibilidad. MCP utiliza los mismos campos del asistente. La herramienta get_voices acepta mode y realtime_variant; get_models acepta realtime_variant. Consulta Modos de motor para conocer los ajustes y limitaciones.

Límites de solicitudes

Las solicitudes REST comparten un presupuesto fijo de un minuto en todos los endpoints: por defecto, 120 solicitudes por clave API o token de acceso OAuth y 600 solicitudes por espacio de trabajo. Tu plan puede tener otros límites. Crear más claves o cambiar de dominio no aumenta el presupuesto del espacio de trabajo. Un límite separado de 1.800 solicitudes por minuto y dirección IP protege la verificación de credenciales; las integraciones con la misma IP comparten este límite. Cuando se agota el presupuesto, la API devuelve 429, error.code: "rate_limited" y una cabecera Retry-After con el tiempo de espera en segundos. Pausa las solicitudes durante ese tiempo y reintenta con esperas crecientes y una pequeña variación aleatoria. Evita consultar continuamente el mismo recurso y utiliza webhooks cuando estén disponibles. Si la protección de solicitudes no está disponible temporalmente, la API devuelve 503 con un tiempo de espera. El panel y MCP tienen sus propias reglas de acceso y solicitudes.

​URL base

​Acceso a la API

​Autenticación

​Higiene de las claves

​Requisitos de clientes OAuth

​Formato de respuesta

​Paginación

​Errores

​Gestión de clientes de marca blanca

​CLI

​MCP

​Variantes Realtime y voces de conversación

​Límites de solicitudes

URL base

Acceso a la API

Autenticación

Higiene de las claves

Requisitos de clientes OAuth

Formato de respuesta

Paginación

Errores

Gestión de clientes de marca blanca

CLI

MCP

Variantes Realtime y voces de conversación

Límites de solicitudes