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

# Agent quickstart

This page is for a coding agent, such as Claude Code or Cursor, that writes the integration for a human. If you are the human, paste this URL into your agent.

## 1. Fetch the contract

```bash
curl -s https://docs.cloudraker.com/developers/agents.md
```

That one Markdown file is the full API contract. It contains the base URL, auth, all six verbs with minimal bodies, the file union, and the run lifecycle. It also contains the extraction schema dialect, the error envelope with every code, and the rate limit. Read it before you write code. It is short enough to hold in context. Do not guess field names.

Three machine-readable surfaces are available, in order of size:

| URL                                                | What it is                                                                                                                                        |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `https://docs.cloudraker.com/developers/agents.md` | The distilled contract. Start here.                                                                                                               |
| `https://docs.cloudraker.com/llms.txt`             | Index of every page. Append `.md` to a page URL to get its Markdown.                                                                              |
| `https://docs.cloudraker.com/openapi.json`         | The full gateway spec, with batch and run listing. It is large. It is re-exported when the surface changes. If the two disagree, use `agents.md`. |

## 2. Get a key

The human creates the key in the CloudRaker app under **Admin → API keys**. That page is admin-only, and the key is shown once. The human then exports it:

```bash
export CLOUDRAKER_API_KEY="sk_…"
```

Never write a key into source, a config file, or a docs example. Read it from the environment.

## 3. Run one call end to end

Extract with an inferred schema. You do not write a schema, and you do not stage a local file:

```bash
curl -sX POST https://api.cloudraker.com/v1/extract \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "name": "w9.pdf" },
    "hints": "This is a tax form; capture its identity",
    "citations": true,
    "metadata": { "job": "agent-quickstart" }
  }'
```

The call holds until the run finishes (60 s by default) and returns the finished run. `config.schema` is the inferred shape, and `output.value` is the data. `output.citations` is the page-and-region evidence per field. It is present because the request asked for it.

```json
{
  "object": "extract_run",
  "id": "exr_01KYD1J8QW2RN4T6VXZ0ABCDEF",
  "status": "processed",
  "config": {
    "schema": {
      "type": "object",
      "properties": {
        "form_type": { "type": ["string", "null"], "description": "Form identifier (e.g., W-9)" },
        "form_revision_date": { "type": ["string", "null"], "description": "Form revision date (e.g., March 2024)" },
        "catalog_number": { "type": ["string", "null"], "description": "IRS catalog number for the form (e.g., 10231X)" }
      }
    }
  },
  "output": {
    "value": { "form_type": "W-9", "form_revision_date": "March 2024", "catalog_number": "10231X" },
    "citations": {
      "form_type": [
        {
          "fileId": "a0375090-2f78-4fc5-a016-cb29dc43f8ea",
          "page": 0,
          "bbox": { "x": 0.091, "y": 0.037, "width": 0.065, "height": 0.036 },
          "text": "Form W-9",
          "confidence": 5
        }
      ]
    }
  }
}
```

If the run passes the wait cap, you get `202` with the same body minus `output`. Poll `statusUrl`. Do not treat this as an error.

## 4. Then write the real integration

Do not ship the call above as-is. [Inference](/paperwork/capabilities/extract#schema-inference) chooses its own field names and can choose differently on the next run. Take the returned `config.schema` and remove the fields you do not need. Then send it as `schema`, or save it once:

```bash
curl -sX POST https://api.cloudraker.com/v1/extract/configs \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "W9 identity", "config": { "schema": { "…": "the pinned schema" } } }'
```

Then every call is `{"file": …, "action": "w9-identity"}`. Send volume through [`POST /v1/extract/batch`](/paperwork/capabilities/extract#batch).

## Install the skill

A ready-made skill file packages the same contract for an agent's skills directory:

Download SKILL.md

Put it in your agent's skills folder (for Claude Code: `.claude/skills/cloudraker-api/SKILL.md`). The agent then loads it when a task touches the CloudRaker API.

## Use the MCP servers

Two MCP servers do different jobs:

* **`https://mcp.cloudraker.com`** serves the API itself. The agent searches the live surface and executes generated calls with your key. [MCP server](/paperwork/developers/mcp) covers setup, auth, and the bundled skills.
* **`https://docs.cloudraker.com/_mcp/server`** serves these docs. Query the documentation directly instead of fetching pages.

```bash
claude mcp add --transport http cloudraker https://mcp.cloudraker.com \
  --header "Authorization: Bearer $CLOUDRAKER_API_KEY"
claude mcp add --transport http cloudraker-docs https://docs.cloudraker.com/_mcp/server
```

## Rules to hold on to

* Branch on the error `code`, never on `message`. Every `/v1` failure is `{code, message, retryable, requestId, docUrl}`.
* A slow run is `202` with a handle, never a timeout error.
* Citations are off by default. Send `"citations": true` when you need the evidence. Without it, the output has no `citations` key.
* The limit is at least 67 requests per minute per organization across all of `/v1`. On `429`, sleep for `Retry-After`, then back off. See [Rate limits](/paperwork/developers/rate-limits).
* No result appears in the CloudRaker app until you [`keep`](/paperwork/developers/runs#keep-a-run) the run.
* Reuse `fileId`s instead of URLs. The API does not fetch or parse the document again.

## Where to go next

#### [API context for agents](/developers/agents)

The single-file contract this page tells you to fetch.

#### [Extract](/capabilities/extract)

Inference, saved configs, batching, and every configuration field.

#### [Runs](/developers/runs)

Listing, polling, TTL, and keeping a result.

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

Drive the whole API from an MCP client through Code Mode.