Skip to main content
Pioneer clients talk to a gateway over JSON-RPC 2.0 on a WebSocket connection. The desktop app uses this protocol, and any other client can use the same contract without linking to gateway internals. The protocol reference documents the public surface from crates/protocol. If a method, event, or payload is not exported there, treat it as an implementation detail.

​
Transport

The default gateway listener is: 
ws://localhost:17878
The gateway accepts WebSocket text frames containing JSON-RPC requests. Server responses and notifications are also WebSocket text frames. A small number of upload paths use binary frames; those are documented on the relevant feature page.

​
Authentication

The WebSocket handshake must include a bearer token: 
Authorization: Bearer <token>
The token is a gateway superuser JWT. You can issue one from the CLI: 
pioneer issue-superuser-token
Tokens are validated during the WebSocket handshake. A missing or invalid bearer token rejects the connection with HTTP 401. The superuser JWT signing material is stored in the gateway keystore. Rotate it with pioneer secrets rotate-jwt-token superuser; existing superuser bearer tokens become invalid and must be reissued.

​
Request Envelope

Every request uses JSON-RPC 2.0. Request ids are strings with exactly 21 characters. 
{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "turn/start",
  "params": {
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001",
    "input": [
      {
        "type": "text",
        "text": "Hello",
        "textElements": []
      }
    ]
  }
}
Successful responses return the same id: 
{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "result": {
    "turn": {
      "id": "trn_000000000000000001",
      "status": "InProgress"
    }
  }
}
Errors use JSON-RPC error envelopes: 
{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "error": {
    "code": -32602,
    "message": "invalid params for `turn/start`: `thread_id` is required"
  }
}
Core JSON-RPC error codes are:
CodeMeaning
-32700Parse error
-32600Invalid request
-32601Method not found
-32602Invalid params
Feature-specific errors may include error.data with a machine-readable code and details.

​
Notifications

Notifications are server-to-client JSON-RPC messages without an id. They are how clients observe long-running turns, tool output, task events, MCP status, and skill catalog changes. 
{
  "jsonrpc": "2.0",
  "method": "item/agent_message/delta",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001",
    "item_id": "itm_000000000000000001",
    "delta": "Hello",
    "stream": "agent_message"
  }
}
Clients should treat request responses as acceptance/lookup results, not as the whole operation. For example, turn/start returns after the gateway accepts the turn; the assistant response arrives through turn/* and item/* notifications.

​
Naming Conventions

Method names use slash-separated groups: 
workspace/default
thread/start
turn/start
provider/models/list
settings/get
memory/search
skills/upload/start
mcp/server/restart
task/create
artifact/list/thread
Payload field casing is mostly inherited from Rust serde attributes. Many request/response structs use snake_case fields, while task and timeline models often use camelCase. Do not infer casing from method names; use the schema or examples for the exact payload.

​
Schemas

JSON Schemas are generated from crates/protocol and written to /schemas. The schema file names use snake_case type names, for example:
  • /schemas/turn_start_params.json
  • /schemas/thread_tree_response.json
  • /schemas/mcp_install_params.json
  • /schemas/task_create_params.json
When implementing a client, use this reference for behavior and the generated schemas for exact type validation.

​
Reference Sections

Workspace & Threads

Workspace listing, creation, selection, renaming, thread creation, folders, history, and subscription cleanup.

AGENTS.md

Thread-tree instruction file read, save, archive, resolve, and notification methods.

Turns

Turn submission, cancellation, item events, timeline composition, and streaming notifications.

Providers

Provider listing, model listing, and API key management.

Settings

Gateway-scoped general and memory settings read/update methods.

Skills

Skill upload, install, update, uninstall, policy, health, and catalog notifications.

Memory

Durable memory search, remember, forget, candidate review methods, and memory notifications.

MCP Servers

MCP install config, policy, restart, uninstall, details, runtime status, and catalog notifications.

Tasks

Durable task creation, scheduling, subagents, task trees, waiting, deliveries, and task events.

Artifacts

Workspace file upload, listing, preview reads, downloads, bindings, and artifact notifications.