REST quickstart

This walkthrough uses cURL. Create an API key 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.

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

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

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

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.

The same workflow in TypeScript

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 to edit documents instead of converting them.

Getting started

Guides

REST reference

1. Upload a document

2. Request a PDF

3. Wait for completion

4. Download the artifact

The same workflow in TypeScript

​1. Upload a document

​2. Request a PDF

​3. Wait for completion

​4. Download the artifact

​The same workflow in TypeScript

1. Upload a document

2. Request a PDF

3. Wait for completion

4. Download the artifact

The same workflow in TypeScript