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

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

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:

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

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

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

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

Install the skill

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

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 covers setup, auth, and the bundled skills.
• https://docs.cloudraker.com/_mcp/server serves 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.
• 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.
• No result appears in the CloudRaker app until you keep the run.
• Reuse fileIds instead of URLs. The API does not fetch or parse the document again.

Where to go next