---
title: "Agent API"
description: "The ScholarXIV research agent as an API: one endpoint, our harness, tools, streaming, 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, files, and saved conversations.
Related: agent-api/quickstart, agent-api/streaming, agent-api/conversations, agent-api/tools, 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`; history and tool evidence reload when you continue. |
| 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` |
| Read a conversation | `GET /api/v1/chat/{chatid}` |
| List, rename, pin, archive, delete, share | `GET`, `PATCH`, `DELETE`, and `POST /api/v1/chats/{chatid}/share` |
| Upload or download a file | `POST /api/v1/uploads/presign`, `POST /api/v1/uploads/complete`, `GET /api/v1/uploads/{id}` |
| 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). 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.
- [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.
- [Files and dictation](/developers/docs/agent-api/files) — attach documents and transcribe audio.
- [Tools and limits](/developers/docs/agent-api/tools) — what the agent runs and how entitlements apply.
- [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 internally and returns a completed answer. Existing signed-in website and mobile clients can keep using `/api/chat`; that session-authenticated route is an adapter to the same engine.

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