Docs/Operaciones

Catálogo de operaciones

Las 134 operaciones de la API pública, agrupadas por dominio. De cada una: qué hace, qué permiso exige de la clave, tras qué puerta de despliegue vive, qué planes la alcanzan de serie y qué códigos HTTP declara.

Esta página se genera del contrato. Una operación nueva aparece aquí sin que nadie la escriba, y hay un test que se pone rojo si el disco y esta tabla dejan de coincidir.

Cómo leer la columna «Puerta»

Valor	Qué significa
Siempre	Servida sin condiciones de despliegue.
Escritura	Exige `PUBLIC_API_WRITE_ENABLED`. Apagado responde 404.
Gasto	Exige los dos interruptores, el alta explícita de la cuenta y cabecera `Idempotency-Key`.

Cómo leer la columna «Planes»

Son los planes cuyo nivel trae la capacidad de serie. Ninguno de serie (43 operaciones) significa que hay que pedir la capacidad para la cuenta — no que sea imposible. La guía de inicio lo explica en su sección 16.

Un 403 en cualquiera de estas operaciones tiene dos lecturas distintas (sección 5): insufficient_scope lo arregla quien emitió la clave; capability_required lo arregla el plan.

Agentes

Listar los agentes de voz del tenant, ver uno y editar su contenido (saludo, prompt, voz). Crear y borrar agentes NO está abierto por API: se hace desde el panel.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/agents`	Listar los agentes de voz del tenant	`agents:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`GET /api/v1/agents/{agent_id}`	Ver un agente	`agents:read`	Siempre	Todos	200, 401, 403, 404, 429, 500
`PATCH /api/v1/agents/{agent_id}`	Actualizar el contenido de un agente	`agents:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/agents/templates`	Listar el catálogo de plantillas de agente	`agents:read`	Siempre	Todos	200, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/agents?limit=10"

Analítica

Los mismos agregados que pinta el panel: el resumen del dashboard y las estadísticas de llamadas por periodo.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/analytics/calls`	Desglose de llamadas por dirección y resultado	`analytics:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`GET /api/v1/analytics/dashboard`	Indicadores del periodo y su variación	`analytics:read`	Siempre	Todos	200, 400, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/analytics/dashboard?start_date=2026-07-01&end_date=2026-07-31"

Anuncios

Los comunicados internos de la cuenta: los mismos que ve el equipo en el panel. Solo lectura por API — publicarlos y retirarlos se hace desde el panel.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/announcements`	Listar los anuncios internos de la cuenta	`announcements:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`GET /api/v1/announcements/{announcement_id}`	Leer un anuncio interno	`announcements:read`	Siempre	Todos	200, 401, 403, 404, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/announcements?limit=20"

Auditoría

El registro de actividad del tenant: quién hizo qué y cuándo.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/audit-log`	Leer el registro de actividad de la cuenta	`audit:read`	Siempre	Todos	200, 400, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/audit-log?limit=50"

Avisos

Configurar, silenciar o descartar los avisos del sistema.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`PATCH /api/v1/alerts`	Configurar los avisos de la cuenta	`alerts:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500

bash

curl -sS -X PATCH \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alert_id":"<uuid>","dismissed":true}' \
  "https://$AMAI_API_HOST/api/v1/alerts"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Base de conocimiento

Gestionar las colecciones de documentos que consultan los agentes. La LECTURA de esas bases vive en el dominio «Knowledge Base» — son dos etiquetas para la misma cosa, y está anotado como defecto conocido en la ficha de la guía.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`PATCH /api/v1/kb/collections/{collection_id}`	Renombrar o describir una colección	`kb:write`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 500

bash

curl -sS -X PATCH \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Manual de producto 2026"}' \
  "https://$AMAI_API_HOST/api/v1/kb/collections/<collection_id>"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Calendario

El horario laboral del tenant y sus excepciones. GET /api/v1/calendar/check responde si un instante concreto cae dentro del horario — es lo que consulta un agente antes de prometer una devolución de llamada.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/bookings`	Citas agendadas	`calendar:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`DELETE /api/v1/calendar/overrides`	Quitar la excepción de un día	`calendar:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`PUT /api/v1/calendar/overrides`	Fijar la excepción de un día	`calendar:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`PUT /api/v1/calendar/schedule`	Fijar el horario semanal	`calendar:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/calendar/check?at=2026-07-28T10:30:00Z"

Campañas

Crear y editar campañas y asociarles listas de contactos. Lanzarlas no está aquí: el despacho gasta saldo y vive en el dominio «Gasto».

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`POST /api/v1/campaigns`	Crear una campaña de email	`campaigns:write`	Escritura	Ninguno de serie	201, 400, 401, 403, 404, 429, 500
`GET /api/v1/campaigns/{campaign_id}`	Consultar una campaña	`campaigns:read`	Siempre	Ninguno de serie	200, 401, 403, 404, 429, 500
`PATCH /api/v1/campaigns/{campaign_id}`	Editar una campaña de email	`campaigns:write`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/campaigns/{campaign_id}/attempts`	Intentos de una campaña	`campaigns:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/campaigns/{campaign_id}/enrollments`	Inscripciones de una campaña	`campaigns:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 404, 429, 500
`DELETE /api/v1/campaigns/{campaign_id}/lists`	Quitar listas de la audiencia de una campaña	`campaigns:write`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/campaigns/{campaign_id}/lists`	Consultar la audiencia de una campaña	`campaigns:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 404, 429, 500
`POST /api/v1/campaigns/{campaign_id}/lists`	Añadir listas a la audiencia de una campaña	`campaigns:write`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 500

bash

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Recordatorio julio","agent_id":"<uuid>"}' \
  "https://$AMAI_API_HOST/api/v1/campaigns"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Canal

Solo para cuentas de tipo agencia o partner: el árbol de subcuentas y sus estadísticas agregadas.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/agency/stats`	Agregado del canal en el periodo	`agency:read`	Siempre	Agency, Partner, Enterprise	200, 400, 401, 403, 429, 500
`GET /api/v1/subaccounts`	Listar las subcuentas del árbol	`subaccounts:read`	Siempre	Agency, Partner, Enterprise	200, 400, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/agency/stats"

Una cuenta cliente recibe 403 capability_required aquí, y es correcto: no tiene canal.

Claves de API

Rotar tu propia credencial por programa: se emite una nueva con el mismo nombre y los mismos permisos, y la anterior queda revocada en el acto — sin periodo de gracia, porque se rota cuando una clave se ha filtrado. key_id tiene que ser el id de la clave con la que llamas (el que ves en el panel, no el secreto); cualquier otro responde 404, incluidas las demás claves de tu cuenta. El valor nuevo viaja una sola vez, en esa respuesta. Listar, crear y revocar otras claves sigue siendo del panel.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`POST /api/v1/api-keys/{key_id}/rotate`	Rotar la propia clave de API	`api-keys:write`	Escritura	Starter, Business, Agency, Partner, Enterprise	201, 400, 401, 403, 404, 429, 500

bash

curl -sS -X POST -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/api-keys/$AMAI_API_KEY_ID/rotate"

Contactos

El directorio del tenant. POST /api/v1/contacts/identify es el que usa un agente en mitad de una llamada para saber con quién habla.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/contacts`	Listar contactos	`contacts:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`POST /api/v1/contacts`	Crear un contacto	`contacts:write`	Escritura	Todos	201, 400, 401, 403, 404, 409, 429, 500
`GET /api/v1/contacts/{contact_id}`	Consultar un contacto	`contacts:read`	Siempre	Todos	200, 401, 403, 404, 429, 500
`PATCH /api/v1/contacts/{contact_id}`	Actualizar un contacto	`contacts:write`	Escritura	Todos	200, 400, 401, 403, 404, 409, 429, 500
`POST /api/v1/contacts/identify`	Identificar un contacto	`contacts:write`	Siempre	Todos	200, 400, 401, 403, 429, 500
`POST /api/v1/contacts/import`	Importar contactos en lote	`contacts:write`	Escritura	Todos	201, 400, 401, 403, 404, 429, 500
`GET /api/v1/members`	Listar miembros del equipo	`members:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 404, 429, 500, 503
`GET /api/v1/team/mention-list`	Listado de personas mencionables del equipo	`team:read`	Siempre	Ninguno de serie	200, 401, 403, 429

bash

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+34600111222"}' \
  "https://$AMAI_API_HOST/api/v1/contacts/identify"

Conversations

La bandeja unificada de WhatsApp: hilos, mensajes, cesión humana y los números conectados, sin entrar nunca en Meta ni manejar un token suyo. Las tres listas —hilos, mensajes y números conectados— se paginan por cursor y no por offset, porque una bandeja se reordena mientras se lee y paginar por posición se salta hilos en silencio; la condición de parada es page.has_more, que se calcula leyendo una fila de más. Toda la sección exige el interruptor CONVERSATIONS_API_ENABLED: apagado responde 404. Y POST .../messages registra la intención de enviar, no envía: quien llama al proveedor es la pasarela.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/conversations`	Listar conversaciones	`whatsapp:read`	Conversations	Todos	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/conversations/{conversation_uuid}`	Ver una conversación	`whatsapp:read`	Conversations	Todos	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/conversations/{conversation_uuid}/messages`	Listar los mensajes de una conversación	`whatsapp:read`	Conversations	Todos	200, 400, 401, 403, 404, 429, 500
`POST /api/v1/conversations/{conversation_uuid}/messages`	Responder en una conversación	`whatsapp:send`	Conversations	Todos	200, 202, 400, 401, 403, 404, 409, 429, 500
`POST /api/v1/conversations/{conversation_uuid}/resume`	Devolver el control	`whatsapp:send`	Conversations	Todos	200, 400, 401, 403, 404, 409, 429, 500
`POST /api/v1/conversations/{conversation_uuid}/takeover`	Tomar el control (takeover humano)	`whatsapp:send`	Conversations	Todos	200, 400, 401, 403, 404, 409, 429, 500
`GET /api/v1/events/catalog`	Catálogo de eventos	`webhooks:read`	Conversations	Todos	200, 400, 401, 403, 404, 429, 500
`POST /api/v1/events/replay`	Reenviar una entrega de webhook	`webhooks:write`	Conversations	Todos	200, 400, 401, 403, 404, 409, 429, 500
`GET /api/v1/whatsapp/connections`	Listar los WhatsApp conectados	`whatsapp:read`	Conversations	Todos	200, 400, 401, 403, 404, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/conversations?status=open&limit=25"

Documentos

El archivo documental de la cuenta: listar y filtrar por tipo, etiqueta, texto y rango de fechas. Las fechas son inclusivas por los dos extremos.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/documents`	Listar el archivo documental de la cuenta	`documents:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 429, 500, 502, 503

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/documents?date_from=2026-07-01&date_to=2026-07-31&limit=25"

Exige que la cuenta tenga el archivo CONECTADO, no solo el plan que lo incluye. Si el plan lo incluye y la integración no está configurada, responde 503 integration_not_configured — y eso no lo arregla ni la clave ni un cambio de plan, sino tu distribuidor.

Email

Las identidades de envío de correo dadas de alta en la cuenta: desde qué direcciones puede enviar, y cuáles están verificadas. Útil para elegir remitente ANTES de llamar al envío.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/email/connections`	Listar las identidades de envío de email	`email-configs:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/email/connections"

Solo lectura, y a propósito: no devuelve ninguna credencial de la conexión (ni contraseña, ni token de OAuth). Dar de alta o revocar una identidad se hace desde el panel.

Equipo

La administración del equipo: invitaciones pendientes, plazas contratadas y ocupadas, y los roles personalizados del tenant. Se puede revocar una invitación.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/team/invites`	Listar invitaciones del equipo	`members:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 429, 500
`DELETE /api/v1/team/invites/{invite_id}`	Revocar una invitación pendiente	`invites:revoke`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/team/roles`	Listar los roles personalizados del tenant	`members:read`	Siempre	Ninguno de serie	200, 401, 403, 429, 500
`GET /api/v1/team/seats`	Consultar las plazas de equipo	`members:read`	Siempre	Ninguno de serie	200, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/team/seats"

Las tres lecturas comparten el scope members:read. La revocación (DELETE /api/v1/team/invites/{invite_id}) es otra autorización — invites:revoke — y además exige PUBLIC_API_WRITE_ENABLED.

Espacio de trabajo

Lo que el panel enseña en su bandeja: recados, avisos y el listado de campañas. Es la vista de lectura del día a día.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/alerts`	Consultar los avisos configurados y el gasto que los dispara	`alerts:read`	Siempre	Todos	200, 401, 403, 429, 500
`GET /api/v1/campaigns`	Listar las campañas de la cuenta	`campaigns:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 429, 500
`GET /api/v1/recados`	Listar la bandeja de recados	`recados:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 429, 500, 503

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/recados?limit=20"

Facturación

Consulta de saldo, suscripción, consumo, movimientos y facturas. Todo de LECTURA: contratar y recargar viven en «Gasto».

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/billing/addons`	Ver los add-ons disponibles y los contratados	`billing:read`	Siempre	Todos	200, 401, 403, 429, 500
`GET /api/v1/billing/balance`	Consultar el saldo del monedero	`billing:read`	Siempre	Todos	200, 401, 403, 429, 500
`GET /api/v1/billing/concurrency`	Consultar el cupo de llamadas simultáneas	`billing:read`	Siempre	Todos	200, 401, 403, 429, 500
`GET /api/v1/billing/invoices`	Listar las facturas emitidas	`billing:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`GET /api/v1/billing/pending-orders`	Listar compras de número sin completar	`billing:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`GET /api/v1/billing/subscription`	Ver el plan contratado y su ciclo de facturación	`billing:read`	Siempre	Todos	200, 401, 403, 429, 500
`GET /api/v1/billing/transactions`	Listar los movimientos del monedero	`billing:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`GET /api/v1/billing/usage`	Consumo del periodo	`billing:read`	Siempre	Todos	200, 400, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/billing/balance"

Gasto

Todo lo que mueve dinero o genera tráfico real: lanzar una llamada, despachar una campaña, recargar saldo, contratar plan o add-on, crear troncales SIP y gestionar subcuentas. Es la superficie con más condiciones de toda la API — cuatro, y hacen falta las cuatro.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`POST /api/v1/agency/subaccounts`	Crear una subcuenta	`agency:write`	Gasto	Agency, Partner, Enterprise	201, 400, 401, 403, 404, 409, 429, 500, 503
`PATCH /api/v1/agency/subaccounts/{subaccount_id}`	Activar o suspender una subcuenta	`agency:write`	Gasto	Agency, Partner, Enterprise	200, 400, 401, 403, 404, 409, 429, 500, 503
`POST /api/v1/billing/addons`	Contratar un add-on	`billing:write`	Gasto	Todos	200, 201, 400, 401, 403, 404, 409, 429, 500, 503
`DELETE /api/v1/billing/addons/{addon_type}`	Cancelar un add-on	`billing:write`	Gasto	Todos	200, 400, 401, 403, 404, 409, 429, 500, 503
`DELETE /api/v1/billing/subscription`	Cancelar el plan al final del periodo	`billing:write`	Gasto	Todos	200, 400, 401, 403, 404, 409, 429, 500, 503
`POST /api/v1/billing/subscription`	Contratar o cambiar de plan	`billing:write`	Gasto	Todos	200, 201, 400, 401, 403, 404, 409, 429, 500, 503
`POST /api/v1/billing/topups`	Recargar el monedero	`billing:write`	Gasto	Todos	201, 400, 401, 403, 404, 409, 429, 500, 503
`POST /api/v1/calls/dial`	Lanzar una llamada saliente	`calls:dial`	Gasto	Todos	201, 400, 401, 402, 403, 404, 409, 429, 500, 503
`POST /api/v1/campaigns/{campaign_id}/dispatch`	Despachar un lote de una campaña	`campaigns:dispatch`	Gasto	Ninguno de serie	200, 400, 401, 403, 404, 409, 429, 500, 503
`GET /api/v1/sip-trunks`	Listar los troncales SIP de la cuenta	`sip-trunks:read`	Siempre	Todos	200, 401, 403, 429, 500
`POST /api/v1/sip-trunks`	Crear un troncal SIP	`sip-trunks:write`	Gasto	PAYG, Starter, Business, Agency, Partner, Enterprise	201, 400, 401, 403, 404, 409, 429, 500, 503
`DELETE /api/v1/sip-trunks/{trunk_id}`	Eliminar un troncal SIP	`sip-trunks:write`	Gasto	PAYG, Starter, Business, Agency, Partner, Enterprise	200, 400, 401, 403, 404, 409, 429, 500, 503
`PATCH /api/v1/sip-trunks/{trunk_id}`	Modificar un troncal SIP	`sip-trunks:write`	Gasto	PAYG, Starter, Business, Agency, Partner, Enterprise	200, 400, 401, 403, 404, 409, 429, 500, 503

bash

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to":"+34600111222","agent_id":"<uuid>"}' \
  "https://$AMAI_API_HOST/api/v1/calls/dial"

Guarda el UUID que generes: si la petición da timeout, reintenta con el mismo o pagarás dos llamadas. Ver la sección de idempotencia de la guía de inicio.

Inbox

La bandeja de correo de la cuenta, de fuera adentro: buzones, carpetas de un buzón, mensajes de una carpeta, un mensaje, sus adjuntos y el hilo al que pertenece. Todo lectura.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/inbox/{mailbox_id}/conversations/{conversation_id}`	Leer un hilo completo	`inbox:read`	Siempre	Ninguno de serie	200, 401, 403, 404, 429, 500, 501, 502
`GET /api/v1/inbox/{mailbox_id}/folders`	Listar las carpetas de un buzón, con sus contadores	`inbox:read`	Siempre	Ninguno de serie	200, 401, 403, 404, 429, 500, 501, 502
`GET /api/v1/inbox/{mailbox_id}/messages`	Listar los mensajes de un buzón compartido	`inbox:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 404, 429, 500, 501, 502
`GET /api/v1/inbox/{mailbox_id}/messages/{message_id}`	Leer un mensaje con su cuerpo	`inbox:read`	Siempre	Ninguno de serie	200, 401, 403, 404, 429, 500, 501, 502
`GET /api/v1/inbox/{mailbox_id}/messages/{message_id}/attachments`	Listar los adjuntos de un mensaje	`inbox:read`	Siempre	Ninguno de serie	200, 401, 403, 404, 429, 500, 501, 502
`GET /api/v1/inbox/{mailbox_id}/messages/{message_id}/attachments/{attachment_id}`	Descargar el contenido de un adjunto (base64)	`inbox:read`	Siempre	Ninguno de serie	200, 401, 403, 404, 413, 429, 500, 501, 502
`GET /api/v1/inbox/mailboxes`	Listar los buzones compartidos que esta clave puede leer	`inbox:read`	Siempre	Ninguno de serie	200, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/inbox/mailboxes"

La descarga de un adjunto corta en 15 MiB con 413 attachment_too_large; por encima de ese tamaño la ficha del adjunto sigue estando en el listado, pero el binario no se sirve por esta vía.

Knowledge Base

Listar las bases de conocimiento y buscar dentro de una. Es la LECTURA; la gestión de colecciones está bajo «Base de conocimiento».

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/knowledge-bases`	Listar las bases de conocimiento de la cuenta	`kb:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 429, 500
`POST /api/v1/knowledge-bases/{kb_id}/search`	Buscar en una base de conocimiento	`kb:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 404, 429, 500

bash

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"horario de atención"}' \
  "https://$AMAI_API_HOST/api/v1/knowledge-bases/<kb_id>/search"

Listas

Listas de contactos: crearlas, renombrarlas y meter o sacar miembros.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/contact-lists`	Listar las listas de contactos	`contacts:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`POST /api/v1/contact-lists`	Crear una lista de contactos	`contacts:write`	Escritura	Todos	201, 400, 401, 403, 404, 429, 500
`GET /api/v1/contact-lists/{list_id}`	Consultar una lista	`contacts:read`	Siempre	Todos	200, 401, 403, 404, 429, 500
`PATCH /api/v1/contact-lists/{list_id}`	Renombrar o describir una lista	`contacts:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`DELETE /api/v1/contact-lists/{list_id}/members`	Quitar contactos de una lista	`contacts:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/contact-lists/{list_id}/members`	Listar los contactos de una lista	`contacts:read`	Siempre	Todos	200, 400, 401, 403, 404, 429, 500
`POST /api/v1/contact-lists/{list_id}/members`	Añadir contactos a una lista	`contacts:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500

bash

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Clientes activos"}' \
  "https://$AMAI_API_HOST/api/v1/contact-lists"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Llamadas

El historial con desglose de coste y los agregados del periodo completo — el sustituto por API del CSV del panel — más las anotaciones sobre una llamada (miembro asignado, etiquetas).

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/call-labels`	Listar el catálogo de etiquetas de llamada	`calls:read`	Siempre	Todos	200, 401, 403, 429, 500
`GET /api/v1/calls`	Listar llamadas con coste y agregados del periodo	`calls:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`GET /api/v1/calls/{call_id}`	Ver una llamada	`calls:read`	Siempre	Todos	200, 400, 401, 403, 404, 429, 500
`POST /api/v1/calls/{call_id}/labels`	Etiquetar una llamada	`calls:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`DELETE /api/v1/calls/{call_id}/labels/{label_key}`	Quitar una etiqueta de una llamada	`calls:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`DELETE /api/v1/calls/{call_id}/member`	Quitar la asignación de una llamada	`calls:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`PUT /api/v1/calls/{call_id}/member`	Asignar personas del equipo a una llamada	`calls:write`	Escritura	Todos	200, 400, 401, 403, 404, 409, 410, 429, 500
`GET /api/v1/qualifications`	Veredictos de cualificación	`calls:read`	Siempre	Todos	200, 400, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/calls?start_date=2026-07-01&end_date=2026-07-31&limit=50"

Guía completa, con paginación de un mes entero: /docs/calls.

Marca blanca

Dar de alta clientes con tu marca, sin ratón. El alta ya existía (POST /api/v1/agency/subaccounts, que cuelga la cuenta nueva de la tuya); esto es la otra mitad: leer y escribir cómo se ve el panel de esa cuenta —nombre, logo, colores, dominio propio— y las tres verjas que deciden si admite altas (allow_signup) y qué puede contratar (hide_plans, hide_addons). El identificador tiene que colgar de ti; cualquier otro responde 404 sin decirte si existe.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/subaccounts/{subaccount_id}`	Leer una cuenta del árbol	`subaccounts:read`	Siempre	Agency, Partner, Enterprise	200, 401, 403, 404, 429, 500
`GET /api/v1/subaccounts/{subaccount_id}/branding`	Leer la marca de una cuenta del árbol	`branding:read`	Siempre	Agency, Partner, Enterprise	200, 401, 403, 404, 429, 500
`PATCH /api/v1/subaccounts/{subaccount_id}/branding`	Editar la marca de una cuenta del árbol	`branding:write`	Escritura	Agency, Partner, Enterprise	200, 400, 401, 403, 404, 409, 429, 500
`POST /api/v1/subaccounts/{subaccount_id}/branding/verify-domain`	Verificar el dominio propio contra el DNS	`branding:write`	Escritura	Agency, Partner, Enterprise	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/subaccounts/{subaccount_id}/packaging`	Leer las verjas de empaquetado de una cuenta del árbol	`branding:read`	Siempre	Agency, Partner, Enterprise	200, 401, 403, 404, 429, 500
`PATCH /api/v1/subaccounts/{subaccount_id}/packaging`	Editar las verjas de empaquetado de una cuenta del árbol	`branding:write`	Escritura	Agency, Partner, Enterprise	200, 400, 401, 403, 404, 429, 500

bash

curl -sS -X PATCH -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_name":"Mi Marca","primary_color":"#00a86b","custom_domain":"panel.miempresa.com"}' \
  "https://$AMAI_API_HOST/api/v1/subaccounts/$AMAI_SUBACCOUNT_ID/branding"

custom_domain_verified no se puede escribir. Se gana publicando el registro TXT que devuelve la lectura (_amai-verify.<dominio> → amai-verify=<account_id>) y llamando a POST …/branding/verify-domain, que lo comprueba contra el DNS. Y cambiar el dominio revoca la verificación en la misma escritura: si no, apuntar el dominio a otro sitio heredaría un sello que no se ha ganado.

Plantillas

Plantillas de email reutilizables en campañas y secuencias.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/email-templates`	Listar las plantillas de email de la cuenta	`campaigns:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 429, 500
`POST /api/v1/email-templates`	Crear una plantilla de email	`campaigns:write`	Escritura	Ninguno de serie	201, 400, 401, 403, 404, 429, 500
`GET /api/v1/email-templates/{template_id}`	Ver una plantilla de email	`campaigns:read`	Siempre	Ninguno de serie	200, 401, 403, 404, 429, 500
`PATCH /api/v1/email-templates/{template_id}`	Editar una plantilla de email	`campaigns:write`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 500

bash

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Bienvenida","subject":"Hola {{first_name}}","body":"<p>Gracias por confiar en nosotros.</p>"}' \
  "https://$AMAI_API_HOST/api/v1/email-templates"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Secuencias

Secuencias de seguimiento automatizadas: crearlas y editarlas.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/sequences`	Listar las secuencias de la cuenta	`campaigns:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 429, 500
`POST /api/v1/sequences`	Crear una secuencia de email	`campaigns:write`	Escritura	Ninguno de serie	201, 400, 401, 403, 404, 429, 500
`DELETE /api/v1/sequences/{sequence_id}`	Archivar una secuencia de email	`campaigns:write`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 500
`PATCH /api/v1/sequences/{sequence_id}`	Editar una secuencia de email	`campaigns:write`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 500
`POST /api/v1/sequences/{sequence_id}/enroll`	Inscribir contactos en una secuencia	`campaigns:write`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 500

bash

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Seguimiento a 3 días"}' \
  "https://$AMAI_API_HOST/api/v1/sequences"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Telefonía

Los números del tenant y las tarifas de venta propias de la cuenta, con el catálogo de países disponibles.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/numbers`	Listar los números del tenant	`numbers:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`PATCH /api/v1/numbers/{number_id}`	Renombrar un número del inventario	`numbers:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/rates`	Consultar las tarifas de salida de la cuenta	`rates:read`	Siempre	Starter, Business, Agency, Partner, Enterprise	200, 400, 401, 403, 429, 500
`GET /api/v1/rates/countries`	Listar el catálogo de destinos que se pueden llamar	`rates:read`	Siempre	Starter, Business, Agency, Partner, Enterprise	200, 401, 403, 429, 500
`GET /api/v1/telephony/extensions`	Listar las extensiones SIP del tenant	`numbers:read`	Siempre	Todos	200, 400, 401, 403, 429, 500
`GET /api/v1/telephony/profiles`	Listar los perfiles de telefonía del tenant	`numbers:read`	Siempre	Todos	200, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/numbers"

/api/v1/rates devuelve tus tarifas de venta, las de tu cuenta. No expone el coste de proveedor de AMAI ni ningún multiplicador.

Utilidades

Las piezas sueltas que un flujo de agente necesita: calendario, envío de email e histórico de email y de SMS.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`GET /api/v1/calendar`	Calendario laboral de un rango de fechas	`calendar:read`	Siempre	Todos	200, 400, 401, 403, 404, 429
`GET /api/v1/calendar/check`	Comprobar día/hora laborable	`calendar:read`	Siempre	Todos	200, 400, 401, 403, 404, 429
`GET /api/v1/email/history`	Listar el histórico de email	`email:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 429, 500
`POST /api/v1/email/send`	Enviar un email desde el tenant	`email:send`	Escritura	Ninguno de serie	200, 400, 401, 403, 429, 502, 503
`POST /api/v1/sms/check`	Verificar destinatarios de SMS (sin enviar)	`sms:send`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 503
`GET /api/v1/sms/history`	Listar el histórico de SMS	`sms:read`	Siempre	Ninguno de serie	200, 400, 401, 403, 429, 500
`POST /api/v1/sms/send`	Enviar un SMS	`sms:send`	Escritura	Ninguno de serie	200, 400, 401, 403, 404, 429, 502, 503

bash

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"cliente@ejemplo.com","subject":"Tu cita","body":"Confirmada para el martes."}' \
  "https://$AMAI_API_HOST/api/v1/email/send"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Webhooks

Tu suscripción a los eventos de la plataforma —un destino por cuenta— y el registro de cada intento de entrega. El ejemplo es la consulta, que es lo primero que se necesita: hasta ahora se entregaba a ciegas y el único sitio donde se veía si algo había llegado era la pantalla del panel.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`DELETE /api/v1/webhooks`	Dar de baja tu suscripción de webhooks	`webhooks:write`	Escritura	Todos	200, 401, 403, 404, 429, 500
`GET /api/v1/webhooks`	Consultar tu suscripción de webhooks	`webhooks:read`	Siempre	Todos	200, 401, 403, 429, 500
`PATCH /api/v1/webhooks`	Cambiar el destino o los eventos	`webhooks:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`POST /api/v1/webhooks`	Dar de alta (o reemplazar) tu suscripción de webhooks	`webhooks:write`	Escritura	Todos	200, 400, 401, 403, 404, 429, 500
`GET /api/v1/webhooks/deliveries`	Ver si tus entregas llegaron	`webhooks:read`	Siempre	Todos	200, 400, 401, 403, 429, 500

bash

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/webhooks/deliveries?success=false&limit=20"

El secreto de firma no viaja en ninguna lectura: GET /api/v1/webhooks solo dice si lo hay. Se enseña una única vez, en el POST que lo emite. Si lo pierdes, rotate_secret emite otro — y las firmas anteriores dejan de validar.

Enviar texto y plantillas, leer el histórico y consultar las plantillas aprobadas. El token de Meta lo custodia y rota AMAI: nunca lo manejas tú.

Operación	Qué hace	Scope	Puerta	Planes	Códigos
`POST /api/v1/whatsapp/check`	¿A quién se le puede escribir, y cómo?	`whatsapp:send`	Escritura	Todos	200, 400, 401, 403, 404, 429, 503
`GET /api/v1/whatsapp/messages`	Listar mensajes (recibir por polling)	`whatsapp:read`	Siempre	Todos	200, 401, 403, 404, 429, 500
`POST /api/v1/whatsapp/send`	Enviar un mensaje de WhatsApp	`whatsapp:send`	Escritura	Todos	200, 400, 401, 403, 404, 422, 429, 500, 502
`GET /api/v1/whatsapp/templates`	Listar plantillas aprobadas	`whatsapp:read`	Siempre	Todos	200, 400, 401, 403, 404, 429, 500, 502

bash

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+34600111222","type":"text","text":"Hola desde la API de AMAI"}' \
  "https://$AMAI_API_HOST/api/v1/whatsapp/send"

Guía completa, con la ventana de 24 h y los webhooks: /docs/whatsapp.