Rivetplane API

Returns 200 as soon as the HTTP listener serves traffic. Deployment health checks use it.

Authentication: None. The endpoint is public.

Responses

Example request

curl "https://rivetplane.com/health"

Example response

{
  "ok": true
}

The machine-readable description of this API. The /docs page and llms.txt are rendered from the same definitions and the same capability catalog.

Authentication: None. The endpoint is public.

Responses

Example request

curl "https://rivetplane.com/openapi.json"

Example response

{
  "openapi": "3.1.0",
  "info": {
    "title": "Rivetplane API",
    "version": "0.1.0"
  },
  "paths": {
    "/v1/sessions": {
      "get": {
        "summary": "List visible sessions, newest activity first."
      }
    }
  }
}

A plain-text summary of authentication, endpoints, request bodies, responses, streams, and MCP tools for agent consumers.

Authentication: None. The endpoint is public.

Responses

Example request

curl "https://rivetplane.com/llms.txt"

Example response

# Rivetplane

## Authentication
Authorization: Bearer <API_TOKEN>
...

The rendered reference. Every operation on it comes from the same definitions as /openapi.json.

Authentication: None. The endpoint is public.

Responses

Example request

curl "https://rivetplane.com/docs"

Example response

<!doctype html> ... Rivetplane API ...

A one-page map of every REST, SSE, WebSocket, and MCP capability, with purpose, parameters, limits, and examples for each one.

Authentication: None. The endpoint is public.

Responses

Example request

curl "https://rivetplane.com/capabilities"

Example response

<!doctype html> ... Everything on the plane. ...

A small script that adds a copy button to every code block. The content security policy allows this file only.

Authentication: None. The endpoint is public.

Responses

Example request

curl "https://rivetplane.com/ui.js"

Example response

(() => { /* copy buttons */ })();

Lists every runner the token can see. An API token sees the account fleet; a machine token sees only itself. Retired runners are excluded.

Authentication: Bearer token in the Authorization header. Scope: read.

Responses

Example request

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

Example 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"
    ]
  }
]

Hides a duplicate or dead runner and its sessions from list views. Transcript history stays readable by direct session ID. Machine tokens cannot retire a runner.

Authentication: Bearer token in the Authorization header. Scope: write.

Path parameters

Responses

Example request

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

Example response

{
  "retired": true
}

Issues a secret device code and a short user code. The server stores only SHA-256 hashes. Requests are rate limited per connection address.

Authentication: None. The endpoint is public.

Request body (application/json)

Stable controller identity and display name.

{
  "device_name": "Desk controller",
  "device_id": "4f61c8c8-55c3-4a36-b8eb-11855267982e"
}

Responses

Example request

curl -X POST "https://rivetplane.com/v1/auth/device/code" \
  -H "Content-Type: application/json" \
  -d '{"device_name":"Desk controller","device_id":"4f61c8c8-55c3-4a36-b8eb-11855267982e"}'

Example response

{
  "device_code": "base64url-secret",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://rivetplane.com/device",
  "expires_in": 600,
  "interval": 5
}

Polls at the returned interval. Approval produces one account-scoped consumer token. The exchange is single-use and replay safe. Early polls increase the interval by five seconds.

Authentication: None. The endpoint is public.

Request body (application/json)

The secret device code.

{
  "device_code": "base64url-secret"
}

Responses

Example request

curl -X POST "https://rivetplane.com/v1/auth/device/token" \
  -H "Content-Type: application/json" \
  -d '{"device_code":"base64url-secret"}'

Example response

{
  "error": "authorization_pending",
  "interval": 5
}

Lists controller identities and status. Consumer tokens cannot use this token-management endpoint.

Authentication: Bearer token in the Authorization header. Scope: read.

Responses

Example request

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

Example response

[]

Revokes the device and every active token for it. Consumer tokens cannot revoke devices.

Authentication: Bearer token in the Authorization header. Scope: write.

Path parameters

Responses

Example request

curl -X POST "https://rivetplane.com/v1/consumer-devices/6c2fd71b-e082-4aca-b8ea-f52704ccd501/revoke" \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Example response

{
  "revoked": true
}

The last step of local-client pairing. The local client opens /authorize in a browser, receives a code on its loopback callback, and exchanges it here. Every exchange revokes the earlier tokens of that machine.

Authentication: One-time authorization code plus the PKCE code verifier.

Request body (application/json)

The code, the PKCE verifier, and the same loopback callback.

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

Responses

Example request

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

Example response

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

The local client opens this page in the browser. It shows what the runner may do and posts the approval. An anonymous visitor is redirected to /login with return_to preserved.

Authentication: Browser session cookies plus a CSRF form field.

Query parameters

Responses

Example request

curl "https://rivetplane.com/authorize?redirect_uri=http%3A%2F%2F127.0.0.1%3A45678%2Fcallback&state=b7f1c2&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&machine_name=Studio%20Mac"

Example response

<!doctype html> ... Authorize local client ...

Claims a stable machine identity for the device, stores a one-time authorization code, and redirects to the loopback callback with code and state.

Authentication: Browser session cookies plus a CSRF form field.

Request body (application/x-www-form-urlencoded)

The prompt form fields.

{
  "csrf": "cs_5f21c8",
  "redirect_uri": "http://127.0.0.1:45678/callback",
  "state": "b7f1c2",
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "machine_name": "Studio Mac"
}

Responses

Example request

curl -X POST "https://rivetplane.com/authorize" \
  -b "hcp_access=...; hcp_refresh=...; hcp_csrf=cs_5f21c8" \
  --data-urlencode "csrf=cs_5f21c8" \
  --data-urlencode "redirect_uri=http://127.0.0.1:45678/callback" \
  --data-urlencode "state=b7f1c2" \
  --data-urlencode "code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

Example response

HTTP/1.1 303 See Other
location: http://127.0.0.1:45678/callback?code=1kQ7yq3f...&state=b7f1c2

Shows a CSRF-protected code entry form. The raw user code stays out of the URL and access logs. An anonymous user is sent to sign in.

Authentication: Browser session cookies plus a CSRF form field.

Responses

Example request

curl "https://rivetplane.com/device"

Example response

<!doctype html> ... Pair a controller ...

Looks up the short code from a form body, then shows the controller name and exact minimum scopes.

Authentication: Browser session cookies plus a CSRF form field.

Request body (application/x-www-form-urlencoded)

CSRF token and short code.

{
  "csrf": "cs_5f21c8",
  "user_code": "ABCD-EFGH"
}

Responses

Example request

curl -X POST "https://rivetplane.com/device/review"   -b "hcp_access=...; hcp_refresh=...; hcp_csrf=cs_5f21c8"   --data-urlencode "csrf=cs_5f21c8"   --data-urlencode "user_code=ABCD-EFGH"

Example response

<!doctype html> ... Approve controller ...

Applies one CSRF-protected decision to a pending, unexpired user code.

Authentication: Browser session cookies plus a CSRF form field.

Request body (application/x-www-form-urlencoded)

CSRF token, user code, and decision.

{
  "csrf": "cs_5f21c8",
  "user_code": "ABCD-EFGH",
  "decision": "approved"
}

Responses

Example request

curl -X POST "https://rivetplane.com/device"   -b "hcp_access=...; hcp_refresh=...; hcp_csrf=cs_5f21c8"   --data-urlencode "csrf=cs_5f21c8"   --data-urlencode "user_code=ABCD-EFGH"   --data-urlencode "decision=approved"

Example response

<!doctype html> ... Controller approved ...

Reports what every connected harness can do. Read it before you create a session or send a command. Adapter reports are authoritative. A discovery-only adapter can report transcripts but reject messages, interrupts, approvals, questions, or session creation.

Authentication: Bearer token in the Authorization header. Scope: read.

Query parameters

Responses

Example request

curl "https://rivetplane.com/v1/harness-capabilities?machine=runner-01" \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Example 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"
  }
]

Returns the allowed directories, the model roster, and the control operations that this harness accepts. Claude Code discovery is currently read-only when the adapter cannot use an official exact-ID control interface.

Authentication: Bearer token in the Authorization header. Scope: read.

Path parameters

Responses

Example request

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

Example 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"
}

Relays a session-creation command to the runner. The directory and the model must both appear in the capability report. The new session ID arrives through the session_upsert event and through GET /v1/sessions. 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.

Authentication: Bearer token in the Authorization header. Scope: write.

Path parameters

Request body (application/json)

The directory and model to use.

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

Responses

Example request

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

Example response

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

Aggregates append-only usage samples. Late and out-of-order samples are included by timestamp. event_id makes replay and reconnect ingestion idempotent. Cost status and coverage prevent estimates or incomplete data from appearing as authoritative billing. 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.

Authentication: Bearer token in the Authorization header. Scope: read and usage:read.

Query parameters

Responses

Example request

curl "https://rivetplane.com/v1/usage?from=2026-08-26T00%3A00%3A00Z&to=2026-08-26T23%3A59%3A59Z&harness=codex" \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Example 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
}

Lists sessions across the fleet. Filter for triage, for example status=waiting_approval to find every session that waits on a human.

Authentication: Bearer token in the Authorization header. Scope: read.

Query parameters

Responses

Example request

curl "https://rivetplane.com/v1/sessions?status=waiting_approval&limit=20" \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN"

Example 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"
    }
  }
]

Returns the harness type, directory, status, timestamps, and the active pending interaction.

Authentication: Bearer token in the Authorization header. Scope: read.

Path parameters

Responses

Example request

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

Example 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
}

Returns retained transcript events in ascending sequence order. Follow next_cursor until it is null, then switch to the SSE stream for live events.

Authentication: Bearer token in the Authorization header. Scope: read.

Path parameters

Query parameters

Responses

Example request

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

Example 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
}

Opens a text/event-stream connection. The server writes a ': connected' comment, then one data frame per new transcript event. Read the paged transcript first, then stream, so no event is missed. The stream sends text/event-stream data records and closes when the client disconnects.

Authentication: Bearer token in the Authorization header. Scope: read.

Path parameters

Headers

Responses

Example request

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

Example response

: connected

data: {"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."}}

Returns the interaction the session waits on, or null. Always read this immediately before you respond, and reuse the exact ID.

Authentication: Bearer token in the Authorization header. Scope: read.

Path parameters

Responses

Example request

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

Example 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"
  }
}

Relays a user message into a live session. The harness reply arrives as transcript events, not in this response. Read-only adapters reject this command. Check the runner capability report first.

Authentication: Bearer token in the Authorization header. Scope: write.

Path parameters

Request body (application/json)

The message to relay.

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

Responses

Example 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" \
  -d '{"text":"Continue with the migration plan."}'

Example response

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

Answers one approval or question. The pending_id must equal the ID currently returned by the pending read, so a new interaction cannot receive an old decision. A stale pending_id returns 409. Rivetplane never approves whatever happens to be pending. Read-only adapters reject this command.

Authentication: Bearer token in the Authorization header. Scope: write and pending:respond.

Path parameters

Request body (application/json)

The exact interaction ID and the decision.

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

Responses

Example 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" \
  -d '{"pending_id":"per_01","response":"approve","scope":"once"}'

Example response

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

Relays an ACP cancel to the harness. A capable harness can treat an interrupt as a no-op when the session is idle. Read-only adapters reject this command.

Authentication: Bearer token in the Authorization header. Scope: write.

Path parameters

Responses

Example request

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

Example response

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

Returns one fleet-wide inbox. By default it excludes offline runners and read-only adapters. Use include_non_actionable=true for diagnostics. 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.

Authentication: Bearer token in the Authorization header. Scope: read.

Query parameters

Responses

Example request

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

Example 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
  }
]

Finds the interaction by exact ID, checks adapter support and current state again, sends the response, and waits for the runner result. 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.

Authentication: Bearer token in the Authorization header. Scope: write and pending:respond.

Path parameters

Request body (application/json)

The decision or answer.

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

Responses

Example request

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

Example response

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

One JSON-RPC 2.0 endpoint for initialize, ping, tools/list, tools/call, resources/list, resources/templates/list, and resources/read. Notifications receive 202 with an empty body. Tools that act on a session need the write scope.

Authentication: Bearer token in the Authorization header. Scope: read.

Request body (application/json)

A JSON-RPC 2.0 request.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Responses

Example request

curl -X POST "https://rivetplane.com/mcp" \
  -H "Authorization: Bearer $RIVETPLANE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Example response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "list_sessions",
        "description": "List visible sessions with optional filters.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "filter": {
              "type": "object"
            }
          }
        }
      }
    ]
  }
}

Stripe calls this public endpoint. The server verifies the signature against the unparsed body before it stores customer, subscription, plan, or status changes.

Authentication: Stripe-Signature header verified against the raw body.

Headers

Request body (application/json)

The raw Stripe event.

{
  "id": "evt_1PxTest",
  "type": "customer.subscription.updated",
  "data": {
    "object": {
      "id": "sub_test"
    }
  }
}

Responses

Example request

curl -X POST "https://rivetplane.com/v1/billing/webhook" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_1PxTest","type":"customer.subscription.updated"}' \
  -H "Stripe-Signature: t=1756000000,v1=..."

Example response

{
  "received": true
}

Creates a Stripe Checkout session for the signed-in account and redirects to it. Self-hosted deployments without Stripe configuration return 503.

Authentication: Browser session cookies plus a CSRF form field.

Request body (application/x-www-form-urlencoded)

Form fields: csrf and plan.

{
  "csrf": "cs_5f21c8",
  "plan": "pro"
}

Responses

Example request

curl -X POST "https://rivetplane.com/billing/checkout" \
  -b "hcp_access=...; hcp_refresh=...; hcp_csrf=cs_5f21c8" \
  --data-urlencode "csrf=cs_5f21c8" \
  --data-urlencode "plan=pro"

Example response

HTTP/1.1 303 See Other
location: https://checkout.stripe.com/c/pay/cs_test_...

Creates a Stripe billing portal session for the signed-in account so the user can change the plan, the payment method, or read invoices.

Authentication: Browser session cookies plus a CSRF form field.

Request body (application/x-www-form-urlencoded)

Form field: csrf.

{
  "csrf": "cs_5f21c8"
}

Responses

Example request

curl -X POST "https://rivetplane.com/billing/portal" \
  -b "hcp_access=...; hcp_refresh=...; hcp_csrf=cs_5f21c8" \
  --data-urlencode "csrf=cs_5f21c8"

Example response

HTTP/1.1 303 See Other
location: https://billing.stripe.com/p/session/test_...

Returns the product page for anonymous visitors and the fleet dashboard for a signed-in browser session. The dashboard issues API tokens and shows runner state.

Authentication: Browser session cookies plus a CSRF form field.

Responses

Example request

curl "https://rivetplane.com/"

Example response

<!doctype html> ... Any harness. One plane. ...

Renders the sign-in form. return_to keeps a same-origin destination, for example an /authorize request from the local client.

Authentication: None. The endpoint is public.

Query parameters

Responses

Example request

curl "https://rivetplane.com/login"

Example response

<!doctype html> ... auth-page ...

Renders the account creation form. Supabase Auth owns the account record and the confirmation email.

Authentication: None. The endpoint is public.

Query parameters

Responses

Example request

curl "https://rivetplane.com/signup"

Example response

<!doctype html> ... auth-page ...

Form submission. On success the server sets the access, refresh, and CSRF cookies and redirects to return_to.

Authentication: None. The endpoint is public.

Request body (application/x-www-form-urlencoded)

Form fields: email, password, and return_to.

{
  "email": "dev@example.com",
  "password": "correct horse battery staple",
  "return_to": "/"
}

Responses

Example request

curl -X POST "https://rivetplane.com/auth/login" \
  --data-urlencode "email=dev@example.com" \
  --data-urlencode "password=correct horse battery staple" \
  --data-urlencode "return_to=/"

Example response

HTTP/1.1 303 See Other
location: /
set-cookie: hcp_access=...; HttpOnly; SameSite=Lax

Form submission. When Supabase requires email confirmation the server returns 202 with a confirmation page instead of a session.

Authentication: None. The endpoint is public.

Request body (application/x-www-form-urlencoded)

Form fields: email, password, and return_to.

{
  "email": "dev@example.com",
  "password": "correct horse battery staple",
  "return_to": "/"
}

Responses

Example request

curl -X POST "https://rivetplane.com/auth/signup" \
  --data-urlencode "email=dev@example.com" \
  --data-urlencode "password=correct horse battery staple"

Example response

HTTP/1.1 303 See Other
location: /
set-cookie: hcp_access=...; HttpOnly; SameSite=Lax

Revokes the Supabase session and clears the cookies. The csrf field must equal the hcp_csrf cookie.

Authentication: Browser session cookies plus a CSRF form field.

Request body (application/x-www-form-urlencoded)

Form field: csrf.

{
  "csrf": "cs_5f21c8"
}

Responses

Example request

curl -X POST "https://rivetplane.com/logout" \
  -b "hcp_access=...; hcp_refresh=...; hcp_csrf=cs_5f21c8" \
  --data-urlencode "csrf=cs_5f21c8"

Example response

HTTP/1.1 303 See Other
location: /login

Creates an account API token with read and write scope. The secret appears once in the response page. The server keeps only its hash.

Authentication: Browser session cookies plus a CSRF form field.

Request body (application/x-www-form-urlencoded)

Form field: csrf.

{
  "csrf": "cs_5f21c8"
}

Responses

Example request

curl -X POST "https://rivetplane.com/api-tokens" \
  -b "hcp_access=...; hcp_refresh=...; hcp_csrf=cs_5f21c8" \
  --data-urlencode "csrf=cs_5f21c8"

Example response

<!doctype html> ... <pre>Yb2m9Qs4Tt7Vx1Zc5Hg8Kj0Lp3Rn6Wd</pre> ...

The dashboard form equivalent of POST /v1/machines/{machine_id}/retire. It writes the same audit record and closes the relay connection.

Authentication: Browser session cookies plus a CSRF form field.

Path parameters

Request body (application/x-www-form-urlencoded)

Form field: csrf.

{
  "csrf": "cs_5f21c8"
}

Responses

Example request

curl -X POST "https://rivetplane.com/machines/runner-01/retire" \
  -b "hcp_access=...; hcp_refresh=...; hcp_csrf=cs_5f21c8" \
  --data-urlencode "csrf=cs_5f21c8"

Example response

HTTP/1.1 303 See Other
location: /

CSRF-protected dashboard action. It revokes the controller and all its active bearer tokens.

Authentication: Browser session cookies plus a CSRF form field.

Path parameters

Request body (application/x-www-form-urlencoded)

Form field: csrf.

{
  "csrf": "cs_5f21c8"
}

Responses

Example request

curl -X POST "https://rivetplane.com/consumer-devices/6c2fd71b-e082-4aca-b8ea-f52704ccd501/revoke"   -b "hcp_access=...; hcp_refresh=...; hcp_csrf=cs_5f21c8"   --data-urlencode "csrf=cs_5f21c8"

Example response

HTTP/1.1 303 See Other
location: /

One WebSocket that carries every event the token can see: runner presence, session upserts and removals, harness capability reports, transcript events, and command activity. This is the feed for 'show me everything that waits on me'.

Authentication: Authorization: Bearer <API_TOKEN>. Browsers that cannot set headers may send the subprotocol bearer.<base64url-token> instead. Principal: API token, or a machine token that receives only its own events

Handshake

GET /v1/events/stream HTTP/1.1
Host: rivetplane.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Authorization: Bearer $RIVETPLANE_TOKEN

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

Frames

session_upsert

{
  "type": "session_upsert",
  "ts": "2026-08-26T10:15:00Z",
  "machine_id": "runner-01",
  "session_id": "runner-01/codex/ses_01",
  "data": {
    "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
  }
}

transcript_event

{
  "type": "transcript_event",
  "ts": "2026-08-26T10:15:00Z",
  "machine_id": "runner-01",
  "session_id": "runner-01/codex/ses_01",
  "data": {
    "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."
    }
  }
}

usage_sample

{
  "type": "usage_sample",
  "ts": "2026-08-26T10:15:00Z",
  "machine_id": "runner-01",
  "session_id": "runner-01/codex/ses_01",
  "data": {
    "event_id": "usage-01",
    "harness": "codex",
    "source": "codex.app_server",
    "tokens": {
      "total": 1500
    },
    "cost": {
      "status": "estimated",
      "amount": 0.08,
      "currency": "USD"
    }
  }
}

machine_online

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

machine_offline

{
  "type": "machine_offline",
  "ts": "2026-08-26T10:15:00Z",
  "machine_id": "runner-01",
  "data": {}
}

session_removed

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

harness_capabilities

{
  "type": "harness_capabilities",
  "ts": "2026-08-26T10:15:00Z",
  "machine_id": "runner-01",
  "data": {
    "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"
  }
}

command_sent

{
  "type": "command_sent",
  "ts": "2026-08-26T10:15:00Z",
  "machine_id": "runner-01",
  "session_id": "runner-01/codex/ses_01",
  "data": {
    "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
    "command_type": "command.send_message",
    "actor": "api:5c1f"
  }
}

command_result

{
  "type": "command_result",
  "ts": "2026-08-26T10:15:00Z",
  "machine_id": "runner-01",
  "data": {
    "type": "command.result",
    "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
    "ok": true,
    "result": {
      "session_id": "runner-01/codex/ses_01"
    }
  }
}

Close codes

The outbound connection that a local runner keeps open. The runner publishes machine, capability, session, and transcript state; the server pushes commands back. The server never dials into a developer machine. Frames are applied in order, so a transcript event cannot overtake its session.

Authentication: Authorization: Bearer <MACHINE_TOKEN> from POST /v1/auth/token. Principal: Machine token only

Handshake

GET /v1/relay HTTP/1.1
Host: rivetplane.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Authorization: Bearer $MACHINE_TOKEN

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

Frames

machine.hello

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

machine.heartbeat

{
  "type": "machine.heartbeat",
  "machine_id": "runner-01",
  "sent_at": "2026-08-26T10:15:00Z"
}

harness.capabilities

{
  "type": "harness.capabilities",
  "capabilities": {
    "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"
  }
}

session.upsert

{
  "type": "session.upsert",
  "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,
    "metadata": {
      "source": "app-server"
    },
    "status": "running",
    "created_at": "2026-08-26T09:58:00Z",
    "last_activity_at": "2026-08-26T10:15:00Z",
    "pending": null
  }
}

transcript.append

{
  "type": "transcript.append",
  "event": {
    "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."
    }
  }
}

usage.sample

{
  "type": "usage.sample",
  "sample": {
    "event_id": "usage-01",
    "machine_id": "runner-01",
    "session_id": "runner-01/codex/ses_01",
    "timestamp": "2026-08-26T10:15:00Z",
    "harness": "codex",
    "source": "codex.app_server",
    "provider": "openai",
    "model": "gpt-5",
    "source_counter_mode": "cumulative",
    "tokens": {
      "input": 1200,
      "output": 300,
      "reasoning": null,
      "cache_read": 450,
      "cache_write": null,
      "total": 1500
    },
    "cost": {
      "status": "estimated",
      "amount": 0.08,
      "currency": "USD"
    }
  }
}

session.removed

{
  "type": "session.removed",
  "session_id": "runner-01/codex/ses_01",
  "removed_at": "2026-08-26T10:15:00Z"
}

command.result

{
  "type": "command.result",
  "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
  "ok": true,
  "result": {
    "session_id": "runner-01/codex/ses_01"
  }
}

relay.error

{
  "type": "relay.error",
  "error": "Session does not belong to this machine"
}

command.send_message

{
  "type": "command.send_message",
  "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
  "session_id": "runner-01/codex/ses_01",
  "text": "Continue with the migration plan."
}

command.respond_to_pending

{
  "type": "command.respond_to_pending",
  "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
  "session_id": "runner-01/codex/ses_01",
  "pending_id": "per_01",
  "response": "approve",
  "scope": "once"
}

command.interrupt_session

{
  "type": "command.interrupt_session",
  "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
  "session_id": "runner-01/codex/ses_01"
}

command.create_session

{
  "type": "command.create_session",
  "command_id": "9b1f7a1e-6c5b-4a11-8e6f-2d0c9a4f31bb",
  "machine_id": "runner-01",
  "harness_type": "codex",
  "cwd": "/workspace/app",
  "title": "Investigate CI",
  "model": {
    "provider_id": "openai",
    "model_id": "gpt-5.4"
  }
}

Close codes

Returns the protocol version and the advertised capabilities. Rivetplane serves tools and resources. The bearer token is required on this call, like on every other call.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {},
      "resources": {}
    },
    "serverInfo": {
      "name": "rivetplane",
      "title": "Rivetplane",
      "version": "0.1.0"
    }
  }
}

A notification has no id. The server answers with HTTP 202 and an empty body. Every notifications/* method behaves the same way.

Request

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

Response

HTTP/1.1 202 Accepted (empty body)

Returns an empty result.

Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "ping"
}

Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {}
}

Returns every tool with its JSON Schema. The list is stable for a server version.

Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/list"
}

Response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "tools": [
      {
        "name": "get_pending",
        "description": "Get the current approval or question.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "session_id": {
              "type": "string"
            }
          },
          "required": [
            "session_id"
          ]
        }
      },
      {
        "name": "…",
        "description": "The other tools follow the same shape."
      }
    ]
  }
}

Runs one tool. The result carries both a text block and structuredContent.result, so strict and lenient clients both work. A failed call returns an HTTP status with an Error body, not a JSON-RPC result.

Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_pending",
    "arguments": {
      "session_id": "runner-01/codex/ses_01"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"type\": \"approval\",\n  \"id\": \"per_01\",\n  \"session_id\": \"runner-01/codex/ses_01\",\n  \"tool_name\": \"shell\",\n  \"tool_input_summary\": \"bun run migrate\",\n  \"requested_at\": \"2026-08-26T10:15:00Z\"\n}"
      }
    ],
    "structuredContent": {
      "result": {
        "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"
      }
    },
    "isError": false
  }
}

Rivetplane exposes no fixed resources. It exposes one template, so the caller loads a transcript by session ID.

Request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/list"
}

Response

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "resources": [],
    "resourceTemplates": [
      {
        "uriTemplate": "session://{id}/transcript",
        "name": "Session transcript",
        "mimeType": "application/json"
      }
    ]
  }
}

Returns the transcript template only.

Request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "resources/templates/list"
}

Response

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "session://{id}/transcript",
        "name": "Session transcript",
        "mimeType": "application/json"
      }
    ]
  }
}

Loads the complete transcript as context instead of paging through tool calls. Percent-encode the session ID inside the URI.

Request

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

Response

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "contents": [
      {
        "uri": "session://runner-01%2Fcodex%2Fses_01/transcript",
        "mimeType": "application/json",
        "text": "[{\"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.\"}}]"
      }
    ]
  }
}

Error

Every failed request returns this shape.

{
  "error": "Session not found"
}

Health

{
  "ok": true
}

MachineStatus

Relay connection state of a paired runner.

Machine

One paired local runner.

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

SessionStatus

Reported by the runner. The server never infers a state.

SessionModel

Model identity reported by the harness.

ApprovalScope

How long the harness keeps an approval decision.

ApprovalResolution

Approval

A tool call that waits for a human decision.

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

Question

A free-text or multiple-choice question from the harness.

{
  "type": "question",
  "id": "q_01",
  "session_id": "runner-01/codex/ses_01",
  "prompt": "Which region should I deploy first?",
  "options": [
    "eu-central",
    "ap-southeast"
  ],
  "requested_at": "2026-08-26T10:15:00Z"
}

PendingInteraction

The one interaction a session currently waits on.

Session

One harness session on one machine.

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

PendingResponse

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

PendingListItem

TranscriptEventType

Payload discriminator of a transcript event.

TranscriptEvent

One append-only transcript record. The payload shape follows the type.

{
  "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."
  }
}

TranscriptPage

One page of transcript events in ascending sequence order.

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

HarnessModel

One selectable model in a harness roster.

HarnessCapabilities

What one harness on one machine can do right now.

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

UsageTokenCounts

Normalized incremental token contributions. Null means that no matching source reported the counter.

UsageCostSummary

Cost metadata, not an invoice. Any estimate makes status estimated. Partial coverage means some matching samples had no cost.

UsageAggregate

UsageBreakdown

UsageContext

UsageQuotaWindow

UsageQuota

UsageReport

Append-only usage aggregated for the requested range. Missing values stay null or unavailable.

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

CreateSessionRequest

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

SendMessageRequest

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

RespondToPendingRequest

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

RespondByPendingIdRequest

CommandCompleted

CommandAccepted

The control plane relayed a command to the runner. It does not mean the harness finished the work.

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

MachineRetired

{
  "retired": true
}

MachineTokenRequest

{
  "code": "1kQ7yq3fJ2Xo9m8vTn0pQ5rW6sD1aZ4c",
  "code_verifier": "b3T3wM9dLp1sV2xY7hR4nJ6kF8gC0uQ5",
  "redirect_uri": "http://127.0.0.1:45678/callback"
}

MachineTokenResponse

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

DeviceCodeRequest

DeviceCodeResponse

DeviceTokenRequest

ConsumerDevice

DeviceTokenResponse

DeviceTokenError

Revoked

StripeWebhookAck

{
  "received": true
}

JsonRpcRequest

MCP Streamable HTTP request.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

JsonRpcResponse

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "list_sessions"
      }
    ]
  }
}

Html

A server-rendered HTML page.