# Research Companion conversations

Read past Research Companion conversations with their messages and attached files, rename them or delete them.


The API gives access to the Research Companion conversations you have already had in a workspace: read them, rename them, delete them. Nothing can be sent through the API. There is no endpoint that sends a message or starts a conversation.

## List conversations

```bash
curl https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/conversations \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

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

## Read one

```bash
curl "https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/conversations/CONVERSATION_ID?limit=50" \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

You get the conversation and one page of `messages`, oldest first. `limit` and `cursor` page the messages. Each message has:

- `role`: `user` for what you sent, `assistant` for the companion's reply.
- `text`: the message as you saw it, in Markdown. In replies, people and records appear as links such as `[Person: Name](/knowledge-base/people/{id})`.
- `citations`: the people and records a reply cites, as `{ type, id }`.
- `attachments`: files you attached, each with a `file_id`.
- `attached_items`: knowledge base items you attached, such as a record or a person.

Messages are returned as you saw them. The companion's internal working (its reasoning, tool calls and summaries) is never included.

## Download an attached file

```bash
curl https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/conversations/CONVERSATION_ID/files/FILE_ID \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

This returns `{ "url", "expires_at" }`. The URL works for 5 minutes. Ask again for a new one.

## Rename or delete

- `PATCH .../conversations/{conversation_id}` with `{"title": "..."}` (1 to 200 characters) renames it.
- `DELETE .../conversations/{conversation_id}` deletes the conversation, its messages and its attached files, as in the app. **This cannot be undone.**

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