Guía de inicio rápido de la API

Esta guía de inicio rápido verifica que un backend pueda autenticarse y leer tu cuenta. Necesitas un plan de pago activo, una terminal con curl y acceso a Panel → Ajustes → Desarrollador.

La API v1 actual gestiona y sincroniza recursos. No es un medio de transporte para chats personalizados: no puedes enviar mensajes como si fueras un visitante. Los leads se pueden crear, actualizar y aceptar (leads:write), y un propietario puede responder a una conversación, pausarla o reanudarla (conversations:write).

1. Crea una clave con privilegios mínimos#

Crea una clave llamada Local API quickstart, selecciona account:read y sites:read, y elige una caducidad corta. Copia la clave en texto plano de inmediato; no se volverá a mostrar.

No uses una clave de proveedor de IA, como una clave de OpenRouter o de Speko. La API pública requiere una clave de Make Agent Fast que comience por maf_live_.

2. Guárdala para esta terminal#

export MAF_API_KEY="maf_live_..."

Confirma que la variable existe sin imprimir el secreto:

test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"

No incluyas la clave en .env, en ejemplos del historial de la shell, en datos de prueba ni en un bundle del navegador. Para el código desplegado, usa el gestor de secretos de tu proveedor de alojamiento.

3. Inspecciona la cuenta#

curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Estado esperado: 200 OK. El cuerpo contiene data.id, información del plan y de los derechos de uso, y un resumen del monedero. La respuesta también incluye x-request-id; conserva ese valor al reportar una solicitud fallida.

{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "owner@example.com",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}

Se pueden añadir campos sin cambiar la ruta /v1. Ignora los campos desconocidos en lugar de rechazar la respuesta.

4. Lista los sitios#

curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Las respuestas de colecciones usan esta estructura:

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

Si has_more es true, envía el valor exacto de next_cursor como parámetro de consulta cursor en la siguiente solicitud. No decodifiques ni construyas cursores.

5. Gestiona un error estructurado#

Quita temporalmente el encabezado Authorization y repite la solicitud a /me. La respuesta debería ser 401 con un código estable:

{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}

El código de producción debe ramificarse según error.code, no comparar message. Registra la operación, el estado HTTP y el ID de solicitud sin registrar la clave.

6. Realiza la primera escritura de forma segura#

Crea una clave aparte que además tenga sites:write, agents:write y knowledge:write; no amplíes la clave de lectura de esta guía. Sigue las recetas de la API para crear un sitio, añadir conocimiento fundamentado y publicarlo usando claves de idempotencia explícitas.

Errores habituales en la primera solicitud#

Continúa con Scopes y errores, la referencia de la API y los límites de frecuencia.