---
title: "Quickstart"
description: "Create an sxv_ key, send a message to POST /api/v1/chat, and read the JSON answer back."
canonical_url: "https://scholarxiv.com/developers/docs/agent-api/quickstart"
markdown_url: "https://scholarxiv.com/developers/docs/agent-api/quickstart.md"
---

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

# Quickstart
URL: /developers/docs/agent-api/quickstart
LLM index: /llms.txt
Description: Create an sxv_ key, send a message to POST /api/v1/chat, and read the JSON answer back.
Related: agent-api, agent-api/streaming, agent-api/conversations, papers-api/authentication

# Quickstart

Create an `sxv_` key in the [developer dashboard](/developers/dashboard/apikeys). Keep it on your backend or in a user's secure credential storage. Do not embed a shared key in a public app.

## Ask a question

```bash
curl https://scholarxiv.com/api/v1/chat \
  -H "Authorization: Bearer sxv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"message":"Compare retrieval augmentation and fine-tuning, with sources.","model":"auto"}'
```

The default response is JSON:

```json
{
  "chat_id": "65a000000000000000000001",
  "text": "The research answer, including source links…",
  "model": "provider/model-id",
  "usage": { "inputTokens": 1200, "outputTokens": 400, "totalTokens": 1600 },
  "finish_reason": "stop",
  "message": {
    "id": "assistant-message-id",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "The research answer, including source links…" }],
    "metadata": { "chatID": "65a000000000000000000001" }
  }
}
```

The values above are illustrative. `message.parts` also contains any tool calls and results. Model and usage metadata describe the actual execution, including automatic continuations.

Save `chat_id`; send it with the next `message` to continue. You send only the new message. The service reloads stored history and tool evidence.

## Request fields

| Field | Type | Meaning |
|---|---|---|
| `message` | string, required | Nonblank user message, up to 64,000 characters. |
| `chat_id` | string | Owned, 24-character conversation ID. Omit to create a new chat. |
| `stream` | boolean | Default `false`. Set `true` for live SSE events. |
| `model` | string | Explicit entitled model or `auto` routing preset. Defaults to the account's preferred model, with the plan default as fallback. |
| `deep_research` | boolean | Default `false`. Larger research step budget; requires Plus or Pro. |
| `selected_papers` | string | User-selected paper titles, identifiers, abstracts, or serialized context. |
| `selected_texts` | string | Highlighted passages to reference. |
| `attachment_ids` | string[] | Up to five existing attachment IDs owned by the caller. Upload them first — see [Files and dictation](/developers/docs/agent-api/files). Per-chat plan limits also apply. |
| `reply_contexts` | object[] | Up to ten excerpts the user is replying to. Each item is `{ "text", "source_message_id"? }`. |
| `context` | object | Optional string fields: `proteins`, `genes`, `molecules`, `densities`, `components`, `patents`, `taxa`, `sky_objects`, `exoplanets`. |

Each context string accepts up to 128,000 characters; the engine bounds context to fit the chosen model. Unknown fields are rejected. Caller-supplied history, system prompts, user IDs, plan IDs, and tool definitions are not accepted. Account custom instructions apply as they do on the website.

## One request at a time

Send one request at a time per conversation. Execution is tied to the active request; there is no background run, resumable event log, or idempotency key. Do not automatically retry a POST after losing the connection: it may have already saved a turn or performed tools. Inspect history using the saved ID first. A fresh POST without `chat_id` always creates a new conversation.

For live output, set `stream: true` — see [Streaming](/developers/docs/agent-api/streaming).

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