---
title: "Agent API"
description: "The ScholarXIV research agent as an API: one endpoint, our harness, tools, streaming, background runs, files, and saved conversations."
canonical_url: "https://scholarxiv.com/developers/docs/agent-api"
markdown_url: "https://scholarxiv.com/developers/docs/agent-api.md"
---

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

# Agent API
URL: /developers/docs/agent-api
LLM index: /llms.txt
Description: The ScholarXIV research agent as an API: one endpoint, our harness, tools, streaming, background runs, files, and saved conversations.
Related: agent-api/quickstart, agent-api/runs, agent-api/streaming, agent-api/conversations, agent-api/tools, agent-api/usage, router-api/completions, health-api

# Agent API

`POST /api/v1/chat` runs the same agent as the website and mobile chat: the same system prompt, research tools, model routing, continuation, context compaction, and conversation storage. That agent and its harness are the product — you get the whole thing, not a prompt and a model. Tools and models remain subject to the API key owner's current plan.

Use this API for a complete research assistant in a bot, app, or integration. If you only need a raw completion against a chosen model, use the [Router Chat Completions API](/developers/docs/router-api/completions) instead; it does not run the ScholarXIV research workflow, execute tools, or store conversations.

## What you get

| Part                        | What it means for you                                                                                                                                           |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System prompt               | You send a message, not a prompt. The agent already knows how to plan, search, cite and stop.                                                                   |
| Research tools              | Paper and web research, federated sources, full-text reading and code execution run server-side. Your client implements no tools.                               |
| Model routing               | `auto` picks per request from the models your plan reaches, or name an entitled model to pin it.                                                                |
| Continuation and compaction | Long tasks finish across turns, and long conversations stay inside the model's context window.                                                                  |
| Conversation storage        | Every turn is persisted under a `chat_id`, and the chat shows on the website, where you can continue it. History and tool evidence reload either way.           |
| Generated files             | Figures, sandbox plots, files written by Python, and voice memos are saved and listed per turn with download links.                                             |
| Durable runs                | Every turn is a run that survives a dropped connection. Run it in the background, resume its stream from any event, and retry safely with an `Idempotency-Key`. |
| Per-request controls        | Narrow the tools, lower the step budget, tag the run, or ask for a JSON object that matches your schema.                                                        |
| Usage                       | Tokens, tool calls, duration and estimated cost per run, and account totals by model, source and surface.                                                       |
| Files and dictation         | Attach documents per turn, or dictate a question and send the transcript.                                                                                       |

## The surfaces

| Action                                            | Request                                                                                                      |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Run the agent                                     | `POST /api/v1/chat` (JSON, `stream: true`, or `background: true`)                                            |
| Read a conversation and its running turn          | `GET /api/v1/chat/{chatid}`                                                                                  |
| Read, stream, or cancel a run                     | `GET /api/v1/runs/{run_id}`, `GET /api/v1/runs/{run_id}/stream`, `POST /api/v1/runs/{run_id}/cancel`         |
| List a conversation's runs                        | `GET /api/v1/chats/{chatid}/runs`                                                                            |
| List, create, rename, pin, archive, delete, share | `GET`, `POST /api/v1/chats`, `GET`, `PATCH`, `DELETE /api/v1/chats/{chatid}`, `/api/v1/chats/{chatid}/share` |
| Cancel whatever is running on a chat              | `POST /api/v1/chats/{chatid}/cancel`                                                                         |
| Agent usage                                       | `GET /api/v1/usage`                                                                                          |
| Upload or download a file                         | `POST /api/v1/uploads/presign`, `POST /api/v1/uploads/complete`, `GET /api/v1/uploads/{id}`, `/content`      |
| Dictate                                           | `POST /api/v1/transcribe`                                                                                    |
| List models                                       | `GET /api/v1/models?surface=research`                                                                        |

All routes use the same `sxv_` key and the same rate limits as the [Papers API](/developers/docs/papers-api/limits); reading, streaming and cancelling runs do not count against the hourly limit. The [Health Chat API](/developers/docs/health-api) uses these same harness routes with `surface` or `scope` set to `health`.

## Where to start

- [Quickstart](/developers/docs/agent-api/quickstart) — create a key, send a message, read the response.
- [Runs, background mode and retries](/developers/docs/agent-api/runs) — long turns, resumable streams, `Idempotency-Key`, and cancellation.
- [Streaming](/developers/docs/agent-api/streaming) — live tokens, tool events, and the AI SDK event stream.
- [Conversations](/developers/docs/agent-api/conversations) — read, list, rename, share and delete chats, and continue them on the website.
- [Files and dictation](/developers/docs/agent-api/files) — attach documents, download what the agent makes, and transcribe audio.
- [Tools and controls](/developers/docs/agent-api/tools) — what the agent runs, the code sandbox, per-request controls, structured output, and entitlements.
- [Usage and metrics](/developers/docs/agent-api/usage) — per-run metrics and account usage.
- [Errors](/developers/docs/agent-api/errors) — status codes, error shape and retry guidance.
- [FAQ](/developers/docs/agent-api/faq) — history, custom prompts, retries and plan questions.

Authentication is the same `Authorization: Bearer sxv_…` header documented in [Papers API Authentication](/developers/docs/papers-api/authentication).

The MCP `research_chat` tool invokes this same service, including background runs (read them with `get_agent_run`). The signed-in website uses the session route `/api/chat`, an adapter to the same engine and the same runs: a reopened chat reattaches to a turn that is still running. The ScholarXIV mobile app calls these same agent routes with its session token as the bearer credential; its calls are recorded with the source `mobile` and do not count against the hourly API limit. Signed-in turns on the website and in the app also follow the account's agent tool settings; turns made with an API key do not.

## 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).
