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

# SDK

> **Note**
>
> The package `@cloudraker/sdk` is not published yet.

The SDK has no runtime dependency. It runs in Node 20 or later, Bun, Deno, browsers and Cloudflare Workers.

## Find the API host

Each organization has its own API host. A `crk_` key contains the slug, so the SDK finds the host from the key.

```ts
import { baseUrlFromKey, parseKey } from '@cloudraker/sdk'

parseKey(process.env.CRK_API_KEY!)
// { env: 'test', slug: 'acme' }

baseUrlFromKey(process.env.CRK_API_KEY!)
// https://acme.cloudraker.run
```

A `crt_` token or a JWT does not contain the slug. Set the `slug` option:

```ts
baseUrlFromKey(token, { slug: 'acme' })
```

A live key and a test key use the same host.

A credential or a slug with a wrong format causes a `KeyError`. The message never contains the credential.

| `error.code`      | Cause                                                                                |
| ----------------- | ------------------------------------------------------------------------------------ |
| `invalid_api_key` | A `crk_` key with a bad format, or a credential that is not `crk_`, `crt_` or a JWT. |
| `invalid_token`   | A `crt_` token with a bad format.                                                    |
| `invalid_slug`    | The `slug` option is not a valid slug.                                               |
| `slug_required`   | A `crt_` token or a JWT with no `slug` option.                                       |
| `slug_mismatch`   | The `slug` option is not the slug of the `crk_` key.                                 |

## Timeouts

The default request timeout of the SDK client is 100 seconds. A call with a `wait` also has a timeout of at least `wait` plus 10 seconds.

The client sends one `Idempotency-Key` per `POST` call and uses the same key for each retry of the call. Read [Idempotency](/paperwork/v2/idempotency).

## Wait for a job

`jobs.wait()` waits for a job until the job ends. Each call uses `Prefer: wait=55` or less, so a 60-second proxy does not cut it. It uses the `Retry-After` value. Read [Sync and async](/paperwork/v2/sync-and-async).

## Read a stream

The stream reader parses the server-sent events of a job and resumes with `Last-Event-ID` after a cut connection. Read [Streaming](/paperwork/v2/streaming).

## Verify a webhook

`verifyWebhook({ rawBody, signature, endpointUrl, slug })` verifies the JWT in `x-cr-signature`. It uses RS256 and the JWKS of your organization, and keeps a cache of the keys by `kid`. It checks `iss`, `aud`, `exp` with a clock skew of 60 seconds, and `body_sha256`. It refuses the HMAC form `t=,v1=`. Read [Webhooks](/paperwork/v2/webhooks).

## Other environments

To use another API host, set the `baseUrl` option of the client. Do not call `baseUrlFromKey`.