API

Estado

Pymaia expone sus capacidades de dos formas, ambas contra https://api.pymaia.com:

MCP (Model Context Protocol) en /mcp — la vía recomendada para usarlo desde herramientas de IA como Claude o ChatGPT. Ver MCP.
REST en /api/v1 — para integraciones propias, scripts o data warehouse. La documentación OpenAPI interactiva está en /docs (esquema en /api/openapi.json).

Las dos comparten el mismo motor y las mismas herramientas, así que lo que hacés por chat lo podés hacer por HTTP. Hay 162 endpoints — ver la Referencia completa.

Autenticación

Generás una API key en Ajustes → API Keys. Las claves tienen prefijo pymaia_ y las pasás como Bearer token (Authorization: Bearer pymaia_...).

El acceso siempre está scopeado a tu organización y respeta los mismos permisos que la app: un cliente nunca accede a datos de otro.
Cada clave se genera con scopes puntuales (ej. ads:read, ecommerce:read, tasks:write, agents:run, actions:approve). Dale solo los que necesita la integración; nunca hay una clave con acceso total implícito. Ver Scopes y permisos.
Las acciones que modifican tus plataformas siguen pasando por el Trust Layer (aprobación).

Arrancá en Primeros pasos — de cero a tu primera llamada en 2 minutos.

Estructura de una llamada

Todo endpoint es POST /api/v1/{tool} con body JSON y devuelve { ok, result, duration_ms }:

curl -sS https://api.pymaia.com/api/v1/get_kpi_summary \
  -H "Authorization: Bearer pymaia_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"days": 30}'

Los errores (auth, scope, rate limit, módulo apagado) están en Errores.

Feature flags por módulo

La API respeta los módulos habilitados de tu organización, igual que la UI: si tu plan no incluye un módulo (ej. MercadoLibre), sus endpoints devuelven 404 (no aparecen en /api/v1/tools ni en list_tools del MCP). En la Referencia cada endpoint gateado indica qué module_* requiere.

Webhooks

Algunas integraciones (ej. Shopify) ya funcionan con webhooks entrantes para sincronización en tiempo real. Para webhooks salientes hacia tus sistemas, escribinos desde Ayuda en la app o ver Contacto y soporte — te contamos qué está disponible hoy.