---
title: "Files and dictation"
description: "Attach documents to an agent turn, download the figures, plots and files the agent produces, and transcribe audio."
canonical_url: "https://scholarxiv.com/developers/docs/agent-api/files"
markdown_url: "https://scholarxiv.com/developers/docs/agent-api/files.md"
---

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

# Files and dictation
URL: /developers/docs/agent-api/files
LLM index: /llms.txt
Description: Attach documents to an agent turn, download the figures, plots and files the agent produces, and transcribe audio.
Related: agent-api, agent-api/quickstart, agent-api/conversations, health-api

# Files and dictation

These routes use the same `sxv_` key and cover the rest of the `/chat` composer. The [Health Chat API](/developers/docs/health-api) uses them with `surface` or `scope` set to `health`.

## Attach a file

Presign, `PUT` the bytes, then complete:

```bash
curl -X POST https://scholarxiv.com/api/v1/uploads/presign \
  -H "Authorization: Bearer sxv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"filename":"review.pdf","mime":"application/pdf","size":184320,"scope":"chat"}'
```

`PUT` the bytes to the returned `uploadUrl`, then call `POST /api/v1/uploads/complete` with `{ "id" }`. Pass the completed id in `attachment_ids` on the next agent call — up to five per turn, subject to per-chat plan limits.

## Files the agent makes

A turn can produce files: a figure from `generateResearchFigure`, plots and files from Python in the [code sandbox](/developers/docs/agent-api/tools#the-code-sandbox) (a `.py` script, a CSV, a notebook, a spreadsheet; see [which types are kept](/developers/docs/agent-api/tools#the-code-sandbox)), a manuscript PDF from `compileLatexProject`, and voice memos. Each is saved to the account like an upload, and every response lists them in `files`. That is `files` in the JSON response, and `result.files` on a [run](/developers/docs/agent-api/runs#read-a-run):

```json
{
	"text": "Here is the blueprint diagram of a black hole…",
	"files": [
		{
			"attachment_id": "6ae2211d69a960e89e53d919",
			"source": "generated_figure",
			"filename": "a-simple-scientific-blueprint-style-diagram-of-a-1.png",
			"mime": "image/jpeg",
			"tool_call_id": "call_1",
			"download": "/api/v1/uploads/6ae2211d69a960e89e53d919",
			"content": "/api/v1/uploads/6ae2211d69a960e89e53d919/content"
		}
	]
}
```

`source` is `generated_figure`, `sandbox_figure`, `sandbox_file`, `compiled_pdf` (a manuscript built with `compileLatexProject`), or `voice_memo`. To fetch one:

- `GET {content}` with your key redirects (302) to the file itself. Most HTTP clients follow the redirect, so this returns the bytes in one call.
- `GET {download}` returns `{ "attachment": {…}, "download_url": "…", "expires_in": 300 }` when you want the signed URL itself, for example to hand to a browser.

```bash
curl -L -o figure.png https://scholarxiv.com/api/v1/uploads/6ae2211d69a960e89e53d919/content \
  -H "Authorization: Bearer sxv_your_key_here"
```

Signed URLs last five minutes; ask again for a fresh one. The redirect to it carries no key, so it is safe to follow across origins. `content` does not count toward the hourly request limit; `download` counts like any other call.

The agent is told to describe a figure rather than embed it, but an answer can still contain `![…](attachment://<attachment_id>)`. That id is always one of the turn's `files`: replace the link with the file you fetched, or with your own URL for it. The website does the same.

`GET /api/v1/uploads?scope=figure` lists every figure on the account, including ones made on the website. `GET /api/v1/uploads` without a scope lists chat, health and figure files together.

## Dictate a question

```bash
curl -X POST https://scholarxiv.com/api/v1/transcribe \
  -H "Authorization: Bearer sxv_your_key_here" \
  -F "audio=@memo.m4a" \
  -F "provider=addis"
```

Send it as `multipart/form-data` with `audio` and `provider` (`addis` or `elevenlabs`). Put the returned `text` in `message`.

## Context on the message

Selected papers and highlighted text are `selected_papers` and `selected_texts` on the message. Science viewer context is the `context` object. The server runs the tools; a client does not implement them. Voice memos, figures, and Python outputs are summarised in `files` and `sandbox`, and are also inside `message.parts` and the stream's tool events.

`GET /api/v1/models?surface=research` lists the models the current plan can run.

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