Developer surface / read-only map

Everything on
the plane.

One exact map of the REST, SSE, WebSocket, and MCP surface.

RESTSSEWebSocketMCP

01 / sessions

Sessions

Find active and retained work, inspect one session, send input, interrupt a turn, or create work through an API client.

RESTGET/v1/sessionsList visible sessions, newest activity first.read-only

Authentication scope
read

Important parameters

Parameter	In	Required	Purpose
`machine`	query	No	Filter by machine ID.
`harness`	query	No	Filter by harness type.
`status`	query	No	Filter by session status.
`cwd`	query	No	Filter by working directory.
`before`	query	No	Return sessions older than this ISO timestamp.
`limit`	query	No	Return 1–1,000 sessions.

Request

curl 'https://rivetplane.com/v1/sessions' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

[
  {
    "id": "runner-01/opencode/ses_01",
    "machine_id": "runner-01",
    "harness_type": "opencode",
    "cwd": "/workspace/app",
    "title": "Repair deployment workflow",
    "model": {
      "provider_id": "openai",
      "model_id": "gpt-5.4"
    },
    "agent": "build",
    "read_only": false,
    "status": "waiting_approval",
    "created_at": "2026-08-26T09:58:00Z",
    "last_activity_at": "2026-08-26T10:15:00Z",
    "pending": {
      "type": "approval",
      "id": "per_01",
      "session_id": "runner-01/opencode/ses_01",
      "tool_name": "shell",
      "tool_input_summary": "bun run migrate",
      "requested_at": "2026-08-26T10:15:00Z"
    }
  }
]

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

RESTGET/v1/sessions/{session_id}Get current metadata and pending state for one session.read-only

Authentication scope
read

Important parameters

Parameter	In	Required	Purpose
`session_id`	path	Yes	A percent-encoded namespaced session ID.

Request

curl 'https://rivetplane.com/v1/sessions/runner-01%2Fcodex%2Fses_01' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

{
  "id": "runner-01/codex/ses_01",
  "machine_id": "runner-01",
  "harness_type": "codex",
  "cwd": "/workspace/app",
  "title": "Repair deployment workflow",
  "model": {
    "provider_id": "openai",
    "model_id": "gpt-5.4"
  },
  "agent": "default",
  "read_only": false,
  "metadata": {
    "source": "app-server"
  },
  "status": "running",
  "created_at": "2026-08-26T09:58:00Z",
  "last_activity_at": "2026-08-26T10:15:00Z",
  "pending": null
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

404 The session does not exist.

RESTPOST/v1/machines/{machine_id}/harnesses/{harness}/sessionsAsk a capable runner to create a session with a reported directory and model.mutating

Authentication scope
write

Important parameters

Parameter	In	Required	Purpose
`machine_id`	path	Yes	The paired runner ID.
`harness`	path	Yes	The reported harness type.
`cwd`	body	Yes	A directory from the capability report.
`model`	body	Yes	A reported provider and model pair.

Limits and behavior

Session creation is available only through REST or MCP. The web UI has no Create session control.

A 202 response confirms queue acceptance, not session completion.

Request

curl -X POST 'https://rivetplane.com/v1/machines/runner-01/harnesses/codex/sessions' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "cwd": "/workspace/app",
  "title": "Investigate CI",
  "model": {
    "provider_id": "openai",
    "model_id": "gpt-5.4"
  }
}'

{
  "cwd": "/workspace/app",
  "title": "Investigate CI",
  "model": {
    "provider_id": "openai",
    "model_id": "gpt-5.4"
  }
}

Successful response

{
  "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
  "accepted": true
}

Common errors

400 The directory or model was not reported.

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

404 The target does not exist.

409 The runner is offline or the target state changed.

RESTPOST/v1/sessions/{session_id}/messagesSend a user message to a live session.mutating

Authentication scope
write

Important parameters

Parameter	In	Required	Purpose
`session_id`	path	Yes	A percent-encoded namespaced session ID.
`text`	body	Yes	A non-empty user message.

Limits and behavior

Read-only adapters reject this command. Check the runner capability report first.

Request

curl -X POST 'https://rivetplane.com/v1/sessions/runner-01%2Fcodex%2Fses_01/messages' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "text": "Continue with the migration plan."
}'

{
  "text": "Continue with the migration plan."
}

Successful response

{
  "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
  "accepted": true
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

404 The target does not exist.

409 The runner is offline or the target state changed.

RESTPOST/v1/sessions/{session_id}/interruptInterrupt the current agent turn.mutating

Authentication scope
write

Important parameters

Parameter	In	Required	Purpose
`session_id`	path	Yes	A percent-encoded namespaced session ID.

Limits and behavior

A capable harness can treat an interrupt as a no-op when the session is idle.

Read-only adapters reject this command.

Request

curl -X POST 'https://rivetplane.com/v1/sessions/runner-01%2Fcodex%2Fses_01/interrupt' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

{
  "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
  "accepted": true
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

404 The target does not exist.

409 The runner is offline or the target state changed.

02 / machines

Machines / runners

Inspect paired runners and the harness, directory, model, and control capabilities that each runner reports.

RESTGET/v1/machinesList paired runners, state, last-seen time, and active harness types.read-only

Authentication scope
read

Important parameters

No operation parameters.

Request

curl 'https://rivetplane.com/v1/machines' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

[
  {
    "id": "runner-01",
    "name": "Studio Mac",
    "owner_account_id": "account-01",
    "last_seen_at": "2026-08-26T10:15:00Z",
    "status": "online",
    "harnesses": [
      "codex",
      "opencode"
    ]
  }
]

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

RESTPOST/v1/machines/{machine_id}/retireHide a stale runner and its sessions from list views without deleting transcript history.mutating

Authentication scope
write

Important parameters

Parameter	In	Required	Purpose
`machine_id`	path	Yes	The runner to retire.

Request

curl -X POST 'https://rivetplane.com/v1/machines/runner-01/retire' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

{
  "retired": true
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

404 The target does not exist.

409 The runner is offline or the target state changed.

RESTGET/v1/harness-capabilitiesList reported control capabilities, directories, and model rosters.read-only

Authentication scope
read

Important parameters

Parameter	In	Required	Purpose
`machine`	query	No	Optional machine ID filter.

Limits and behavior

Adapter reports are authoritative. A discovery-only adapter can report transcripts but reject messages, interrupts, approvals, questions, or session creation.

Request

curl 'https://rivetplane.com/v1/harness-capabilities' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

[
  {
    "machine_id": "runner-01",
    "harness_type": "codex",
    "can_create_session": true,
    "can_send_message": true,
    "can_respond_to_approval": true,
    "directories": [
      "/workspace/app"
    ],
    "models": [
      {
        "provider_id": "openai",
        "model_id": "gpt-5.4",
        "name": "GPT-5.4"
      }
    ],
    "reported_at": "2026-08-26T10:15:00Z"
  }
]

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

RESTGET/v1/machines/{machine_id}/harnesses/{harness}/capabilitiesGet one runner and harness capability report.read-only

Authentication scope
read

Important parameters

Parameter	In	Required	Purpose
`machine_id`	path	Yes	The paired runner ID.
`harness`	path	Yes	The harness type.

Limits and behavior

Claude Code discovery is currently read-only when the adapter cannot use an official exact-ID control interface.

Request

curl 'https://rivetplane.com/v1/machines/runner-01/harnesses/codex/capabilities' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

{
  "machine_id": "runner-01",
  "harness_type": "claude-code",
  "can_create_session": false,
  "can_send_message": false,
  "can_interrupt": false,
  "can_respond_to_approval": false,
  "can_respond_to_question": false,
  "directories": [],
  "models": [],
  "reported_at": "2026-08-26T10:15:00Z"
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

404 No capability report exists for this harness.

03 / usage

AI usage / quota

Aggregate privacy-safe token, cost, context-window, and quota metadata without treating estimates as billing records.

RESTGET/v1/usageGet token, cost, context-window, and quota usage for a date range.read-only

Authentication scope
read

Important parameters

Parameter	In	Required	Purpose
`from`	query	No	Inclusive RFC 3339 start. Defaults to 00:00 UTC today.
`to`	query	No	Inclusive RFC 3339 end. Defaults to now.
`machine`	query	No	Filter by machine ID.
`harness`	query	No	Filter by harness type.
`session`	query	No	Filter by session ID.
`provider`	query	No	Filter by provider.
`model`	query	No	Filter by model.

Limits and behavior

Token fields are null when no matching source reported them.

estimated cost is not an authoritative bill. coverage=partial means some matching samples had unavailable cost.

Account-level quota can omit session_id.

Request

curl 'https://rivetplane.com/v1/usage' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

{
  "range": {
    "from": "2026-08-26T00:00:00Z",
    "to": "2026-08-26T23:59:59Z"
  },
  "totals": {
    "tokens": {
      "input": 1200,
      "output": 300,
      "reasoning": null,
      "cache_read": 450,
      "cache_write": null,
      "total": 1500
    },
    "cost": {
      "status": "estimated",
      "coverage": "partial",
      "priced_samples": 2,
      "unavailable_samples": 1,
      "amount": 0.08,
      "currency": "USD"
    }
  },
  "breakdowns": {
    "by_machine": [],
    "by_harness": [
      {
        "key": "codex",
        "tokens": {
          "input": 1200,
          "output": 300,
          "reasoning": null,
          "cache_read": 450,
          "cache_write": null,
          "total": 1500
        },
        "cost": {
          "status": "estimated",
          "coverage": "partial",
          "priced_samples": 2,
          "unavailable_samples": 1,
          "amount": 0.08,
          "currency": "USD"
        }
      }
    ],
    "by_session": [],
    "by_provider": [],
    "by_model": []
  },
  "context": [
    {
      "machine_id": "runner-01",
      "session_id": "runner-01/codex/ses_01",
      "harness": "codex",
      "provider": "openai",
      "model": "gpt-5",
      "timestamp": "2026-08-26T10:15:00Z",
      "window_size": 200000,
      "used_tokens": 1500
    }
  ],
  "quota": [
    {
      "machine_id": "runner-01",
      "harness": "codex",
      "provider": "openai",
      "timestamp": "2026-08-26T10:15:00Z",
      "windows": [
        {
          "name": "five_hour",
          "used_percent": 35,
          "resets_at": "2026-08-26T15:00:00Z"
        }
      ]
    }
  ],
  "samples_count": 3
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

400 from or to is invalid, or from is after to.

04 / pending

Pending approvals / questions

Read the exact active request before you send a decision or answer. The harness remains the permission authority.

RESTGET/v1/sessions/{session_id}/pendingGet the exact active approval or question, or null.read-only

Authentication scope
read

Important parameters

Parameter	In	Required	Purpose
`session_id`	path	Yes	A percent-encoded namespaced session ID.

Request

curl 'https://rivetplane.com/v1/sessions/runner-01%2Fcodex%2Fses_01/pending' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

{
  "pending": {
    "type": "approval",
    "id": "per_01",
    "session_id": "runner-01/codex/ses_01",
    "tool_name": "shell",
    "tool_input_summary": "bun run migrate",
    "requested_at": "2026-08-26T10:15:00Z"
  }
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

404 The session does not exist.

RESTPOST/v1/sessions/{session_id}/pending/respondRespond to the exact current approval or question.mutating

Authentication scope
write

Important parameters

Parameter	In	Required	Purpose
`session_id`	path	Yes	A percent-encoded namespaced session ID.
`pending_id`	body	Yes	The ID returned by the latest pending read.
`response`	body	Yes	approve, deny, or question text.
`scope`	body	No	once, always_this_tool, or always_session.

Limits and behavior

A stale pending_id returns 409. Rivetplane never approves whatever happens to be pending.

Read-only adapters reject this command.

Request

curl -X POST 'https://rivetplane.com/v1/sessions/runner-01%2Fcodex%2Fses_01/pending/respond' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "pending_id": "per_01",
  "response": "approve",
  "scope": "once"
}'

{
  "pending_id": "per_01",
  "response": "approve",
  "scope": "once"
}

Successful response

{
  "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
  "accepted": true
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

404 The target does not exist.

409 The runner is offline or the target state changed.

RESTGET/v1/pendingList pending approvals and questions that the connected adapters can answer.read-only

Authentication scope
read

Important parameters

Parameter	In	Required	Purpose
`include_non_actionable`	query	No	Set true to include read-only, expired, and offline items with a reason.

Limits and behavior

The server checks the current machine state, adapter capability report, and pending interaction expiry. The default response contains only actionable items; expired native response windows are returned as read-only when include_non_actionable=true.

Request

curl 'https://rivetplane.com/v1/pending' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

[
  {
    "pending": {
      "type": "approval",
      "id": "per_01",
      "session_id": "runner-01/codex/ses_01",
      "tool_name": "shell",
      "tool_input_summary": "bun run migrate",
      "requested_at": "2026-08-26T10:15:00Z"
    },
    "session_id": "runner-01/codex/ses_01",
    "machine_id": "runner-01",
    "harness_type": "codex",
    "cwd": "/workspace/app",
    "title": "Repair deployment workflow",
    "model": {
      "provider_id": "openai",
      "model_id": "gpt-5.4"
    },
    "agent": "default",
    "read_only": false,
    "actionable": true
  }
]

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

RESTPOST/v1/pending/{pending_id}/respondRespond by exact pending ID and wait for the runner result.mutating

Authentication scope
write

Important parameters

Parameter	In	Required	Purpose
`pending_id`	path	Yes	Exact ID from GET /v1/pending.
`response`	body	Yes	approve, deny, or question text.
`scope`	body	No	once, always_this_tool, or always_session.

Limits and behavior

The server re-fetches the exact pending ID before it sends the response.

HTTP 200 means the runner reported success. A runner rejection returns 409.

Request

curl -X POST 'https://rivetplane.com/v1/pending/{pending_id}/respond' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "response": "approve",
  "scope": "once"
}'

{
  "response": "approve",
  "scope": "once"
}

Successful response

{
  "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
  "completed": true
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

404 The target does not exist.

409 The runner is offline or the target state changed.

504 The runner did not report a result before the timeout.

05 / transcripts

Transcripts / event streams

Page through retained events or follow live session and fleet activity with SSE or WebSocket.

RESTGET/v1/sessions/{session_id}/transcriptGet a retained transcript page in sequence order.read-only

Authentication scope
read

Important parameters

Parameter	In	Required	Purpose
`session_id`	path	Yes	A percent-encoded namespaced session ID.
`cursor`	query	No	Continue from a prior page.
`since`	query	No	Return events at or after an ISO timestamp.
`limit`	query	No	Return 1–1,000 events.

Request

curl 'https://rivetplane.com/v1/sessions/runner-01%2Fcodex%2Fses_01/transcript' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

{
  "events": [
    {
      "id": "evt_01",
      "session_id": "runner-01/codex/ses_01",
      "seq": 42,
      "ts": "2026-08-26T10:15:00Z",
      "type": "agent_message",
      "payload": {
        "text": "The tests pass."
      }
    }
  ],
  "next_cursor": null
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

400 The cursor or limit is invalid.

404 The session does not exist.

SSEGET/v1/sessions/{session_id}/transcript/streamFollow new transcript events for one session.read-only

Authentication scope
read

Important parameters

Parameter	In	Required	Purpose
`session_id`	path	Yes	A percent-encoded namespaced session ID.
`Authorization`	header	Yes	Bearer API token.

Limits and behavior

The stream sends text/event-stream data records and closes when the client disconnects.

Request

curl 'https://rivetplane.com/v1/sessions/runner-01%2Fcodex%2Fses_01/transcript/stream' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

data: {"id":"evt_43","seq":43,"type":"tool_call","payload":{...}}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

404 The session does not exist.

WebSocketWS/v1/events/streamFollow machine, session, command, pending, and transcript activity across the account.read-only

Authentication scope
read

Important parameters

Parameter	In	Required	Purpose
`Authorization`	header	No	Bearer API token for non-browser clients.
`Sec-WebSocket-Protocol`	header	No	Browser alternative: bearer.<base64url-token>.

Request

curl 'https://rivetplane.com/v1/events/stream' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

{
  "type": "transcript_event",
  "ts": "2026-08-26T10:15:00Z",
  "machine_id": "runner-01",
  "session_id": "runner-01/codex/ses_01",
  "data": {
    "type": "agent_message"
  }
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

WebSocketWS/v1/relayConnect a paired local runner to publish state and receive commands.mutating

Authentication scope
machine read/write

Important parameters

Parameter	In	Required	Purpose
`Authorization`	header	Yes	A token scoped to one machine.

Limits and behavior

This runner protocol is not an API-consumer event feed. The connection is always initiated from the local machine.

Request

curl 'https://rivetplane.com/v1/relay' \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Successful response

{
  "type": "command.send_message",
  "command_id": "cmd_01",
  "session_id": "runner-01/codex/ses_01",
  "text": "Continue."
}

Common errors

401 The bearer token is missing, expired, or invalid.

403 The token cannot access this account, machine, or session.

06 / authentication

Authentication / API tokens

Use account-scoped API tokens for consumers and one-runner machine tokens for the outbound relay.

API tokenAccount · read/write

Issue it in the signed-in dashboard. The secret appears once and is stored only as a hash.

Machine tokenOne runner · read/write

The local client gets it through browser authorization and PKCE pairing.

RESTPOST/v1/auth/tokenExchange a one-time PKCE pairing grant for a machine-scoped bearer token.mutating

Authentication scope
public grant exchange

Important parameters

Parameter	In	Required	Purpose
`code`	body	Yes	The one-time pairing code.
`code_verifier`	body	Yes	The PKCE verifier.
`redirect_uri`	body	Yes	The exact loopback callback URI from authorization.

Request

curl -X POST 'https://rivetplane.com/v1/auth/token' \
  -H "Content-Type: application/json" \
  --data '{
  "code": "one-time-code",
  "code_verifier": "pkce-verifier",
  "redirect_uri": "http://127.0.0.1:43123/callback"
}'

{
  "code": "one-time-code",
  "code_verifier": "pkce-verifier",
  "redirect_uri": "http://127.0.0.1:43123/callback"
}

Successful response

{
  "access_token": "shown-once",
  "token_type": "Bearer",
  "machine_id": "runner-01",
  "owner_account_id": "account-01"
}

Common errors

400 The grant, verifier, or redirect URI is invalid.

07 / mcp

MCP tools / resources

Use the same operation layer from an MCP client through Streamable HTTP.

Streamable HTTP configuration

Connect to one endpoint with the same bearer token used for REST.

{
  "mcpServers": {
    "rivetplane": {
      "url": "https://rivetplane.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

MCPtoollist_sessionsList visible sessions with optional filters. Results include harness-reported titles and model identity when available.read-only

Authentication scope
read

Parameters

Parameter	In	Required	Purpose
`filter`	argument	No	Optional machine, harness, status, and cwd fields.

JSON-RPC request

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

Result shape

[
  {
    "id": "runner-01/codex/ses_01",
    "title": "Repair deployment workflow",
    "model": {
      "provider_id": "openai",
      "model_id": "gpt-5.4"
    },
    "status": "running"
  }
]

MCPtoolget_sessionGet one session, including its harness-reported title, model, agent, and control mode when available.read-only

Authentication scope
read

Parameters

Parameter	In	Required	Purpose
`session_id`	argument	Yes	Namespaced session ID.

JSON-RPC request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_session",
    "arguments": {
      "session_id": "<session_id>"
    }
  }
}

Result shape

{
  "id": "runner-01/codex/ses_01",
  "title": "Repair deployment workflow",
  "model": {
    "provider_id": "openai",
    "model_id": "gpt-5.4"
  },
  "agent": "default",
  "read_only": false,
  "status": "running",
  "pending": null
}

MCPtoolsend_messageSend a user message to a live session.mutating

Authentication scope
write

Parameters

Parameter	In	Required	Purpose
`session_id`	argument	Yes	Namespaced session ID.
`text`	argument	Yes	Non-empty user message.

Limits and behavior

Read-only adapters reject this tool call.

JSON-RPC request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_message",
    "arguments": {
      "session_id": "<session_id>",
      "text": "<text>"
    }
  }
}

Result shape

{
  "accepted": true
}

MCPtoolinterrupt_sessionInterrupt the active agent turn.mutating

Authentication scope
write

Parameters

Parameter	In	Required	Purpose
`session_id`	argument	Yes	Namespaced session ID.

Limits and behavior

Read-only adapters reject this tool call.

JSON-RPC request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "interrupt_session",
    "arguments": {
      "session_id": "<session_id>"
    }
  }
}

Result shape

{
  "accepted": true
}

MCPtoolcreate_sessionCreate a session with a reported directory and model.mutating

Authentication scope
write

Parameters

Parameter	In	Required	Purpose
`machine_id`	argument	Yes	Paired runner ID.
`harness_type`	argument	Yes	Reported harness type.
`cwd`	argument	Yes	Reported directory.
`title`	argument	No	Optional session title.
`provider_id`	argument	Yes	Reported model provider.
`model_id`	argument	Yes	Reported model ID.

Limits and behavior

There is no Create session control in the web UI.

JSON-RPC request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_session",
    "arguments": {
      "machine_id": "<machine_id>",
      "harness_type": "<harness_type>",
      "cwd": "<cwd>",
      "provider_id": "<provider_id>",
      "model_id": "<model_id>"
    }
  }
}

Result shape

{
  "accepted": true
}

MCPtoollist_machinesList visible paired runners.read-only

Authentication scope
read

Parameters

No operation parameters.

JSON-RPC request

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

Result shape

[
  {
    "id": "runner-01",
    "status": "online"
  }
]

MCPtoollist_harness_capabilitiesList runner capability and model reports.read-only

Authentication scope
read

Parameters

Parameter	In	Required	Purpose
`machine_id`	argument	No	Optional runner filter.

JSON-RPC request

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

Result shape

[
  {
    "harness_type": "codex",
    "can_send_message": true
  }
]

MCPtoolget_usageGet token, cost, context-window, and quota usage.read-only

Authentication scope
read

Parameters

Parameter	In	Required	Purpose
`from`	argument	No	Inclusive RFC 3339 start.
`to`	argument	No	Inclusive RFC 3339 end.
`machine`	argument	No	Optional machine filter.
`harness`	argument	No	Optional harness filter.
`session`	argument	No	Optional session filter.
`provider`	argument	No	Optional provider filter.
`model`	argument	No	Optional model filter.

Limits and behavior

Estimated cost is not an authoritative bill. Missing fields remain unavailable.

JSON-RPC request

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

Result shape

{
  "range": {
    "from": "2026-08-26T00:00:00Z",
    "to": "2026-08-26T23:59:59Z"
  },
  "totals": {
    "tokens": {
      "input": 1200,
      "output": 300,
      "reasoning": null,
      "cache_read": 450,
      "cache_write": null,
      "total": 1500
    },
    "cost": {
      "status": "estimated",
      "coverage": "partial",
      "priced_samples": 2,
      "unavailable_samples": 1,
      "amount": 0.08,
      "currency": "USD"
    }
  },
  "breakdowns": {
    "by_machine": [],
    "by_harness": [
      {
        "key": "codex",
        "tokens": {
          "input": 1200,
          "output": 300,
          "reasoning": null,
          "cache_read": 450,
          "cache_write": null,
          "total": 1500
        },
        "cost": {
          "status": "estimated",
          "coverage": "partial",
          "priced_samples": 2,
          "unavailable_samples": 1,
          "amount": 0.08,
          "currency": "USD"
        }
      }
    ],
    "by_session": [],
    "by_provider": [],
    "by_model": []
  },
  "context": [
    {
      "machine_id": "runner-01",
      "session_id": "runner-01/codex/ses_01",
      "harness": "codex",
      "provider": "openai",
      "model": "gpt-5",
      "timestamp": "2026-08-26T10:15:00Z",
      "window_size": 200000,
      "used_tokens": 1500
    }
  ],
  "quota": [
    {
      "machine_id": "runner-01",
      "harness": "codex",
      "provider": "openai",
      "timestamp": "2026-08-26T10:15:00Z",
      "windows": [
        {
          "name": "five_hour",
          "used_percent": 35,
          "resets_at": "2026-08-26T15:00:00Z"
        }
      ]
    }
  ],
  "samples_count": 3
}

MCPtoolget_pendingGet the exact active approval or question.read-only

Authentication scope
read

Parameters

Parameter	In	Required	Purpose
`session_id`	argument	Yes	Namespaced session ID.

JSON-RPC request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_pending",
    "arguments": {
      "session_id": "<session_id>"
    }
  }
}

Result shape

{
  "type": "question",
  "id": "q_01",
  "prompt": "Which region?"
}

MCPtoolrespond_to_pendingRespond to the exact active approval or question.mutating

Authentication scope
write

Parameters

Parameter	In	Required	Purpose
`session_id`	argument	Yes	Namespaced session ID.
`pending_id`	argument	Yes	Exact current pending ID.
`response`	argument	Yes	Decision or answer.
`scope`	argument	No	Optional approval scope.

Limits and behavior

Read-only adapters reject this tool call.

JSON-RPC request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "respond_to_pending",
    "arguments": {
      "session_id": "<session_id>",
      "pending_id": "<pending_id>",
      "response": "<response>"
    }
  }
}

Result shape

{
  "accepted": true
}

MCPtoollist_pendingList pending items that the connected adapters can answer, with session identity fields for triage.read-only

Authentication scope
read

Parameters

Parameter	In	Required	Purpose
`include_non_actionable`	argument	No	Use true to include read-only and offline items with a reason.

JSON-RPC request

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

Result shape

[
  {
    "session_id": "runner-01/codex/ses_01",
    "title": "Repair deployment workflow",
    "model": {
      "provider_id": "openai",
      "model_id": "gpt-5.4"
    },
    "pending": {
      "type": "question",
      "id": "q_01",
      "prompt": "Which region?"
    },
    "actionable": true
  }
]

MCPtoolrespond_to_pending_by_idRespond by exact pending ID and wait for the runner result.mutating

Authentication scope
write

Parameters

Parameter	In	Required	Purpose
`pending_id`	argument	Yes	Exact ID from list_pending.
`response`	argument	Yes	Decision or answer.
`scope`	argument	No	Optional approval scope.

JSON-RPC request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "respond_to_pending_by_id",
    "arguments": {
      "pending_id": "<pending_id>",
      "response": "<response>"
    }
  }
}

Result shape

{
  "completed": true
}

MCPtoolget_transcriptGet a page of transcript events.read-only

Authentication scope
read

Parameters

Parameter	In	Required	Purpose
`session_id`	argument	Yes	Namespaced session ID.
`since`	argument	No	Optional ISO timestamp.
`limit`	argument	No	Optional page size, 1–1,000.
`cursor`	argument	No	Optional page cursor.

JSON-RPC request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_transcript",
    "arguments": {
      "session_id": "<session_id>"
    }
  }
}

Result shape

{
  "events": [
    {
      "seq": 42,
      "type": "agent_message"
    }
  ],
  "next_cursor": null
}

MCPresourcesession://{id}/transcriptLoad the complete retained transcript as context without paging tool calls.read-only

Authentication scope
read

Parameters

Parameter	In	Required	Purpose
`id`	argument	Yes	Percent-encoded namespaced session ID.

JSON-RPC request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "session://runner-01%2Fcodex%2Fses_01/transcript"
  }
}

Result shape

{
  "contents": [
    {
      "uri": "session://runner-01%2Fcodex%2Fses_01/transcript",
      "mimeType": "application/json",
      "text": "[{...}]"
    }
  ]
}