> 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 written for a coding agent — Claude Code, Cursor, or anything else writing the integration for a human. If you are the human: paste this URL into your agent and let it work.

## 1. Fetch the contract

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

That single Markdown file is the whole API contract: base URL, auth, all six verbs with minimal bodies, the file union, the run lifecycle, the extraction schema dialect, the error envelope with every code, and the rate limit. Read it before writing code — it is short enough to hold in context and specific enough that you should not guess a field name.

Three more machine-readable surfaces, 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 any page URL for its Markdown.                                                                                                         |
| `https://docs.cloudraker.com/openapi.json`         | The OpenAPI document — the full gateway spec, batch and run listing included. Large; re-exported whenever the surface changes. Prefer `agents.md` if the two ever disagree. |

## 2. Get a key

The human you're working for creates it in the CloudRaker app under **Admin → API keys** (admin-only, shown once) and 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 — no schema to write, no local file to stage:

```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",
    "metadata": { "job": "agent-quickstart" }
  }'
```

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

```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 it takes longer than the wait cap you get `202` with the same body minus `output` — poll `statusUrl`, don't treat it as an error.

## 4. Then write the real integration

Do not ship the call above as-is. [Inference](/capabilities/extract#schema-inference) chooses its own field names and can choose differently next time. Take the `config.schema` it returned, edit it down to the fields you actually need, and either send it as `schema` or save it once:

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

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

## Install the skill

A ready-made skill file — the same contract packaged for an agent's skills directory — is here:

Download SKILL.md

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

## Use the MCP servers

Two MCP servers, different jobs:

* **`https://mcp.cloudraker.com`** — the API itself. The agent searches the live surface and executes generated calls with your key. Setup, auth, and the bundled skills are on [MCP server](/developers/mcp).
* **`https://docs.cloudraker.com/_mcp/server`** — 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.
* At least 67 requests per minute per organization across all of `/v1`; on `429` sleep for `Retry-After`, then back off. See [Rate limits](/developers/rate-limits).
* Nothing shows up in the CloudRaker app until you [`keep`](/developers/runs#keep-a-run) the run.
* Reuse `fileId`s instead of re-sending URLs — the document isn't re-fetched or re-parsed.

## 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 actions, 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.