PI-Desktop Request Paths for Conversations and Tool Calls: RACP API Reference

PI-Desktop exposes a REST-style RACP (Remote API for Conversation-Processing) interface that uses /v1/sessions/{sessionId} for conversation operations and /v1/sessions/{sessionId}/turns for initiating tool calls.

PI-Desktop is an open-source desktop application that provides conversational AI capabilities through a structured HTTP API. Understanding the exact request path for a conversation and tool call is essential for developers integrating with or extending the platform's functionality. The RACP protocol defines specific endpoints for session management and turn-based interactions, all centralized in packages/shared/src/racp.ts.

Conversation Management Endpoints

The RACP protocol treats conversations as sessions with unique identifiers. All conversation-level operations target the /v1/sessions base path.

Create a New Conversation

To initialize a new conversation session, issue a POST request to the root sessions endpoint.

POST /v1/sessions

This endpoint is defined at line 598 in packages/shared/src/racp.ts. The response returns a sessionId required for subsequent turn operations.

Retrieve an Existing Conversation

To fetch metadata or history for a specific conversation, target the session resource directly using the unique identifier.

GET /v1/sessions/{sessionId}

This GET operation is mapped at lines 599-600 in packages/shared/src/racp.ts and returns the conversation state without executing new tool calls.

Tool Call and Turn Execution Paths

Tool calls in PI-Desktop are implemented as turns within a conversation session. The turn-based architecture separates the initiation of a tool call from the retrieval of its results.

Start a Turn (Tool Call)

The primary request path for a conversation and tool call is the turns endpoint, which accepts a POST body containing the model request and optional tool specifications in an OpenAI-compatible schema.

POST /v1/sessions/{sessionId}/turns

According to packages/shared/src/racp.ts at lines 602-603, this endpoint carries the tool-call payload including model, messages, and tool_calls parameters. The packages/agent-runtime/src/runtime.ts file orchestrates turn creation at this path, handling automatic compaction and provider binding through packages/agent-runtime/src/provider-binding.ts.

Retrieve Turn Results

After initiating a turn, poll or fetch the specific turn resource to retrieve tool call results or model responses.

GET /v1/turns/{turnId}

This endpoint, defined at line 604 in racp.ts, decouples the execution request from result retrieval, enabling asynchronous tool call processing.

Interrupt or Cancel a Turn

To stop an in-progress tool call or conversation turn, use the colon-action sub-resource pattern.

POST /v1/turns/{turnId}:stop
POST /v1/turns/{turnId}:interrupt
POST /v1/turns/{turnId}:cancel

These control endpoints are defined at lines 605-607 in packages/shared/src/racp.ts and allow immediate termination of long-running tool executions.

Practical Code Examples

The following implementations demonstrate the exact request paths for conversation and tool call interactions:

// Fetch a conversation's metadata
await fetch(`${baseUrl}/v1/sessions/${sessionId}`, {
  method: "GET",
  headers: { Authorization: `Bearer ${apiKey}` },
});

// Start a turn that contains a tool-call request
await fetch(`${baseUrl}/v1/sessions/${sessionId}/turns`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "What's the weather?" }],
    // Tool call specifications appear here in OpenAI-compatible format
  }),
});

// Retrieve the turn including tool-call results
await fetch(`${baseUrl}/v1/turns/${turnId}`, {
  method: "GET",
  headers: { Authorization: `Bearer ${apiKey}` },
});

Source Code Architecture

The request paths are hardcoded in the RACP endpoint table located in packages/shared/src/racp.ts. The runtime implementation in packages/agent-runtime/src/runtime.ts consumes these paths to orchestrate turn creation, while packages/agent-runtime/src/provider-binding.ts builds the provider model and injects required headers. The test suite in packages/agent-runtime/src/opencode-session-headers.test.ts validates that conversation ID headers are correctly transmitted on one-shot completions, ensuring the /v1/sessions/{sessionId}/turns path maintains proper session context.

Summary

• Conversation Retrieval: Use GET /v1/sessions/{sessionId} to access conversation metadata.
• Tool Call Initiation: Use POST /v1/sessions/{sessionId}/turns to execute tool calls within a conversation.
• Result Polling: Use GET /v1/turns/{turnId} to retrieve specific turn results asynchronously.
• Turn Control: Use POST /v1/turns/{turnId}:stop or :interrupt to cancel active operations.
• Source Location: All paths are defined in packages/shared/src/racp.ts at lines 598-607.

Frequently Asked Questions

What is the exact request path to initiate a tool call in PI-Desktop?

Tool calls are initiated via POST /v1/sessions/{sessionId}/turns. This endpoint accepts an OpenAI-compatible request body containing the model parameters and optional tool specifications, as implemented in packages/shared/src/racp.ts at lines 602-603.

How do I retrieve the results of a specific tool call turn?

Send a GET request to /v1/turns/{turnId}. This path returns the completed turn object including any tool call results or model responses, separate from the initial execution endpoint.

Where are the RACP endpoint definitions located in the source code?

All request paths are centralized in packages/shared/src/racp.ts. The runtime logic that consumes these paths resides in packages/agent-runtime/src/runtime.ts, with header injection handled by packages/agent-runtime/src/provider-binding.ts.

Can I interrupt an ongoing tool call turn?

Yes. Send a POST request to /v1/turns/{turnId}:stop, :interrupt, or :cancel. These custom actions, defined at lines 605-607 in racp.ts, immediately terminate the turn execution without deleting the turn record.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}