---
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/runs, 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" \
  -H "Idempotency-Key: 3b8e5f1a-0c4d-4f5e-8a9b-1c2d3e4f5a6b" \
  -d '{"message":"Compare retrieval augmentation and fine-tuning, with sources.","model":"auto"}'
```

The default response is JSON:

```json
{
	"chat_id": "65a000000000000000000001",
	"run_id": "6f1d3c9e-5b2a-4c1e-9a77-2f0d8e4b1c55",
	"text": "The research answer, including source links…",
	"model": "provider/model-id",
	"usage": { "inputTokens": 1200, "outputTokens": 400, "totalTokens": 1600 },
	"metrics": {
		"input_tokens": 1200,
		"output_tokens": 400,
		"total_tokens": 1600,
		"tool_calls": 3,
		"duration_ms": 18400,
		"estimated_cost_usd": 0.0061
	},
	"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, and `metrics` is abbreviated; see [Usage and metrics](/developers/docs/agent-api/usage) for every field. `message.parts` also contains any tool calls and results. Model and usage metadata describe the actual execution, including automatic continuations. The `X-Chat-Id` and `X-Run-Id` headers carry the same ids.

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 — see [Streaming](/developers/docs/agent-api/streaming).                                                                                             |
| `background`      | boolean          | Default `false`. Return `202` with the run at once and read it later — see [Runs](/developers/docs/agent-api/runs). Cannot be combined with `stream: true`.                                          |
| `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.                                                                                                                                  |
| `max_steps`       | integer          | 1–10. Lowers the tool-step budget for this turn; it never raises the plan's budget (5, or 10 with deep research).                                                                                    |
| `tools`           | object           | Narrow the agent's tools for this turn — see [Tools and controls](/developers/docs/agent-api/tools#per-request-controls).                                                                            |
| `response_format` | object           | `{ "type": "json_schema", "json_schema": { "name", "schema", "description"? } }` to also get a matching JSON `output` — see [Structured output](/developers/docs/agent-api/tools#structured-output). |
| `metadata`        | object           | Up to 16 string tags (keys up to 64 characters, values up to 512), stored on the run and its usage row.                                                                                              |
| `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`, `ephemerides`, `solar_views`.                                   |

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 unless you turn them off with `tools.custom_instructions: false`.

## Headers

| Header            | Meaning                                                                                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | Optional, recommended. A retry with the same key returns the same run instead of starting another — see [Runs](/developers/docs/agent-api/runs#retry-safely-with-idempotency-key). |

## Dropped connections and retries

A dropped connection stops your view of the turn, not the turn: the run keeps going and is saved on the chat. To get the answer:

- If you sent an `Idempotency-Key`, send the same request again with the same key. You get the same run's result.
- Otherwise, with the `run_id` from `X-Run-Id`, read `GET /api/v1/runs/{run_id}` or resume its stream.
- Otherwise, read `GET /api/v1/chat/{chat_id}`: `active_run` shows a turn that is still running.

Send one message at a time per conversation: a second message while a turn is running returns `409 run_in_progress`. Long turns are best started with `background: true`. A POST without `chat_id` always creates a new conversation.

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