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

$
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:

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:

$
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:

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

1
{
2
  "object": "extract_run",
3
  "id": "exr_01KYD1J8QW2RN4T6VXZ0ABCDEF",
4
  "status": "processed",
5
  "config": {
6
    "schema": {
7
      "type": "object",
8
      "properties": {
9
        "form_type": { "type": ["string", "null"], "description": "Form identifier (e.g., W-9)" },
10
        "form_revision_date": { "type": ["string", "null"], "description": "Form revision date (e.g., March 2024)" },
11
        "catalog_number": { "type": ["string", "null"], "description": "IRS catalog number for the form (e.g., 10231X)" }
12
      }
13
    }
14
  },
15
  "output": {
16
    "value": { "form_type": "W-9", "form_revision_date": "March 2024", "catalog_number": "10231X" },
17
    "citations": {
18
      "form_type": [
19
        {
20
          "fileId": "a0375090-2f78-4fc5-a016-cb29dc43f8ea",
21
          "page": 0,
22
          "bbox": { "x": 0.091, "y": 0.037, "width": 0.065, "height": 0.036 },
23
          "text": "Form W-9",
24
          "confidence": 5
25
        }
26
      ]
27
    }
28
  }
29
}

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

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

Install the skill

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

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.
• https://docs.cloudraker.com/_mcp/server — these docs. Query the documentation directly instead of fetching pages.

$
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.
• Nothing shows up in the CloudRaker app until you keep the run.
• Reuse fileIds instead of re-sending URLs — the document isn’t re-fetched or re-parsed.

Where to go next