~ macha · API para desarrolladores

Construye agentes de soporte desde tu terminal.

Trabaja con Macha directamente desde tu coding agent. Dale tu API key y despliega un agente funcional, con conectores, herramientas y triggers, sin salir de la línea de comandos.

Empezar prueba gratis Leer la doc del API

Compatible con Claude Code Codex Cursor

claude, crea un agente de Macha

Bienvenido a Claude Code

Opus 4.8 · ~/macha-agents

> Aquí va mi Macha key: mka_live_••••

Crea un agente WISMO sobre Shopify + Zendesk.

● Leer el contrato del API de Macha

┗ llms-full.txt · OpenAPI 3.1

● GET /connectors

┗ shopify · zendesk · stripe

● POST /agents → @wismo

┗ { id: "agent_7Qh2…", tools: 3, is_active: true }

✓ Creado @wismo · vivo en tu dashboard

Trae tu propio coding agent.

El API es HTTP puro con docs que un modelo puede leer, así que cualquier herramienta de coding agentic puede leer el contrato y construir contra él.

Claude Code

Apúntale a llms-full.txt + tu key, lee el contrato y construye.

$ claude "read $MACHA/llms-full.txt"

Codex

Apúntale a llms-full.txt + tu key, lee el contrato y construye.

$ codex --doc $MACHA/openapi.json

Cursor

Apúntale a llms-full.txt + tu key, lee el contrato y construye.

@Docs → getmacha.com/llms-full.txt

Todos funcionan por lo mismo: HTTP + llms.txt + OpenAPI. Sin lock-in de SDK, el mismo flujo corre desde cURL o cualquier cliente HTTP.

Todo lo que un coding agent necesita para manejar Macha.

Una superficie REST limpia, keys de mínimo privilegio y documentación pensada para que la lea una máquina.

Un API REST de verdad

Auth Bearer, una envoltura { data, meta }, códigos de error estables, escrituras idempotentes, y límites 1.000/min · 10.000/hora.

https://dashboard.getmacha.com/api/v1

Keys con scope

Emite keys mka_live_… desde Ajustes → API Keys con scopes {resource}:{action}. Mínimo privilegio, scope de organización, se muestran una vez (hasheadas con bcrypt).

mka_live_•••• · agents:write

Docs legibles por IA

llms.txt + llms-full.txt en www.getmacha.com, más una spec OpenAPI 3.1 con x-required-scope en cada operación.

/api/v1/openapi.json

De la key al agente funcionando, en una sesión.

1

Genera una key con scope

En Ajustes → API Keys, emite una key mka_live_ solo con los scopes que necesitas. Se muestra una vez.
2

Apunta tu coding agent a la doc

Suelta llms-full.txt + la spec OpenAPI en Claude Code o Codex y define MACHA_API_KEY.
3

Lista conectores para descubrir herramientas

El agente llama a GET /connectors para saber los nombres reales de las herramientas en tu org, sin adivinar.
4

Hace /agents para crearlo

Un único POST /agents idempotente conecta instrucciones y tools. La respuesta trae el nuevo agent ID.

claude, crea un agente WISMO

$ export MACHA_API_KEY=mka_live_••••
$ curl -s $MACHA/api/v1/connectors
  → shopify · zendesk · …
$ curl -s -X POST $MACHA/api/v1/agents -d '{
    "handle":"wismo", "tools":[
      "shopify_get_order",
      "shopify_search_orders",
      "zendesk_add_public_reply" ] }'
  { "data":{ "id":"agent_7Qh2…", "handle":"@wismo",
    "model":"claude-sonnet", "tools_count":3 } }
✓ created

Contra qué puedes construir.

Un mapa honesto de la superficie v1. Configuración y contenido son programables; el runtime en vivo, la facturación y las superficies críticas de seguridad se quedan en el dashboard a propósito.

Agentes

CRUD completo

Crear, leer, actualizar, borrar, instrucciones y las tools que cada agente puede llamar.

Custom tools

CRUD completo

Registra tu propia API REST como tools de agentes con POST /custom_tools.

Fuentes

CRUD completo

Gestiona las fuentes de conocimiento detrás de tus agentes de forma programática.

Conversaciones

Lectura

Pagina el historial de conversaciones a tu warehouse. Solo lectura, paginado por cursor.

Conectores

Lectura

Lista los conectores y sus nombres de tool cableados en tu org.

En v1 los triggers son solo lectura, configura triggers webhook y agendados en el dashboard y luego los lees por API. Correr una interacción de chat en vivo, facturación, Studies y Sidekick se quedan solo en el dashboard por diseño.

Por qué una IA puede manejarlo de verdad.

✓
Una envoltura de respuesta en todos lados. Cada endpoint devuelve { data, meta } con un request_id y un next_cursor. Aprende la forma una vez.
✓
Códigos de error estables, decidibles por máquina. Los errores llevan un code estable, no solo texto.
✓
Los scopes se descubren solos. Un 403 más x-required-scope le dice al agente exactamente qué scope pedirte.
✓
Los reintentos idempotentes no duplican. Las escrituras respetan un Idempotency-Key con replay de 24h.

Una envoltura, en todos lados

{ "data": { … },
  "meta": { "request_id":"req_a1b2c3",
          "next_cursor":"eyJpZ…" } }

Errores sobre los que un modelo puede ramificar

{ "error": {
    "code":"insufficient_scope",
    "message":"needs agents:write" } }

Barreras que lo hacen seguro para delegar.

Darle una key a un agente autónomo solo funciona si el radio de daño es pequeño, reversible y auditable.

seguro-para-delegar

✓
Keys con scope de mínimo privilegio — una key solo hace lo que le concediste.
✓
Escrituras idempotentes — Idempotency-Key significa que los reintentos nunca duplican.
✓
Rate limits por key — 1.000/min · 10.000/hora, con Retry-After en 429.
✓
Borrado suave — los borrados van a una papelera de 30 días con restauración a un clic.
✓
Traza de auditoría — cada acción del API queda marcada "creado vía API key <label>".
✓
Revocación automática ante fugas — el prefijo mka_live_ se escanea en GitHub público y se revoca automáticamente.

Más allá de un solo agente.

En cuanto es un API, aplica todo tu toolbox de workflows.

Agentes como código en Git

Guarda las definiciones de agentes en tu repo y que CI haga PATCH /agents al mergear. Revisa cambios de prompt como si fueran código.

Cableado en masa

Levanta un sub-agente por línea de producto en un bucle, horas de clicar se vuelven un script.

Tu propia API como tools

Registra endpoints REST internos con POST /custom_tools para que los agentes llamen a tus sistemas.

Conversaciones a tu warehouse

Pagina GET /conversations con el cursor hacia BigQuery o Snowflake.

.github/workflows/agents.yml

# sincroniza config del agente en cada merge a main
$ curl -X PATCH $MACHA/api/v1/agents/$ID \
    -H "Idempotency-Key: $GITHUB_SHA" \
    --data @agents/wismo.json
✓ wismo actualizado · req_4f8a…

// coste

El API es gratis. Construir y gestionar agentes vía API cuesta cero créditos, sin metering, en todas las cuentas, incluidas las de prueba. Solo gastas créditos cuando un agente que has construido corre de verdad (trabaja un ticket o dispara en un trigger).

¿Qué podrías construir con el API de Macha?

Obtén tu API key → # luego pega tu key en Claude Code, Codex o Cursor

O lee la documentación del API.

Preguntas frecuentes.

Qué puede y no puede hacer el API, cómo está protegido y con qué coding agents funciona.

Sí, porque la key solo lleva los scopes que le concedes, y es de organización. Dale a un agente de descubrimiento una key de solo lectura; reserva agents:write para cuando realmente quieras que construya. Los borrados son suaves (papelera de 30 días con restauración), la idempotencia evita duplicados, cada cambio queda auditado con un request_id y el label de la key, y el prefijo mka_live_ lo escanean GitHub y GitGuardian, así que una key filtrada se auto-revoca.

En v1, triggers, chatbots, team, analítica y org son de solo lectura, configuras triggers webhook y agendados en el dashboard y luego los lees por API. Correr una interacción de chat en vivo, facturación, Studies y Sidekick son solo dashboard por diseño. El API es para construir y gestionar agentes (agents, custom tools y sources son CRUD completo), no para servir una conversación en tiempo real.

El API en sí es gratis. Generar keys y usarlas para construir y gestionar agentes, conectores, tools y sources cuesta cero créditos, sin cargo por llamada ni metering del API, y está en todas las cuentas, incluidas las de prueba. Es así porque el API es una capa de gestión, no de ejecución: configura agentes en tu dashboard, no los corre. Los créditos se gastan solo cuando un agente corre, dispara en un trigger o trabaja un ticket y ejecuta acciones reales. Ese coste de runtime es por créditos (por acción de IA, por modelo) y es el mismo si el agente se construyó a mano o por API.

Cualquier agente que pueda ejecutar comandos de shell y leer una URL. Claude Code, Codex y Cursor son los obvios: apúntalos a llms-full.txt y a la spec de OpenAPI, define MACHA_API_KEY en el entorno y ya tienen todo lo necesario para descubrir tus conectores y crear agentes. Como es un REST plano con Bearer, el mismo flujo funciona desde cualquier script o framework.

Cada key se limita a un conjunto de scopes {recurso}:{acción}, por ejemplo agents:read y agents:write. Cada operación de la spec de OpenAPI declara el scope que necesita vía x-required-scope, así un agente ve qué requiere una llamada antes de hacerla. Si a la key le falta un scope, la llamada devuelve 403 insufficient_scope nombrando exactamente lo que falta, el agente puede entonces pedirte que amplíes la key.

Dale la key a tu coding agent. Empieza a construir.

Empezar prueba gratis Leer la doc del API

500 créditos gratis · sin límite de tiempo, sin tarjeta