# Conversations endpoints

Past Research Companion conversations: read them with their messages and attached files, rename or delete them. Nothing can be sent through the API.

Paths are relative to https://kleiobase.com/api/v1. Request and response schemas are in the OpenAPI document at https://kleiobase.com/api/v1/openapi.json.

## List conversations

`GET /workspaces/{workspace_id}/conversations`

Newest first by updated_at, as the app lists them. A conversation that gets a new message or a new title moves to the front, so it can appear again on a later page.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `limit` (query, optional): Page size. Default 25, max 100.
- `cursor` (query, optional): The next_cursor of the previous page. Opaque.

Responses:

- `200`: A page of conversations.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `404`: The workspace does not exist or is not visible to this key's owner.
- `422`: Invalid limit or cursor.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Get a conversation with its messages

`GET /workspaces/{workspace_id}/conversations/{conversation_id}`

One page of messages, oldest first (limit and cursor page the messages). Messages are as the user saw them: what they sent and the companion's replies, the people and records each reply cites, and the files and knowledge base items each message carried. The companion's internal working (its reasoning, tool calls, summaries) is not included.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `conversation_id` (path, required): The Research Companion conversation id.
- `limit` (query, optional): Page size. Default 25, max 100.
- `cursor` (query, optional): The next_cursor of the previous page. Opaque.

Responses:

- `200`: The conversation and a page of messages.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `404`: The workspace does not exist or is not visible to this key's owner. Also: the conversation is not in this workspace.
- `422`: Invalid limit or cursor.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Rename a conversation

`PATCH /workspaces/{workspace_id}/conversations/{conversation_id}`

Only the title can be changed. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `conversation_id` (path, required): The Research Companion conversation id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: The conversation.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: the conversation is not in this workspace.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Delete a conversation

`DELETE /workspaces/{workspace_id}/conversations/{conversation_id}`

Deletes the conversation, its messages and its attached files, as deleting it in the app does. It cannot be undone. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `conversation_id` (path, required): The Research Companion conversation id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Responses:

- `200`: Deleted.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: the conversation is not in this workspace.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Get a download URL for an attached file

`GET /workspaces/{workspace_id}/conversations/{conversation_id}/files/{file_id}`

A signed URL for the file as it was uploaded. It works for 5 minutes; ask again for a new one.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `conversation_id` (path, required): The Research Companion conversation id.
- `file_id` (path, required): The id of a file attached to a message (attachments[].file_id).

Responses:

- `200`: The signed URL.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `404`: The workspace does not exist or is not visible to this key's owner. Also: the conversation is not in this workspace, or the file is not attached to it.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

Canonical: https://kleiobase.com/developers/docs/reference/conversations