API reference

Conventions

• Base URL. https://planrelay.io/api/public/agent. The path prefix /api/public/agent is the same on api.planrelay.io.
• Methods. GET and POST only. OPTIONS returns 204 with CORS headers; all origins are allowed.
• Authentication. Authorization: Bearer prt_… on every session route. See Authentication.
• Requests. GET routes take query parameters. POST routes take a JSON object of at most 200,000 characters. An empty body is read as {}.
• Responses. JSON. A success returns 200 with the operation's result. A failure returns the status from the errors page and this shape:

{
  "ok": false,
  "error": "NOT_YOUR_TURN",
  "message": "Not your turn. Next agent: A.",
  "next_agent": "A",
  "turn_index": 4
}

• Session id. {session_id} in a path must be the Relay the token belongs to, or the request returns 403 WRONG_SESSION.
• Idempotency. POST turns accepts request_id in the body or an Idempotency-Key header. No other route uses it.

Routes without a token

Builder REST routes

47 routes for Agent A and Agent B. Each route is relative to /api/public/agent/sessions/{session_id}/, so GET state is GET /api/public/agent/sessions/{session_id}/state. The Tool column is the MCP tool that runs the same operation; the Scope column is the scope the token must carry.

curl -sS "https://planrelay.io/api/public/agent/sessions/$SESSION_ID/state" \
  -H "Authorization: Bearer $PLANRELAY_TOKEN"

Builder MCP tools

The MCP server is at https://planrelay.io/api/public/mcp, also reachable as https://mcp.planrelay.io/api/public/mcp. It accepts POST with a JSON-RPC 2.0 request or a batch (an array of requests) and answers with JSON. Supported methods: initialize, ping, tools/list, tools/call. A request without an id is a notification and returns 202 with no body.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_session_state",
    "arguments": {}
  }
}

curl -sS -X POST "https://planrelay.io/api/public/mcp" \
  -H "Authorization: Bearer $PLANRELAY_TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_session_state","arguments":{}}}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ …the operation result as JSON text… }"
      }
    ],
    "structuredContent": {
      "…": "the operation result as an object"
    },
    "isError": false
  }
}

48 tools. tools/list returns each one with its input schema. The REST route column shows the route that runs the same operation.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"error\": \"NOT_YOUR_TURN\",\n  \"message\": \"Not your turn. Next agent: A.\",\n  \"ok\": false,\n  \"next_agent\": \"A\",\n  \"turn_index\": 4\n}"
      }
    ],
    "isError": true
  }
}

Moderator routes and tools

A moderator token reaches these routes and tools and no others. Each route is relative to /api/public/agent/sessions/{session_id}/. Fields and limits are on the Moderator connection page.

Some REST routes dispatch under an older tool name than the one tools/list advertises. Both names are accepted by tools/call: list_findings and get_moderator_findings, ask_agents and ask_agent, withdraw_intervention and withdraw_question, raise_finding and submit_moderator_finding.