> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Murmur REST API reference and getting started

> REST API for Murmur — spawn agents, track progress, manage tasks, and read and write catalog resources like workspaces and personas from any HTTP client.

<Warning>
  **PRE-ALPHA: INTERFACE SUBJECT TO CHANGE WITHOUT NOTICE**
</Warning>

The murmur REST API lets you spawn agents, track their progress, manage their task lists, and read and write catalog resources from any HTTP client. Every operation is a plain HTTP+JSON endpoint.

## Base URL

```
https://api.murmur.dev/v1
```

Requests and responses are `application/json`. Field names are lowerCamelCase, enums are strings, 64-bit integers are strings, and binary values are base64 strings.

## Authentication

Authenticate every request with a murmur [API key](/security/api-keys):

```bash theme={null}
export MURMUR_API_KEY="mur_<key_id>.<secret>"

curl -s https://api.murmur.dev/v1/whoami \
  -H "Authorization: Bearer $MURMUR_API_KEY"
```

## Agent identity

Agent identity in every payload is the structured `agentId` object: a `workspace` plus the `agent` path array — one element for a root agent, more for children:

```json theme={null}
{"agentId": {"workspace": "myws", "agent": ["fix-auth-bug", "api"]}}
```

You only need `workspace` and the agent path — murmur fills in your tenant and account automatically from the authenticated caller. Anything you set explicitly is passed through exactly as you sent it.

Agent-scoped operations use `POST` with the `agentId` in the JSON body — reads and mutations alike:

```bash theme={null}
# Get an agent's status
curl -s -X POST https://api.murmur.dev/v1/agent/status \
  -H "Authorization: Bearer $MURMUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":{"workspace":"myws","agent":["fix-auth-bug"]}}'

# Spawn an agent
curl -s -X POST https://api.murmur.dev/v1/agent/spawn \
  -H "Authorization: Bearer $MURMUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":{"workspace":"myws","agent":["fix-auth-bug"]},"description":"Fix the auth bug in login flow","expectedOutput":"pr"}'
```

## Errors

Errors return a consistent JSON body: a numeric `code`, a human-readable `message`, and optional machine-readable `details`:

```json theme={null}
{"code": 5, "message": "agent \"no-such-agent\" not found", "details": []}
```

The `code` value and the HTTP status always correspond:

| `code` | Meaning             | HTTP status |
| ------ | ------------------- | ----------- |
| 3      | `INVALID_ARGUMENT`  | 400         |
| 5      | `NOT_FOUND`         | 404         |
| 7      | `PERMISSION_DENIED` | 403         |
| 16     | `UNAUTHENTICATED`   | 401         |

## Catalog payloads are base64-encoded JSON

The catalog endpoints carry the resource document in a `payload` field as a base64-encoded JSON document — decode it on read, encode it on write:

```bash theme={null}
# Read a workspace resource: decode the payload to get the resource JSON.
curl -s https://api.murmur.dev/v1/catalog/workspace/myws \
  -H "Authorization: Bearer $MURMUR_API_KEY" | jq -r .payload | base64 -d

# Write it back: encode the edited resource JSON into the payload.
curl -s -X POST https://api.murmur.dev/v1/catalog/workspace/myws \
  -H "Authorization: Bearer $MURMUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"payload\":\"$(jq -c . workspace.json | base64 -w0)\"}"
```

## Blocking on completion

`POST /v1/agent/wait` blocks until the agent needs attention — it finishes, fails, or comes to rest waiting for input. Bound the wait with your client's timeout:

```bash theme={null}
curl -s --max-time 600 -X POST https://api.murmur.dev/v1/agent/wait \
  -H "Authorization: Bearer $MURMUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":{"workspace":"myws","agent":["fix-auth-bug"]}}'
```

Disconnecting cancels the server-side call.