Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt

Use this file to discover all available pages before exploring further.

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
skills/upload/start
mcp/server/restart
task/create
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 lookup, thread creation, folders, history, and subscription cleanup.

Turns

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

Providers

Provider listing, model listing, and API key management.

Skills

Skill upload, install, update, uninstall, policy, health, and catalog 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.