Threads API

Endpoints for listing, reading, forking, and deleting conversation threads. See API Conventions for authentication and error format.

GET /api/threads

List root threads, ordered by most recently updated.


GET /api/threads
Authorization: Bearer <token>

Response


{
  "threads": [
    {
      "id": "abc123",
      "title": "Getting started with Pandora",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:01:00.000Z",
      "activeThreadId": "fork-456",
      "threadIds": ["abc123", "fork-456"]
    }
  ],
  "total": 1,
  "page": 0,
  "perPage": 100,
  "hasMore": false,
  "activeStreamIds": ["abc123"]
}

Field	Type	Description
`threads`	`array`	Thread objects, ordered by `updatedAt` descending
`threads[].id`	`string`	Root thread ID
`threads[].title`	`string \| null`	Auto-generated title (set after first assistant response)
`threads[].activeThreadId`	`string`	ID of the most recently updated thread in the family (root or any branch)
`threads[].threadIds`	`string[]`	All thread IDs in the family (root + branches)
`total`	`number`	Total root thread count
`page`	`number`	Current page index
`perPage`	`number \| false`	Page size
`hasMore`	`boolean`	Whether more pages exist
`activeStreamIds`	`string[]`	Thread IDs currently streaming a response. Always `[]` in serverless mode.

Only root threads appear in the list. Branches are accessible through the threadIds array or by fetching them directly with GET /api/threads/:id.

GET /api/threads/:id

Get a single thread with its full message history and branching context.


GET /api/threads/:id
Authorization: Bearer <token>

Response


{
  "thread": {
    "id": "abc123",
    "title": "Getting started with Pandora",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:01:00.000Z"
  },
  "messages": [
    {
      "id": "msg-1",
      "role": "user",
      "parts": [{ "type": "text", "text": "Hello" }]
    },
    {
      "id": "msg-2",
      "role": "assistant",
      "parts": [{ "type": "text", "text": "Hi there!" }]
    }
  ],
  "forks": {
    "msg-1": [{ "id": "fork-456", "title": "Alternative question" }]
  },
  "forkInfo": null
}

Field	Type	Description
`thread`	`object`	Thread metadata
`messages`	`array`	Full message history. Each message has `id`, `role`, and `parts`.
`messages[].parts`	`Part[]`	Message content parts matching the UIMessage format. See Message Part Types.
`forks`	`Record<string, BranchRef[]>`	Child branches keyed by fork-point message ID. Each entry lists threads that branched at that message.
`forkInfo`	`ForkInfo \| null`	Present only when this thread is itself a branch.

ForkInfo

When a thread is a branch (created via fork), forkInfo describes its relationship to the parent:

Field	Type	Description
`sourceThreadId`	`string`	The parent thread this was forked from
`forkPointIndex`	`number`	Index in the parent’s message list where the fork occurred
`siblings`	`BranchRef[]`	Other branches forked from the same point in the parent

A BranchRef is { id: string, title?: string }.

Errors

Status	Error	Cause
`404`	`Thread not found`	No thread with this ID exists

POST /api/threads/:id/fork

Create a new branch from an existing thread at a specific message. All messages before the fork point are cloned into the new thread.


POST /api/threads/:id/fork
Content-Type: application/json
Authorization: Bearer <token>


{ "messageId": "msg-3" }

Field	Type	Required	Description
`messageId`	`string`	Yes	ID of the message to fork at. Messages before this point are included in the branch.

Response


{
  "thread": {
    "id": "fork-456",
    "createdAt": "2025-01-01T00:02:00.000Z",
    "updatedAt": "2025-01-01T00:02:00.000Z"
  },
  "clonedMessageCount": 4
}

After forking, send a POST /api/chat with the new thread’s ID to continue the conversation from the fork point.

Errors

Status	Error	Cause
`400`	`messageId is required`	`messageId` is missing or not a string
`404`	`Message not found in thread`	The message ID does not exist in this thread

DELETE /api/threads/:id

Permanently delete a thread and all its messages.


DELETE /api/threads/:id
Authorization: Bearer <token>

Response


{ "success": true }

Errors

Status	Error	Cause
`404`	`Thread not found`	No thread with this ID exists

SDK Types

These types are available from @pandorakit/sdk/api:


import type { Thread, ThreadListResponse, ThreadDetailResponse, ThreadForkResponse, ServerMessage, BranchRef, ForkInfo } from '@pandorakit/sdk/api'

See SDK Client for the typed client that wraps these endpoints.