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

# SDKs

CloudRaker ships typed SDKs for TypeScript and Python: [`@cloudraker/api` on npm](https://www.npmjs.com/package/@cloudraker/api) and [`cloudraker` on PyPI](https://pypi.org/project/cloudraker/). Both wrap the same API, set the `Authorization` header from a `token` you provide, and default to the Production base URL. Method names map to the [API reference](/api/overview).

The SDKs target `https://api.cloudraker.com` out of the box — no base-URL configuration needed for production. To call [staging or development](/developers/environments), pass that environment's base URL instead.

As of **0.3.0** both SDKs cover the whole `/v1` surface — the six [capability verbs](/capabilities/extract), [batch extraction](/capabilities/extract), the [run](/developers/runs) lifecycle including `GET /v1/runs`, [files](/developers/files), templates, actions and [webhooks](/developers/webhooks) — alongside the rest of the API.

The six verbs are **top-level methods** on the client, not a namespace: `extract`, `extractBatch`, `parse`, `redact`, `fill`, `sign`, `pipeline` (snake\_case in Python: `extract_batch`).

## TypeScript — `@cloudraker/api`

Native `fetch`, ships precompiled CJS + ESM — no build step.

### Install

```bash
npm install @cloudraker/api
```

### Use

```ts
import { CloudRakerClient, CloudRakerEnvironment } from "@cloudraker/api";

const client = new CloudRakerClient({
  environment: CloudRakerEnvironment.Production, // the default; pass a base URL string for other environments
  token: process.env.CLOUDRAKER_API_KEY!,        // string, or a () => string supplier
});

// health check (no auth required)
await client.health();

// current identity
const me = await client.me.getMe();

// list spaces
const spaces = await client.spaces.listSpaces();
```

### Extract, end to end

```ts
import { CloudRakerClient } from "@cloudraker/api";

const client = new CloudRakerClient({ token: process.env.CLOUDRAKER_API_KEY! });

const run = await client.extract({
  file: { url: "https://www.irs.gov/pub/irs-pdf/fw9.pdf", name: "w9.pdf" },
  schema: {
    type: "object",
    properties: {
      business_name: { type: ["string", "null"] },
      tax_classification: { type: ["string", "null"] },
    },
  },
});

if (run.status === "processed") {
  console.log(run.output?.value);      // the extracted object
  console.log(run.output?.citations);  // JSON path -> fileId + page + bbox
} else {
  // still running past the wait window — poll by id
  const latest = await client.runs.getRun({ id: run.id });
  console.log(latest.status);
}
```

The call holds open until the run finishes, up to `wait` seconds (default 60, max 120, `0` returns immediately) — see [runs](/developers/runs) for the polling and webhook paths.

Resource namespaces on the client: `actions`, `authorization`, `dataObjects`, `files`, `home`, `installedActions`, `me`, `ontology`, `organizationSettings`, `organizationTemplates`, `playbooks`, `process`, `runs`, `search`, `spaceFiles`, `spaceRuns`, `spaces`, `templates`, `webhooks` — plus the top-level `health()`, `extract()`, `extractBatch()`, `parse()`, `redact()`, `fill()`, `sign()` and `pipeline()`. The full per-endpoint method list lives in the SDK's `dist/reference.md`.

## Python — `cloudraker`

Sync and async clients, built on `httpx` + `pydantic`. Requires Python 3.9+.

### Install

```bash title="pip"
pip install cloudraker
```

```bash title="uv"
uv add cloudraker
```

### Use (sync)

```python
import os
from cloudraker.client import CloudRaker
from cloudraker.environment import CloudRakerEnvironment

client = CloudRaker(
    environment=CloudRakerEnvironment.PRODUCTION,  # the default; use base_url for other environments
    token=os.environ["CLOUDRAKER_API_KEY"],        # str, or a Callable[[], str] supplier
)

client.health()
me = client.me.get_me()
spaces = client.spaces.list_spaces()
```

### Extract, end to end

```python
import os
from cloudraker.client import CloudRaker

client = CloudRaker(token=os.environ["CLOUDRAKER_API_KEY"])

run = client.extract(
    file={"url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "name": "w9.pdf"},
    schema={
        "type": "object",
        "properties": {
            "business_name": {"type": ["string", "null"]},
            "tax_classification": {"type": ["string", "null"]},
        },
    },
)

if run.status == "processed":
    print(run.output.value)      # the extracted object
    print(run.output.citations)  # JSON path -> fileId + page + bbox
else:
    # still running past the wait window — poll by id
    print(client.runs.get_run(id=run.id).status)
```

The call holds open until the run finishes, up to `wait` seconds (default 60, max 120, `0` returns immediately) — see [runs](/developers/runs) for the polling and webhook paths.

### Async

```python
from cloudraker.client import AsyncCloudRaker  # same signature, awaitable methods

client = AsyncCloudRaker(
    environment=CloudRakerEnvironment.PRODUCTION,
    token=os.environ["RAKERONE_API_KEY"],
)
me = await client.me.get_me()
```

The constructor also accepts `base_url`, `headers`, `timeout` (default 60s), `max_retries` (default 2), `follow_redirects` (default `True`), and `httpx_client`. Resource namespaces mirror the TypeScript client (snake\_case): `actions`, `authorization`, `data_objects`, `files`, `home`, `installed_actions`, `me`, `ontology`, `organization_settings`, `organization_templates`, `playbooks`, `process`, `runs`, `search`, `space_files`, `space_runs`, `spaces`, `templates`, `webhooks` — plus the top-level `health()`, `extract()`, `extract_batch()`, `parse()`, `redact()`, `fill()`, `sign()` and `pipeline()`. The full method list is in the SDK's `src/cloudraker/reference.md`.

## Authentication

The `token` you pass is a [organization API key](/developers/authentication) or a session JWT — both go in the `Authorization: Bearer` header, which the SDK sets for you. Passing a `() => string` supplier lets you rotate the token without rebuilding the client.

## Where to go next

#### [Authentication](/developers/authentication)

Where the token comes from and how scoping works.

#### [MCP server](/developers/mcp)

Drive the same API from Claude and other MCP clients.