~ macha · API for developers

Build support agents from your terminal.

Work with Macha directly from your coding agent. Hand it your API key and ship a working agent — connectors, tools, and triggers — without leaving the command line.

Start free trial Read the API docs

Works with Claude Code Codex Cursor

claude — build a Macha agent

✻ Welcome to Claude Code

Opus 4.8 · ~/macha-agents

> Here's my Macha key: mka_live_••••

Build a WISMO agent on Shopify + Zendesk.

● Read the Macha API contract

┗ llms-full.txt · OpenAPI 3.1

● GET /connectors

┗ shopify · zendesk · stripe

● POST /agents → @wismo

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

✓ Created @wismo · live in your dashboard

Bring your own coding agent.

The API is plain HTTP with AI-ingestible docs — so any agentic coding tool can read the contract and build against it.

Claude Code

Point it at llms-full.txt + your key — it reads the contract and builds.

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

Codex

Point it at llms-full.txt + your key — it reads the contract and builds.

$ codex --doc $MACHA/openapi.json

Cursor

Point it at llms-full.txt + your key — it reads the contract and builds.

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

They all work for the same reason: it's HTTP + llms.txt + OpenAPI. No SDK lock-in — the same flow runs from cURL or any HTTP client.

Everything a coding agent needs to drive Macha.

A clean REST surface, least-privilege keys, and documentation written to be read by a machine.

A real REST API

Bearer auth, a { data, meta } envelope, stable error codes, idempotent writes, and 1,000/min · 10,000/hr rate limits.

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

Scoped keys

Mint mka_live_… keys from Settings → API Keys with {resource}:{action} scopes. Least-privilege, org-scoped, shown once (bcrypt-hashed).

mka_live_•••• · agents:write

AI-ingestible docs

llms.txt + llms-full.txt on www.getmacha.com, plus an OpenAPI 3.1 spec with x-required-scope on every operation.

/api/v1/openapi.json

From key to working agent — in one session.

1

Generate a scoped key

In Settings → API Keys, mint an mka_live_ key with just the scopes you need. It's shown once.
2

Point your coding agent at the docs

Drop llms-full.txt + the OpenAPI spec into Claude Code or Codex and set MACHA_API_KEY.
3

It lists connectors to discover tools

The agent calls GET /connectors to learn the real tool names in your org — no guessing.
4

It POSTs /agents to create it

A single idempotent POST /agents wires up instructions and tools. The response carries the new agent ID.

claude — build a WISMO agent

$ 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

What you can build against.

An honest map of the v1 surface. Configuration and content are programmable; the live runtime, billing, and safety-critical surfaces stay in the dashboard by design.

Agents

Full CRUD

Create, read, update, delete — instructions and the tools each agent can call.

Custom tools

Full CRUD

Sources

Full CRUD

Manage the knowledge sources behind your agents programmatically.

Conversations

Read

Page conversation history into your warehouse. Read-only, cursor-paginated.

Connectors

Read

List the connectors and their tool names wired up in your org.

Triggers are read-only in v1 — set up webhook and scheduled triggers in the dashboard, then read them back. Running a live chat turn, billing, Studies, and Sidekick stay dashboard-only by design.

Why an AI can actually drive it.

✓
One response envelope everywhere. Every endpoint returns { data, meta } with a request_id and next_cursor. Learn the shape once.
✓
Stable, machine-switchable error codes. Errors carry a stable code, not just prose.
✓
Scopes are discoverable. A 403 plus x-required-scope tells the agent exactly which scope to ask you for.
✓
Idempotent retries never duplicate. Writes honor an Idempotency-Key with 24h replay.

One envelope, everywhere

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

Errors a model can switch on

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

Guardrails that make it safe to delegate.

Handing a key to an autonomous agent only works if the blast radius is small, reversible, and auditable.

safe-to-delegate

✓
Least-privilege scoped keys — a key only does what you granted.
✓
Idempotent writes — Idempotency-Key means retries never duplicate.
✓
Rate limits per key — 1,000/min · 10,000/hr, with Retry-After on 429.
✓
Soft delete — deletes land in a 30-day trash with one-click restore.
✓
Audit trail — every API action is tagged "created via API key <label>".
✓
Leak auto-revoke — the mka_live_ prefix is scanned on public GitHub and revoked automatically.

Beyond one agent.

Once it's an API, your whole workflow toolbox applies.

Agents-as-code in Git

Keep agent definitions in your repo and have CI PATCH /agents on merge. Review prompt changes like code.

Bulk wiring

Spin up a sub-agent per product line in a loop — hours of clicking becomes a script.

Your own API as tools

Conversations into your warehouse

Page GET /conversations with the cursor into BigQuery or Snowflake.

.github/workflows/agents.yml

# sync agent config on every merge to main
$ curl -X PATCH $MACHA/api/v1/agents/$ID \
    -H "Idempotency-Key: $GITHUB_SHA" \
    --data @agents/wismo.json
✓ wismo updated · req_4f8a…

// cost

The API is free. Building and managing agents over the API costs zero credits — no metering, on every account including trials. You only spend credits when an agent you've built actually runs (works a ticket or fires on a trigger).

What could you build with the Macha API?

Get your API key → # then paste your key into Claude Code, Codex, or Cursor

Or read the API documentation.

Frequently asked questions.

What the API can and can't do, how it's secured, and which coding agents it works with.

Yes — because the key only carries the scopes you grant it, and it's org-scoped. Give a discovery agent a read-only key; reserve agents:write for when you actually want it to build. Deletes are soft (30-day trash restore), idempotency prevents duplicate writes, every change is audited with a request_id and the key's label, and the mka_live_ prefix is scanned by GitHub and GitGuardian so a leaked key auto-revokes.

In v1, triggers, chatbots, team, analytics, and org are read-only — you set up webhook and scheduled triggers in the dashboard, then read them back over the API. Running a live chat turn, billing, Studies, and Sidekick are dashboard-only by design. The API is for building and managing agents (agents, custom tools, and sources are full CRUD), not for serving a conversation in real time.

The API itself is free. Generating keys and using them to build and manage agents, connectors, tools, and sources costs zero credits — there's no per-call charge and no API metering, and it's available on every account, including trials. That's because the API is a management layer, not an execution one: it configures agents on your dashboard, it doesn't run them. Credits are only spent when an agent actually runs — fires on a trigger or works a ticket and takes real actions. That runtime cost is credit-based (per AI action, by model) and is the same whether the agent was built by hand or over the API.

Any agent that can run shell commands and read a URL. Claude Code, Codex, and Cursor are the obvious fits: point them at llms-full.txt and the OpenAPI spec, set MACHA_API_KEY in the environment, and they have everything they need to discover your connectors and create agents. Because it's a plain REST API behind a Bearer token, the same flow works from any script or framework.

Each key is restricted to a set of {resource}:{action} scopes — for example agents:read and agents:write. Every operation in the OpenAPI spec declares the scope it needs via x-required-scope, so an agent can see what a call requires before it makes it. If a key is missing a scope, the call returns 403 insufficient_scope naming exactly what's needed — the agent can then ask you to widen the key.

Hand your key to your coding agent. Start building.

Start free trial Read the API docs

7-day free trial · no credit card required