Getting Started with the Macha API

This guide walks you through your first authenticated request against the Macha API. By the end you'll have listed your organization's agents from your terminal, understood the response envelope, and know where to read next.

The API base URL is:

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

Every endpoint lives under this prefix. Every request needs an Authorization header. Every response is JSON.

Step 1, Generate an API key

Sign in to the Macha dashboard and head to Settings → API Keys. Click Create API Key, give it a label that identifies the integration, and pick the scopes it needs.

Macha API keys look like this:

mka_live_jbUaWzqeKB004Gr8FIHpRPoyVOq2Yzx9

The structure is intentional, the mka_live_ prefix lets us narrow lookups before doing the bcrypt compare on the suffix. The whole token is bcrypt-hashed at rest, so we cannot show it back to you after creation. Save it somewhere safe immediately.

Picking scopes

Macha API keys are scope-restricted. Every endpoint requires a specific scope like agents:read or conversations:write. There is no super-scope, a key with every capability still has to list each scope individually.

For your first integration, start with read-only scopes:

agents:read
conversations:read
connectors:read
org:read

You can always create a second key with broader scopes later. Macha never auto-elevates an existing key.

Step 2, Make your first request

Pass the key in the Authorization header with the Bearer scheme. Everything else is standard JSON-over-HTTPS.

curl https://dashboard.getmacha.com/api/v1/agents \
  -H "Authorization: Bearer mka_live_YOUR_KEY_HERE"

If the key is valid and has the agents:read scope, you'll get back a paginated list of your agents:

{
  "data": [
    {
      "id": "agent_64f1c0ef2ec711ef6dc1dcf",
      "handle": "ticketTriage",
      "name": "Triage",
      "description": "Routes incoming Zendesk tickets...",
      "model": "gpt-5.4",
      "is_active": true,
      "color": "#000000",
      "avatar": "🚦",
      "tools_count": 2,
      "sub_agents_count": 4,
      "created_at": "2026-06-10T04:07:44.871Z",
      "updated_at": "2026-06-17T07:29:29.408Z"
    }
  ],
  "meta": {
    "request_id": "req_a0b88aa084bac0f7",
    "next_cursor": "agent_..."
  }
}

What if it didn't work?

Common first-request failures and what they mean:

Status	Code	What to do
401	unauthorized	Header missing, malformed, or the token is wrong / revoked. Check you copied the full token including the mka_live_ prefix.
403	insufficient_scope	The token is real but doesn't have the scope this endpoint needs. Create a new token with agents:read.
404		Wrong URL. Check the path matches /api/v1/agents exactly.
429	rate_limited	You blew through the per-minute or per-hour limit. See Rate Limits.

Step 3, Understand the response envelope

Every successful Macha API response uses the same shape:

{
  "data": ,
  "meta": {
    "request_id": "req_a0b88aa084bac0f7",
    "next_cursor": "agent_..."
  }
}

Three rules:

• data is always the payload. For list endpoints it's an array; for single-resource endpoints it's an object.
• meta.request_id is always present. It's also returned in the X-Request-ID response header. Log it, if you ever need support, this is what we'll ask for.
• meta.next_cursor appears only on paginated list endpoints, and is null when there's no next page.

Errors use a different shape, also consistent across every endpoint:

{
  "error": {
    "code": "agent_not_found",
    "message": "Agent not found.",
    "request_id": "req_..."
  }
}

Customers code against the code field, not the message. The message is human-friendly; the code is stable. See the Errors reference for every code we emit.

Step 4, Make a write request

Read endpoints don't change state, so retries are safe. Write endpoints (POST, PATCH, DELETE) can change state, so Macha supports the Idempotency-Key header for retry safety. Pass any unique string and Macha will replay the cached response on retry within 24 hours.

curl -X POST https://dashboard.getmacha.com/api/v1/agents \
  -H "Authorization: Bearer mka_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "handle": "myFirstAgent",
    "name": "My First Agent",
    "instructions": "Answer questions politely and concisely."
  }'

Response:

{
  "data": {
    "id": "agent_...",
    "handle": "myFirstAgent",
    "name": "My First Agent",
    "model": null,
    "is_active": true,
    "tools_count": 0,
    "sub_agents_count": 0,
    "created_at": "2026-06-24T10:42:00.000Z",
    "updated_at": "2026-06-24T10:42:00.000Z"
  },
  "meta": { "request_id": "req_..." }
}

Retry the exact same request with the same Idempotency-Key and you'll get the cached response, no duplicate agent. See Idempotency for the full spec.

Step 5, What to read next

• Authentication, key lifecycle, full scope catalog, what each auth failure means
• Errors, every error code Macha emits, with retry guidance
• Pagination, cursor model for list endpoints
• Idempotency, safe retries for write requests
• Rate Limits, per-minute and per-hour caps with header semantics
• Agents, full CRUD for the agent resource