Documentación de Make Agent Fast

Referencia de la API

Consulta todos los recursos públicos, métodos, scopes necesarios, reglas de paginación y contratos de mutación.

De un vistazo

Consulta todos los recursos públicos, métodos, scopes necesarios, reglas de paginación y contratos de mutación.

Ruta de solicitudes de la APIClave con alcance → recurso versionado → respuesta firmada

v1123 operacionesJSON

El contrato canónico legible por máquina es el OpenAPI JSON. Esta página es el índice de operaciones legible para personas y explica las reglas comunes a todos los endpoints.

URL base y versión#

https://makeagent.fast/api/v1

La versión mayor forma parte de la ruta. Pueden aparecer campos adicionales sin cambiar la versión mayor, así que ignora los campos de respuesta que no conozcas. Todas las solicitudes de gestión usan HTTPS y una clave de API bearer o un token de acceso OAuth.

Encabezados comunes#

Authorization: Bearer maf_live_...
Accept: application/json
Content-Type: application/json
Idempotency-Key: your-stable-operation-key

Content-Type es obligatorio en los cuerpos JSON de POST y PATCH, incluso cuando el cuerpo es {}. Idempotency-Key es opcional, pero se recomienda encarecidamente en todos los POST, PATCH y DELETE.

Cuenta y sitios#

Método	Ruta	Scope	Finalidad
`GET`	`/me`	`account:read`	Leer el resumen de cuenta, plan, derechos de uso y monedero
`GET`	`/sites`	`sites:read`	Listar los sitios propios
`POST`	`/sites`	`sites:write`	Crear un sitio y su agente predeterminado
`GET`	`/sites/{site_id}`	`sites:read`	Obtener un sitio propio
`PATCH`	`/sites/{site_id}`	`sites:write`	Actualizar campos seguros del sitio
`DELETE`	`/sites/{site_id}`	`sites:write`	Eliminar el sitio y los recursos dependientes
`POST`	`/sites/{site_id}/publish`	`sites:write`	Publicar o despublicar con `{ "published": boolean }`
`GET`	`/sites/{site_id}/agent`	`agents:read`	Leer la configuración del agente
`PATCH`	`/sites/{site_id}/agent`	`agents:write`	Actualizar el modo de persona, la finalidad, el nombre visible, las instrucciones, la voz, los idiomas, el modelo, la apariencia, el chrome del embed, la insignia, el estado del embed o los orígenes
`GET`	`/sites/{site_id}/billing`	`account:read`	Leer el plan, el período, el monedero, los complementos y los enlaces de facturación del panel
`PATCH`	`/sites/{site_id}/workspace`	`team:write`	Cambiar el nombre de la empresa propietaria del agente
`PATCH`	`/sites/{site_id}/retention`	`team:write`	Definir cuánto tiempo se conservan las conversaciones

Para crear un sitio se requieren title y content.headline. Los campos opcionales son slug, type, template, contenido adicional, persona_mode y de uno a cuatro idiomas entre en, ko, uz y ru.

PATCH /agent aplica a model, appearance, embed_chrome y badge_hidden las mismas comprobaciones de plan que el panel; badge_hidden: true requiere un plan elegible o el complemento de la insignia.

Método	Ruta	Scope	Finalidad
`GET`	`/sites/{site_id}/install`	`agents:read`	Leer el destino de instalación, el estado del embed, los orígenes permitidos y la evidencia de instalación
`PATCH`	`/sites/{site_id}/install`	`agents:write`	Definir la página en la que debe instalarse el widget
`POST`	`/sites/{site_id}/install/check`	`agents:write`	Comprobar si el fragmento de embed está activo en la página de destino

Conocimiento y preguntas frecuentes#

Método	Ruta	Scope	Finalidad
`GET`	`/sites/{site_id}/knowledge`	`knowledge:read`	Listar las sources de conocimiento
`POST`	`/sites/{site_id}/knowledge`	`knowledge:write`	Ingerir texto pegado, rastrear un sitio web o importar una source de YouTube, pódcast o feed
`PATCH`	`/sites/{site_id}/knowledge/{source_id}`	`knowledge:write`	Definir `refresh_hours` o el `approval_status` del buyer pack
`POST`	`/sites/{site_id}/knowledge/{source_id}/recrawl`	`knowledge:write`	Poner en cola una nueva lectura de una source obtenida; devuelve `202`
`DELETE`	`/sites/{site_id}/knowledge/{source_id}`	`knowledge:write`	Eliminar una source de las consultas futuras
`GET`	`/sites/{site_id}/faqs`	`knowledge:read`	Listar las preguntas frecuentes estructuradas
`POST`	`/sites/{site_id}/faqs`	`knowledge:write`	Crear `{ "question", "answer", "approved" }`
`POST`	`/sites/{site_id}/faqs/generate`	`knowledge:write`	Redactar borradores de preguntas frecuentes a partir del conocimiento del agente
`POST`	`/sites/{site_id}/faqs/approve-all`	`knowledge:write`	Aprobar y publicar todas las preguntas frecuentes en borrador
`PATCH`	`/sites/{site_id}/faqs/{faq_id}`	`knowledge:write`	Actualizar la pregunta, la respuesta o el estado de aprobación
`DELETE`	`/sites/{site_id}/faqs/{faq_id}`	`knowledge:write`	Eliminar una pregunta frecuente
`GET` / `PATCH`	`/sites/{site_id}/fact-sheet`	`knowledge:read` / `knowledge:write`	Leer la ficha de datos del negocio extraída, o corregir los datos que la extracción haya interpretado mal
`POST`	`/sites/{site_id}/fact-sheet/reextract`	`knowledge:write`	Volver a leer el sitio web y reconstruir la ficha de datos
`POST`	`/sites/{site_id}/qa`	`knowledge:write`	Publicar pares de preguntas y respuestas seleccionados
`POST`	`/sites/{site_id}/answers/revise`	`knowledge:write`	Enseñar al agente la respuesta que debería haber dado
`GET`	`/sites/{site_id}/knowledge-connections`	`knowledge:read`	Listar las conexiones de conocimiento de Notion, Drive y MCP
`GET`	`/sites/{site_id}/knowledge-connections/connect-links`	`knowledge:read`	Obtener las URL del panel que inician una conexión de Notion o Drive
`PATCH` / `DELETE`	`/sites/{site_id}/knowledge-connections/{connection_id}`	`knowledge:write`	Definir la frecuencia de sincronización, los elementos seleccionados o la herramienta de importación; o desconectar y purgar la conexión
`GET`	`/sites/{site_id}/knowledge-connections/{connection_id}/items`	`knowledge:read`	Listar las páginas, bases de datos o archivos que una conexión puede importar
`POST`	`/sites/{site_id}/knowledge-connections/{connection_id}/sync`	`knowledge:write`	Poner en cola una sincronización de una conexión de conocimiento

POST /knowledge acepta tres cuerpos: { "name", "text" } con entre 5 y 200 000 caracteres; { "url", "max_pages", "refresh_hours" } para rastrear un sitio web (max_pages de 1 a 40, refresh_hours de 1 a 8760 o null); y { "kind": "youtube" | "podcast" | "feed", "url", "refresh_hours" }. Las sources de YouTube, pódcast y feed requieren Operate o Scale; en Launch devuelven 409 conflict. La subida de archivos sigue siendo un flujo exclusivo del panel.

Conversaciones, leads, analítica y uso#

Método	Ruta	Scope	Finalidad
`GET`	`/sites/{site_id}/conversations`	`conversations:read`	Listar los hilos de conversación
`GET`	`/sites/{site_id}/conversations/{conversation_id}`	`conversations:read`	Obtener un hilo y sus mensajes paginados
`POST`	`/sites/{site_id}/conversations/{conversation_id}/reply`	`conversations:write`	Responder a un visitante en nombre del negocio
`POST`	`/sites/{site_id}/conversations/{conversation_id}/pause`	`conversations:write`	Pausar el agente en esta conversación y asumir el control
`POST`	`/sites/{site_id}/conversations/{conversation_id}/resume`	`conversations:write`	Devolver la conversación al agente
`GET`	`/sites/{site_id}/leads`	`leads:read`	Listar los leads capturados
`POST`	`/sites/{site_id}/leads`	`leads:write`	Crear un lead canónico con consentimiento y preferencias de contacto explícitos
`GET`	`/sites/{site_id}/leads/{lead_id}`	`leads:read`	Obtener un lead
`PATCH`	`/sites/{site_id}/leads/{lead_id}`	`leads:write`	Actualizar, calificar o cambiar la política de contacto de un lead
`POST`	`/sites/{site_id}/leads/{lead_id}/accept`	`leads:write`	Aceptar un lead en el pipeline de oportunidades
`POST`	`/sites/{site_id}/leads/{lead_id}/followup`	`leads:write`	Enviar el mensaje de seguimiento a un lead
`POST`	`/sites/{site_id}/leads/{lead_id}/followup/draft`	`leads:write`	Redactar de nuevo el mensaje de seguimiento sin enviarlo
`GET`	`/sites/{site_id}/analytics`	`analytics:read`	Listar los eventos de analítica
`GET`	`/sites/{site_id}/report`	`analytics:read`	Leer el informe de analítica agregado
`POST`	`/sites/{site_id}/report/unanswered-faq`	`knowledge:write`	Responder una pregunta sin respuesta como una nueva pregunta frecuente
`GET`	`/sites/{site_id}/usage`	`usage:read`	Listar los eventos de uso medido

Estas colecciones de eventos y actividad aceptan limit y cursor. Los registros devueltos pueden contener datos personales; almacénalos y expórtalos conforme a tus obligaciones de privacidad.

Se admiten las respuestas del owner: reply, pause y resume toman el control de un hilo web o de un chat de Telegram, WhatsApp, Messenger o Instagram igual que lo hace el panel. Enviar mensajes como si fueras el visitante no es una operación pública de la API. Se admite la modificación de leads; no establezcas consent_status: granted a menos que tu sistema tenga un registro de consentimiento defendible. Los leads con consentimiento desconocido se excluyen de los envíos masivos.

Pipeline de oportunidades y resultados de CRM#

Método	Ruta	Scope	Finalidad
`GET` / `POST`	`/sites/{site_id}/pipeline/stages`	`pipeline:read` / `pipeline:write`	Listar o configurar las etapas
`GET` / `POST`	`/sites/{site_id}/pipeline/accounts`	`pipeline:read` / `pipeline:write`	Listar o crear cuentas de empresa
`GET`	`/sites/{site_id}/pipeline/accounts/{account_id}`	`pipeline:read`	Obtener una cuenta de empresa
`GET` / `POST`	`/sites/{site_id}/pipeline/opportunities`	`pipeline:read` / `pipeline:write`	Listar o crear oportunidades
`GET` / `PATCH`	`/sites/{site_id}/pipeline/opportunities/{opportunity_id}`	`pipeline:read` / `pipeline:write`	Leer la actividad o actualizar la asignación, el valor, la etapa, la siguiente acción y la respuesta humana
`POST`	`/sites/{site_id}/pipeline/outcomes`	`pipeline:write`	Importar de forma idempotente un resultado de ganado o perdido procedente del CRM
`GET`	`/sites/{site_id}/pipeline/sync-records`	`pipeline:read`	Listar el estado de sincronización, los intentos y los errores
`POST`	`/sites/{site_id}/pipeline/sync-records/{sync_record_id}/retry`	`pipeline:write`	Reintentar un resultado fallido a partir de su payload almacenado
`GET` / `PATCH`	`/sites/{site_id}/pipeline-workflow`	`pipeline:read` / `pipeline:write`	Leer o actualizar la política de respuesta de ventas
`GET` / `POST`	`/sites/{site_id}/pilots`	`pipeline:read` / `pipeline:write`	Listar o iniciar pilotos guiados
`GET`	`/sites/{site_id}/pilots/{pilot_id}`	`pipeline:read`	Leer un piloto, su etapa, sus recuentos y su lista de trabajo
`POST`	`/sites/{site_id}/pilots/{pilot_id}/setup`, `/start`, `/stop`, `/review`, `/decision`, `/complete`, `/delete`	`pipeline:write`	Llevar un piloto por la configuración, la medición, la revisión, la decisión y el cierre, o eliminarlo junto con su evidencia (siete operaciones)
`POST`	`/sites/{site_id}/pilots/{pilot_id}/outcomes`, `/bookings`	`pipeline:write`	Registrar el resultado de un lead o el resultado de una reserva (dos operaciones)
`POST`	`/sites/{site_id}/pilots/{pilot_id}/report/approve`, `/report/revoke`	`pipeline:write`	Aprobar o revocar el informe del piloto que se puede compartir (dos operaciones)
`GET` / `POST`	`/sites/{site_id}/buyer-packs`	`pipeline:read` / `pipeline:write`	Listar los buyer packs o crear uno a partir de sources aprobadas
`PATCH`	`/sites/{site_id}/buyer-packs/{pack_id}`	`pipeline:write`	Reemplazar el título, la audiencia, el resumen, las sources y las secciones de un pack
`POST`	`/sites/{site_id}/buyer-packs/{pack_id}/approve`, `/revoke`	`pipeline:write`	Activar o desactivar el enlace para compartir del pack (dos operaciones)

El provider del CRM, el ID externo y la clave de idempotencia que proporciones permanecen en el registro de auditoría. Un reintento solo toma un registro fallido y nunca convierte una escritura externa en curso en un éxito falso.

Connectors#

Método	Ruta	Scope	Finalidad
`GET`	`/sites/{site_id}/connectors`	`connectors:read`	Listar el estado de los connectors sin secretos
`POST`	`/sites/{site_id}/connectors`	`connectors:write`	Conectar un channel: validar las credenciales en vivo, aprovisionar su webhook y devolver la lista de comprobación de configuración
`PATCH`	`/sites/{site_id}/connectors/{connector_id}`	`connectors:write`	Definir `status` o `reply_with_voice`
`DELETE`	`/sites/{site_id}/connectors/{connector_id}`	`connectors:write`	Desaprovisionar y eliminar un connector
`POST`	`/sites/{site_id}/concierge`	`connectors:write`	Pedir a la plataforma que conecte un canal de mensajería por ti
`GET`	`/sites/{site_id}/domains`	`domains:read`	Eliminado: devuelve `409`. No se ofrecen dominios personalizados
`POST`	`/sites/{site_id}/domains`	`domains:write`	Eliminado: devuelve `409`
`PATCH`	`/sites/{site_id}/domains/{domain_id}`	`domains:write`	Eliminado: devuelve `409`
`POST`	`/sites/{site_id}/domains/{domain_id}/verify`	`domains:write`	Eliminado: devuelve `409`
`DELETE`	`/sites/{site_id}/domains/{domain_id}`	`domains:write`	Eliminado: devuelve `409`

La creación de un connector usa un cuerpo discriminado por channel. Los campos de credenciales difieren para telegram, whatsapp, messenger, instagram, discord y kakao; usa la guía del connector correspondiente antes de enviar secretos.

Envíos masivos, notificaciones y monetización#

Método	Ruta	Scope	Finalidad
`GET`	`/sites/{site_id}/broadcasts`	`broadcasts:read`	Listar los envíos masivos
`POST`	`/sites/{site_id}/broadcasts`	`broadcasts:write`	Crear un borrador de envío masivo de Kakao
`POST`	`/sites/{site_id}/broadcasts/{broadcast_id}/send`	`broadcasts:write`	Poner en cola un borrador existente; devuelve `202`
`GET`	`/sites/{site_id}/notifications`	`notifications:read`	Listar las notificaciones del propietario
`POST`	`/sites/{site_id}/notifications/read-all`	`notifications:write`	Marcar como leídas todas las notificaciones del propietario de este agente
`PATCH`	`/sites/{site_id}/notifications/{notification_id}`	`notifications:write`	Marcar como leída o no leída con `{ "read": boolean }`
`GET`	`/sites/{site_id}/alerts`	`notifications:read`	Leer el estado del canal de alertas del propietario y su enlace del panel
`GET`	`/sites/{site_id}/monetization/products`	`monetization:read`	Listar los productos del sitio
`POST`	`/sites/{site_id}/monetization/products`	`monetization:write`	Crear un producto de tipo `access`, `consult`, `tip` o `digital`
`PATCH`	`/sites/{site_id}/monetization/products/{product_id}`	`monetization:write`	Actualizar los campos del producto y su estado activo
`DELETE`	`/sites/{site_id}/monetization/products/{product_id}`	`monetization:write`	Eliminar un producto

Actualmente, la creación de envíos masivos solo acepta el canal kakao. La puesta en cola falla con 409 conflict cuando no hay destinatarios alcanzables o cuando el envío masivo ya no es un borrador.

Acciones, tickets y equipo#

Método	Ruta	Scope	Finalidad
`GET` / `PATCH`	`/sites/{site_id}/actions`	`agents:read` / `agents:write`	Leer o configurar los procedimientos, el webhook público, el enlace de reservas y los tickets de soporte
`GET`	`/sites/{site_id}/tickets`	`tickets:read`	Listar los tickets de soporte
`GET`	`/sites/{site_id}/tickets/{ticket_id}`	`tickets:read`	Leer un ticket y sus mensajes
`PATCH`	`/sites/{site_id}/tickets/{ticket_id}`	`tickets:write`	Definir el estado, la prioridad y, opcionalmente, el responsable asignado
`POST`	`/sites/{site_id}/tickets/{ticket_id}/messages`	`tickets:write`	Añadir una nota interna, o establecer `internal: false` para responder al cliente por correo electrónico
`GET`	`/sites/{site_id}/team`	`team:read`	Leer los miembros, las invitaciones y los eventos de auditoría permitidos
`POST`	`/sites/{site_id}/team/invitations`	`team:write`	Crear un enlace de invitación sin enviar correo electrónico
`DELETE`	`/sites/{site_id}/team/invitations/{invitation_id}`	`team:write`	Revocar una invitación pendiente
`PATCH` / `DELETE`	`/sites/{site_id}/team/members/{membership_id}`	`team:write`	Cambiar el rol de un miembro que no sea propietario, o eliminar al miembro

Webhooks para desarrolladores y herramientas de configuración#

Método	Ruta	Scope	Finalidad
`GET`	`/webhook-endpoints`	`webhooks:read`	Listar el estado de los endpoints sin secretos de firma
`POST`	`/webhook-endpoints`	`webhooks:write`	Registrar una URL HTTPS pública y mostrar su secreto de firma una sola vez
`DELETE`	`/webhook-endpoints/{endpoint_id}`	`webhooks:write`	Eliminar un endpoint y detener las entregas futuras
`GET`	`/setup/tools`	Cualquier credencial válida	Descubrir las herramientas de configuración para integraciones de API, MCP y GitHub
`POST`	`/setup/tools/{tool_name}`	Específico de cada herramienta	Ejecutar una herramienta de configuración; las solicitudes de plataforma necesitan los scopes de sus endpoints, la inspección de GitHub usa `integrations:read` y la preparación de PR usa `integrations:write`

Las URL de webhook deben usar HTTPS, no pueden incluir credenciales ni un puerto personalizado, y deben resolverse únicamente a direcciones IP públicas.

Paginación#

Las colecciones paginadas aceptan limit de 1 a 100; el valor predeterminado es 50. Usa el next_cursor opaco devuelto únicamente con la misma colección y los mismos filtros.

{
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Algunas colecciones de configuración pequeñas devuelven el mismo envelope con has_more: false y no necesitan cursor.

Idempotencia#

Una clave de idempotencia debe tener entre 8 y 200 caracteres, formados por letras, números, ., _, : y -. Los resultados se conservan durante 24 horas y se asocian al propietario de la credencial.

Misma clave y mismo método, ruta, query y cuerpo: devuelve la respuesta almacenada con x-idempotent-replayed: true.
Misma clave con una entrada distinta: devuelve 409 conflict.
Misma clave mientras la primera solicitud aún se está procesando: devuelve 409 conflict y Retry-After: 2.

Guarda la clave antes de enviar la mutación y reutilízala solo para reintentos de esa misma operación lógica.

Respuestas y errores#

Las respuestas correctas envuelven su recurso en data. Las operaciones de creación normalmente devuelven 201; los envíos masivos puestos en cola devuelven 202; las demás operaciones correctas devuelven 200. Todas las respuestas incluyen x-request-id y usan Cache-Control: no-store para los datos de la API.

Consulta Scopes y errores para ver la tabla completa de códigos de error y Recetas de la API para flujos de trabajo que puedes copiar.

Clientes MCP#

Conecta un cliente MCP de Streamable HTTP a https://makeagent.fast/api/mcp. Los clientes compatibles con el descubrimiento de OAuth abren el navegador para el inicio de sesión y el consentimiento. Verifica la identidad del cliente, la empresa y los scopes solicitados antes de aprobar. La primera aprobación solicita los scopes que usan las herramientas (sites:read, sites:write, agents:write, analytics:read, conversations:read, conversations:write, leads:read, leads:write, knowledge:write); a una credencial a la que le falte alguno de ellos se le pide que vuelva a autorizar. Se requiere un plan activo.

Para los clientes que usan credenciales configuradas manualmente, crea una clave de API con scopes limitados en Ajustes de desarrollador y envíala como encabezado Authorization: Bearer .... Mantén las credenciales fuera del control de versiones y del código del navegador. Revoca las claves de API o las autorizaciones de OAuth desde los ajustes de desarrollador.

Herramientas de lectura: list_agents, get_agent, get_report, list_unanswered_questions, list_conversations, get_conversation, list_leads. Herramientas de escritura: create_agent_from_website, create_agent_from_notes, test_agent, add_knowledge, save_answer, reply_to_customer, update_lead, set_website_widget. Cada herramienta de agente recibe un agent_id obtenido de list_agents. test_agent consume créditos como una respuesta normal; reply_to_customer envía un mensaje al cliente y pausa el agente en esa conversación; set_website_widget activa o desactiva el widget de chat del sitio web; los canales de mensajería se gestionan en el panel. Los clientes con MCP Apps habilitado (de forma predeterminada, la conexión autenticada de Claude) también obtienen list_pending_approvals, list_action_runs y decide_approval, que aprueba o rechaza un cambio confirmado por el cliente; los demás clientes solo ven las 15 herramientas anteriores. Para las herramientas de configuración y de integración con GitHub, usa el asistente de configuración de la aplicación o /api/v1/setup/tools.

Las revisiones del protocolo compatibles son 2026-07-28, 2025-11-25 y 2025-06-18. El transporte devuelve JSON; no ofrece SSE heredado ni sesiones de servidor. Los tokens OAuth de MCP solo autorizan /api/mcp, no solicitudes REST directas. Los tokens de acceso OAuth duran una hora; las credenciales de actualización rotan y caducan a los 90 días. Las claves de API creadas manualmente usan la caducidad con la que se configuraron.