~ macha · API para desenvolvedores

Construa agentes de suporte do seu terminal.

Trabalhe com a Macha direto do seu coding agent. Passe a API key e entregue um agente funcionando, com conectores, ferramentas e triggers, sem sair da linha de comando.

Começar teste grátis Ler a doc da API

Funciona com Claude Code Codex Cursor

claude, monte um agente Macha

Bem-vindo ao Claude Code

Opus 4.8 · ~/macha-agents

> Aqui vai minha key da Macha: mka_live_••••

Monta um agente WISMO em cima do Shopify + Zendesk.

● Ler o contrato da API da Macha

┗ llms-full.txt · OpenAPI 3.1

● GET /connectors

┗ shopify · zendesk · stripe

● POST /agents → @wismo

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

✓ Criado @wismo · ativo no seu painel

Traga seu próprio coding agent.

A API é HTTP puro com docs que a IA consegue ler, então qualquer ferramenta de coding agentic consegue ler o contrato e construir em cima.

Claude Code

Aponte pra llms-full.txt + sua key, ele lê o contrato e constrói.

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

Codex

Aponte pra llms-full.txt + sua key, ele lê o contrato e constrói.

$ codex --doc $MACHA/openapi.json

Cursor

Aponte pra llms-full.txt + sua key, ele lê o contrato e constrói.

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

Todos funcionam pelo mesmo motivo: HTTP + llms.txt + OpenAPI. Sem lock-in de SDK, o mesmo fluxo roda do cURL ou de qualquer cliente HTTP.

Tudo que um coding agent precisa pra pilotar a Macha.

Uma superfície REST limpa, keys de menor privilégio, e documentação escrita pra ser lida por máquina.

Uma API REST de verdade

Auth Bearer, um envelope { data, meta }, códigos de erro estáveis, escritas idempotentes, e limites de 1.000/min · 10.000/hora.

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

Keys com escopo

Gere keys mka_live_… em Configurações → API Keys com escopos {resource}:{action}. Menor privilégio, escopo de organização, mostradas uma vez (com hash bcrypt).

mka_live_•••• · agents:write

Docs legíveis por IA

llms.txt + llms-full.txt em www.getmacha.com, mais uma spec OpenAPI 3.1 com x-required-scope em cada operação.

/api/v1/openapi.json

Da key ao agente rodando, em uma sessão.

1

Gere uma key com escopo

Em Configurações → API Keys, gere uma key mka_live_ só com os escopos que você precisar. É mostrada uma vez.
2

Aponte seu coding agent pra doc

Solte llms-full.txt + a spec OpenAPI no Claude Code ou Codex e defina MACHA_API_KEY.
3

Ele lista conectores pra descobrir ferramentas

O agente chama GET /connectors pra pegar os nomes reais das ferramentas na sua org, sem chutar.
4

Ele faz um /agents pra criar

Um único POST /agents idempotente conecta instruções e tools. A resposta traz o novo agent ID.

claude, monte um 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 o que você pode construir.

Um mapa honesto da superfície v1. Configuração e conteúdo são programáveis; o runtime ao vivo, cobrança e superfícies críticas de segurança ficam no painel, por design.

Agentes

CRUD completo

Criar, ler, atualizar, deletar, instruções e as tools que cada agente pode chamar.

Custom tools

CRUD completo

Registre sua própria API REST como tools de agente com POST /custom_tools.

Fontes

CRUD completo

Gerencie as fontes de conhecimento por trás dos seus agentes de forma programática.

Conversas

Leitura

Pagine o histórico de conversas pro seu warehouse. Só leitura, paginação por cursor.

Conectores

Leitura

Lista os conectores e seus nomes de tool ligados na sua org.

No v1, triggers são só leitura, configure triggers webhook e agendados no painel e depois lê pela API. Rodar um turno de chat ao vivo, cobrança, Studies e Sidekick ficam só no painel, por design.

Por que uma IA consegue realmente pilotar.

✓
Um envelope de resposta em todo lugar. Todo endpoint retorna { data, meta } com um request_id e um next_cursor. Aprende o formato uma vez.
✓
Códigos de erro estáveis, discerníveis por máquina. Erros carregam um code estável, não só texto.
✓
Escopos são descobríveis. Um 403 mais x-required-scope avisa exatamente qual escopo o agente deve te pedir.
✓
Retries idempotentes nunca duplicam. Escritas respeitam um Idempotency-Key com replay de 24h.

Um envelope, em todo lugar

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

Erros que um modelo consegue ramificar

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

Guardrails que deixam seguro delegar.

Entregar uma key pra um agente autônomo só rola se o raio de estrago for pequeno, reversível e auditável.

safe-to-delegate

✓
Keys com escopo de menor privilégio — a key só faz o que você concedeu.
✓
Escritas idempotentes — Idempotency-Key garante que retries nunca duplicam.
✓
Rate limits por key — 1.000/min · 10.000/hora, com Retry-After no 429.
✓
Delete suave — deletes vão pra lixeira de 30 dias com restaurar de um clique.
✓
Trilha de auditoria — toda ação da API vem marcada "criado via API key <label>".
✓
Auto-revogação em vazamento — o prefixo mka_live_ é escaneado no GitHub público e revogado automaticamente.

Além de um agente.

Uma vez que é API, sua caixa de ferramentas de workflow inteira se aplica.

Agentes como código no Git

Mantenha as definições de agente no seu repo e o CI faz PATCH /agents no merge. Revise mudanças de prompt como se fosse código.

Ligação em massa

Suba um sub-agente por linha de produto num loop, horas de clique viram um script.

Sua própria API como tools

Registre endpoints REST internos com POST /custom_tools pra que os agentes chamem seus sistemas.

Conversas pro seu warehouse

Pagine GET /conversations com o cursor pra BigQuery ou Snowflake.

.github/workflows/agents.yml

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

// custo

A API é grátis. Construir e gerenciar agentes pela API custa zero créditos, sem metering, em todas as contas, incluindo trials. Você só gasta crédito quando um agente que você montou de fato roda (trabalha um ticket ou dispara num trigger).

O que você construiria com a API da Macha?

Pegue sua API key → # depois cole sua key no Claude Code, Codex ou Cursor

Ou leia a documentação da API.

Perguntas frequentes.

O que a API pode e não pode, como está protegida, e com quais coding agents ela funciona.

Sim, porque a key só carrega os escopos que você conceder, e é de escopo de organização. Dá pra um agente de descoberta uma key só de leitura; guarde agents:write pra quando você realmente quiser que ele construa. Deletes são suaves (lixeira de 30 dias), a idempotência evita duplicatas, toda mudança fica auditada com um request_id e o label da key, e o prefixo mka_live_ é escaneado pelo GitHub e pelo GitGuardian, então uma key vazada é auto-revogada.

No v1, triggers, chatbots, team, analytics e org são só leitura, você configura triggers webhook e agendados no painel e depois lê pela API. Rodar um turno de chat ao vivo, cobrança, Studies e Sidekick ficam só no painel, por design. A API é pra construir e gerenciar agentes (agents, custom tools e sources são CRUD completo), não pra servir uma conversa em tempo real.

A API em si é grátis. Gerar keys e usá-las pra construir e gerenciar agentes, conectores, tools e sources custa zero créditos, sem cobrança por chamada nem metering de API, e está disponível em todas as contas, incluindo trials. Isso porque a API é uma camada de gestão, não de execução: ela configura os agentes no seu painel, mas não os roda. Créditos só são gastos quando um agente de fato roda, dispara num trigger ou trabalha um ticket e toma ações reais. Esse custo de runtime é por crédito (por ação de IA, por modelo) e é o mesmo se o agente foi construído na mão ou pela API.

Qualquer agente que consiga rodar comandos de shell e ler uma URL. Claude Code, Codex e Cursor são os óbvios: aponta pra llms-full.txt e pra spec OpenAPI, define MACHA_API_KEY no ambiente, e eles têm tudo pra descobrir seus conectores e criar agentes. Como é uma API REST comum atrás de um Bearer, o mesmo fluxo roda de qualquer script ou framework.

Cada key é restrita a um conjunto de escopos {recurso}:{ação}, por exemplo agents:read e agents:write. Toda operação na spec OpenAPI declara o escopo necessário via x-required-scope, então um agente vê o que uma chamada exige antes de fazer. Se a key não tem um escopo, a chamada retorna 403 insufficient_scope nomeando exatamente o que falta, o agente pode então pedir pra você ampliar a key.

Entregue sua key pro seu coding agent. Comece a construir.

Começar teste grátis Ler a doc da API

500 créditos grátis · sem limite de tempo, sem cartão