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

Every payload identifies an agent with a structured agentId object. It contains a workspace and an agent path array with one element for a root agent and more for child agents.

{"agentId": {"workspace": "myws", "agent": ["fix-auth-bug", "api"]}}

You only need workspace and the agent path. Murmur fills in your tenant and account from the authenticated caller. Anything you set explicitly is passed through exactly as you sent it. Agent-scoped operations, including reads and mutations, use POST with the agentId in the JSON body.

# 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

Catalog endpoints carry the resource document in a payload field as base64-encoded JSON. Decode it on read and 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 returns when the agent 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