> This page is for Paperwork API, version v2.
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.cloudraker.com/paperwork/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Quickstart

This page takes you from an API key to a parsed file. You need `curl` and the admin role in your organization.

#### Create an API key

Open [API keys](https://dash.cloudraker.com/api-keys) in Dash and select **Create key**. Select the **Test** environment and the `parse` scope. Dash shows the value of the new key. Copy it.

```bash
export CRK_SLUG="acme"                # the slug of your organization
export CRK_API_KEY="crk_test_acme_…"  # the value from Dash
```

> **Note**
>
> Test keys have their own rate limits, but their jobs use real paperwork credits.

#### Check the key

```bash
curl -s "https://$CRK_SLUG.cloudraker.run/v2/me" \
  -H "Authorization: Bearer $CRK_API_KEY"
```

```json
{
  "slug": "acme",
  "env": "test",
  "scopes": ["parse"],
  "key": { "id": "key_01JC9M…", "name": "quickstart", "hint": "a1B2c3" }
}
```

A `401` means that the key or the host is wrong. Read [Errors](/paperwork/v2/errors#invalid_api_key).

#### Parse a file

`Prefer: wait=30` holds the request for up to 30 seconds. The call below reads a public form from a URL.

```bash
curl -s -X POST "https://$CRK_SLUG.cloudraker.run/v2/parse" \
  -H "Authorization: Bearer $CRK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=30" \
  -d '{ "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "name": "w9.pdf" } }'
```

If the job finishes in time, the answer is `200` with the finished job:

```json
{
  "object": "job",
  "id": "job_01JC9M…",
  "capability": "parse",
  "status": "succeeded",
  "deadline": "asap",
  "created_at": "2026-11-07T14:02:11Z",
  "completed_at": "2026-11-07T14:02:13Z",
  "output": { "output": { "markdown": "…", "json": { "pages": [] } } },
  "error": null,
  "usage": { "credits": 12, "units": { "page_parsed": 6 } }
}
```

The result is in `output.output`. Read [Jobs](/paperwork/v2/jobs#read-the-output) for the two output forms.

#### Read a job that is still running

If the job needs more time, the answer is `202` with the same job, a `Location` header and `status: "running"`. The job continues. Wait for it with the id from the answer:

```bash
curl -s "https://$CRK_SLUG.cloudraker.run/v2/jobs/job_01JC9M…" \
  -H "Authorization: Bearer $CRK_API_KEY" \
  -H "Prefer: wait=30"
```

The answer is `200` with the job, also when the job still runs. Check `status`.

## Next steps

* Get the result in the background: [Webhooks](/paperwork/v2/webhooks).
* Follow the progress of a job: [Streaming](/paperwork/v2/streaming).
* Retry safely: [Idempotency](/paperwork/v2/idempotency).