Research Companion conversations

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

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

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

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.