Primeros pasos (API)

De cero a tu primera respuesta con datos reales en dos minutos.

1. Generá una API key

En Pymaia, andá a Ajustes → API Keys y creá una clave. Elegí solo los scopes que tu integración necesita (ej. ecommerce:read para leer ventas). Copiá la clave — tiene prefijo pymaia_ y solo se muestra una vez.

2. Hacé tu primera llamada

Todo endpoint es POST https://api.pymaia.com/api/v1/{tool} con Bearer token y body JSON:

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}'

Respuesta:

{
  "ok": true,
  "result": { "revenue": 12500, "orders": 84, "roas": 3.2, "...": "..." },
  "duration_ms": 210
}

Si ok es false, mirá error y outcome — el detalle está en Errores.

3. Descubrí los endpoints disponibles

Tu key solo ve las tools que tu org y tu plan habilitan:

curl -sS https://api.pymaia.com/api/v1/tools \
  -H "Authorization: Bearer pymaia_TU_CLAVE"

Devuelve { count, tools: [{ name, description, scopes, rate_limit_per_minute }] }. La Referencia tiene los 162 endpoints con sus parámetros, y el esquema OpenAPI vive en /api/openapi.json (UI interactiva en /docs).

Ejemplo: leer las últimas órdenes

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

Multi-organización (agencias)

Si tu key es de una agencia, podés operar sobre una org cliente accesible pasando el header X-Pymaia-Org:

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

El override solo funciona sobre orgs accesibles para el usuario dueño de la key; cualquier otra devuelve error.

Siguiente paso

• Referencia completa — todos los endpoints.
• Scopes y permisos — qué habilita cada scope.
• Errores — códigos y cómo resolverlos.
• MCP — usarlo desde Claude/ChatGPT sin escribir código.