---
title: "Conversations"
description: "Read, list, create, rename, pin, archive, delete and share the conversations the agent stores for an API key, and see their running turns."
canonical_url: "https://scholarxiv.com/developers/docs/agent-api/conversations"
markdown_url: "https://scholarxiv.com/developers/docs/agent-api/conversations.md"
---

> For the complete documentation index, see [llms.txt](/llms.txt).

# Conversations
URL: /developers/docs/agent-api/conversations
LLM index: /llms.txt
Description: Read, list, create, rename, pin, archive, delete and share the conversations the agent stores for an API key, and see their running turns.
Related: agent-api, agent-api/quickstart, agent-api/runs, agent-api/files

# Conversations

Every turn is stored under the `chat_id` returned by `POST /api/v1/chat`. These routes read and manage that history.

## Read a conversation

```bash
curl https://scholarxiv.com/api/v1/chat/65a000000000000000000001 \
  -H "Authorization: Bearer sxv_your_key_here"
```

Returns `{ "chat_id": "…", "title": "…", "messages": [...], "active_run": null }`. Messages include persisted text, tool parts, and metadata. `active_run` is the turn running on the conversation right now (a [run object](/developers/docs/agent-api/runs#read-a-run)), or `null`. The same conversation can be opened in the website's chat workspace. Access to another user's chat returns 404. Health and figure conversations are excluded.

## Manage conversations

| Action                  | Request                                                                                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| List chats              | `GET /api/v1/chats?surface=research`. Optional `limit` (1–100, default 50), `archived=true`, and `cursor` (the previous page's `next_cursor`). |
| Create an empty chat    | `POST /api/v1/chats` with optional `title` and `surface`                                                                                       |
| Read chat details       | `GET /api/v1/chats/{chatid}`: title, surface, pinned, archived, shared, timestamps, and `active_run`                                           |
| Rename, pin, archive    | `PATCH /api/v1/chats/{chatid}` with `title` (1–100 characters), `pinned`, or `archived`. Archiving also unpins.                                |
| Delete                  | `DELETE /api/v1/chats/{chatid}`. A health conversation also deletes its stored messages.                                                       |
| Share, check, unshare   | `POST`, `GET`, `DELETE /api/v1/chats/{chatid}/share`                                                                                           |
| List the chat's runs    | `GET /api/v1/chats/{chatid}/runs`                                                                                                              |
| Cancel the running turn | `POST /api/v1/chats/{chatid}/cancel`, or `POST /api/v1/runs/{run_id}/cancel` for one run                                                       |

All of these use the same `sxv_` key as the agent call.

## Continuing a conversation

Send one message at a time per conversation; a message sent while a turn is running returns `409 run_in_progress`. A dropped connection stops your view of the turn only: the run keeps going and is saved on the chat. Retry with the same `Idempotency-Key`, or read the run or the conversation, before sending again — see [Runs](/developers/docs/agent-api/runs). A fresh POST without `chat_id` always creates a new conversation.

A health conversation is read and managed through the [Health Chat API](/developers/docs/health-api).

## Continue on the website

API conversations are ordinary ScholarXIV chats. Each one appears in the key owner's sidebar on the website, at `https://scholarxiv.com/chats/{chat_id}`, with the same messages, tool results, figures and files. A new conversation is titled from its first message, the same way the website titles its own.

It works both ways:

- Start in your app, then open the chat on the website and keep going. If a turn is still running, the website attaches to it and streams the rest.
- Start on the website, then pass that chat's id as `chat_id` from your app. The agent reloads the full history either way. The website's chat id is the last part of its URL, and `GET /api/v1/chats` lists them all.

Renames, pins, archives and deletes made through `/api/v1/chats` show on the website, and the other way round. One turn runs per conversation across both: sending from the website while your app's turn is still running is refused there the same way the API answers `409 run_in_progress`.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).
