> ## Documentation Index
> Fetch the complete documentation index at: https://developer.revise.io/llms.txt
> Use this file to discover all available pages before exploring further.

# REST quickstart

> Upload a document, submit a conversion, and retrieve the PDF.

This walkthrough uses cURL. Create an [API key](/revise-api/authentication) and set `REVISE_API_KEY` in your shell. Each response supplies the ID needed by the next request; replace the example IDs with your returned values.

## 1. Upload a document

Send the Markdown directly from standard input. The multipart filename tells Revise which format to parse.

```bash theme={null}
curl --fail-with-body 'https://revise.io/api/v1/files' \
  -H "Authorization: Bearer $REVISE_API_KEY" \
  -H 'Idempotency-Key: report-42-upload' \
  -F 'file=@-;filename=report.md;type=text/markdown' <<'MARKDOWN'
# Quarterly report
Revenue increased this quarter.
MARKDOWN
```

Save the returned `id`, such as `file_…`. Uploads are ephemeral by default and can be claimed by one job. Use a new idempotency key for a different input document.

## 2. Request a PDF

```bash theme={null}
curl --fail-with-body 'https://revise.io/api/v1/convert' \
  -H "Authorization: Bearer $REVISE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: report-42-convert' \
  -d '{"input":{"file_id":"file_REPLACE_ME"},"output":{"format":"pdf"}}'
```

This returns a conversion receipt, normally with HTTP `202` and `status: "queued"`. Persist its `id`. A replay can already be complete, so always inspect the returned status.

## 3. Wait for completion

```bash theme={null}
curl --fail-with-body 'https://revise.io/api/v1/convert/conversion_REPLACE_ME' \
  -H "Authorization: Bearer $REVISE_API_KEY"
```

Repeat while status is `queued` or `running`, waiting at least one second between polls and honoring `Retry-After` when present. Stop on `succeeded`, `failed`, or `cancelled`. Inspect `error` on failure. On success, the downloadable metadata is in `output.artifact`.

## 4. Download the artifact

```bash theme={null}
curl --fail-with-body \
  'https://revise.io/api/v1/artifacts/art_REPLACE_ME/content' \
  -H "Authorization: Bearer $REVISE_API_KEY" \
  -o report.pdf
```

Verify the downloaded byte count and SHA-256 against `output.artifact.bytes` and `output.artifact.sha256` before using the file. Downloads require the same account's bearer key. See [files and artifacts](/revise-api/files).

## The same workflow in TypeScript

```ts theme={null}
import { ReviseClient, Source } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const pdf = await revise.convert(
  Source.fromText("# Quarterly report\nRevenue increased this quarter.", {
    filename: "report.md",
  }),
  "pdf",
  { idempotencyKey: "report-42" },
);
const bytes = await pdf.bytes({ signal: AbortSignal.timeout(60_000) });
```

The helper uploads, submits, and polls. `bytes()` downloads lazily and verifies integrity. You can send these bytes in a response or save them to your own storage. See [prompts](/revise-api/prompts) to edit documents instead of converting them.