Murmur REST API reference and getting started

PRE-ALPHA: INTERFACE SUBJECT TO CHANGE WITHOUT NOTICE

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:

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:

{"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:

# 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:

{"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:

# 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:

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.

Getting Started

Core Concepts

Guides

Murmur REST API reference and getting started

Base URL

Authentication

Agent identity

Errors

Catalog payloads are base64-encoded JSON

Blocking on completion

​Base URL

​Authentication

​Agent identity

​Errors

​Catalog payloads are base64-encoded JSON

​Blocking on completion

Base URL

Authentication

Agent identity

Errors

Catalog payloads are base64-encoded JSON

Blocking on completion