> ## Documentation Index
> Fetch the complete documentation index at: https://revise.io/developer/docs/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 example converts Markdown to PDF with cURL. It costs \$0.005.

Create an [API key](/developer/docs/developer/docs/revise-api/authentication) and set `REVISE_API_KEY` in your shell. Your account needs a positive credit balance. Each response returns the ID for the next request. Replace the example IDs with your own.

## 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"}}'
```

The response is HTTP `202` with a queued conversion receipt. Save its `id`. A replayed request can return a completed receipt, so check the 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`. Wait at least one second between polls, and honor `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 --location \
  '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. The API endpoint requires the same account's bearer key and may redirect to a signed storage URL. `--location` follows that redirect; cURL drops Authorization when the destination origin changes. Do not use `--location-trusted`. See [files and artifacts](/developer/docs/developer/docs/revise-api/files).

## 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" },
);
await pdf.save("report.pdf", { signal: AbortSignal.timeout(60_000) });
```

The helper uploads, submits, and polls. `save()` downloads, verifies integrity, and writes the result. Use `bytes()` instead to send the output in a response or store it elsewhere. Results expire 24 hours after completion. To edit documents instead, see [prompts](/developer/docs/developer/docs/revise-api/prompts).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.