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

> Learn the PI-Desktop RACP API request paths for conversations and tool calls. Find the correct endpoints for /v1/sessions/{sessionId} and /v1/sessions/{sessionId}/turns.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: api-reference
- Published: 2026-09-11

---

**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`](https://github.com/vastsa/PI-Desktop/blob/main/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.

```typescript
POST /v1/sessions

```

This endpoint is defined at line 598 in [`packages/shared/src/racp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/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.

```typescript
GET /v1/sessions/{sessionId}

```

This `GET` operation is mapped at lines 599-600 in [`packages/shared/src/racp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/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.

```typescript
POST /v1/sessions/{sessionId}/turns

```

According to [`packages/shared/src/racp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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.

```typescript
GET /v1/turns/{turnId}

```

This endpoint, defined at line 604 in [`racp.ts`](https://github.com/vastsa/PI-Desktop/blob/main/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.

```typescript
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`](https://github.com/vastsa/PI-Desktop/blob/main/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:

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

```

```typescript
// 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
  }),
});

```

```typescript
// 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`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/racp.ts). The runtime implementation in [`packages/agent-runtime/src/runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/agent-runtime/src/runtime.ts) consumes these paths to orchestrate turn creation, while [`packages/agent-runtime/src/provider-binding.ts`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/racp.ts). The runtime logic that consumes these paths resides in [`packages/agent-runtime/src/runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/agent-runtime/src/runtime.ts), with header injection handled by [`packages/agent-runtime/src/provider-binding.ts`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/racp.ts), immediately terminate the turn execution without deleting the turn record.