Kreuzberg Cloud

Kreuzberg Cloud

Kreuzberg Cloud is the managed extraction API hosted at https://api.kreuzberg.dev. It exposes the same Rust extraction engine as the local kreuzberg CLI, with two extras: jobs are asynchronous (webhook or polling delivery) and large files go through presigned uploads instead of in-band base64.

Use this skill when writing code that:

• Hits api.kreuzberg.dev directly via HTTP.
• Uses the @kreuzberg/cloud (npm) or kreuzberg-cloud-sdk (PyPI) SDKs.
• Configures webhooks, sandbox keys, or usage queries.

v0.1.0 limitation

The kreuzberg-cloud plugin v0.1.0 ships skills only — no MCP server. The kreuzberg-cloud CLI binary that hosts the MCP server lands in plugin v0.2.0. Until then, prefer one of:

1. The TypeScript SDK (@kreuzberg/cloud) — ESM, tree-shakable, generated from the OpenAPI 3.1 spec.
2. The Python SDK (kreuzberg-cloud-sdk) — sync + async, from_sandbox() helper for evaluation.
3. Raw curl — every example below shows the curl form first.

When cloud vs local

Getting an API key

Three options, in order of preference for production:

1. Production key — sign up at https://kreuzberg.dev/cloud, mint a key from the dashboard. Format: sk_live_*.

2. Sandbox key — no signup, 24-hour TTL, 50-page quota, rate-limited to 10 keys per IP per 24 hours. Format: sk_sandbox_*. See the sandbox-keys skill.

3. Local ~/.kreuzberg/cloud.toml — for shell sessions, put the key in:

   # ~/.kreuzberg/cloud.toml
   api_key = "sk_live_..."
   

The plugin's SessionStart hook checks KREUZBERG_API_KEY env var first, then ~/.kreuzberg/cloud.toml, and emits a setup reminder if neither is present.

Authentication

Every request — except POST /v1/sandbox/key — uses a Bearer token:

curl https://api.kreuzberg.dev/v1/usage \
  -H "Authorization: Bearer $KREUZBERG_API_KEY"

Both sk_live_* and sk_sandbox_* go in the same header. The server resolves project context from the key.

Base URL and versioning

• Base: https://api.kreuzberg.dev
• Path prefix: /v1/ for all extraction, jobs, sandbox, uploads, usage endpoints. Health endpoints (/healthz, /readyz) are unversioned.
• The OpenAPI 3.1 spec is published at https://api.kreuzberg.dev/openapi.json; full reference at https://docs.kreuzberg.cloud.

The 12 endpoints

Twelve operations across seven tag groups:

health (2)

Neither requires auth. Use /readyz for uptime monitors and /healthz for load-balancer health checks.

extract (1)

Accepts application/json (base64 documents) or multipart/form-data (binary file parts). Returns 202 Accepted with job_ids (extraction jobs) and crawl_job_ids (URL-crawl jobs). Pair with GET /v1/jobs/{id} to retrieve results — or supply a webhook block to receive them asynchronously. See the offloading-extraction skill.

jobs (1)

Accepts both extraction job IDs and crawl job IDs. Response shape varies: extraction jobs return JobResponse, crawl jobs return CrawlJobResponse. See the tracking-cloud-jobs skill.

documents (4)

For applications that re-process the same document over time. Each extraction returns a document_id that's stable across versions.

uploads (2)

Three-step flow for files larger than ~50 MB: presign → PUT to storage → confirm. See the presigned-uploads skill.

sandbox (1)

24-hour TTL, 50-page quota, 10 keys per IP per 24 hours. No auth required. See the sandbox-keys skill.

usage (1)

Accepts optional start and end ISO-8601 query params. Defaults to the current calendar month. See the managing-cloud-usage skill.

Key request / response shapes

ExtractJsonRequest

{
  "documents": [
    {
      "filename": "invoice.pdf",
      "mime_type": "application/pdf",
      "data": "<base64>"
    }
  ],
  "urls": [
    { "url": "https://example.com/docs" }
  ],
  "options": {
    "extraction_config": {
      "output_format": "markdown",
      "ocr": { "backend": "tesseract", "language": "eng" }
    }
  },
  "crawl_config": {
    "max_depth": 2,
    "max_pages": 50,
    "stay_on_domain": true
  },
  "webhook": {
    "url": "https://example.com/webhook",
    "secret": "shared-hmac-secret",
    "metadata": { "request_id": "abc123" }
  }
}

Either documents or urls is required (or both). webhook, options, and crawl_config are optional.

ExtractResponse (202)

{
  "job_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "crawl_job_ids": ["660e9400-f39c-51e5-b827-557766551111"],
  "status": "pending"
}

JobResponse (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "invoice.pdf",
  "status": "completed",
  "created_at": "2025-12-21T10:00:00Z",
  "processing_time_ms": 1234,
  "result": {
    "content": "Invoice total: $1,234.56",
    "mime_type": "text/markdown",
    "tables": [],
    "images": [],
    "metadata": { "title": "Invoice #12345" }
  }
}

JobStatus enum

awaiting_upload | pending | processing | chunking | aggregating
                | completed | partial_success | failed | cancelled

Terminal states: completed, partial_success, failed, cancelled. Stop polling when any of those appears.

UsageResponse (200)

{
  "period_start": "2026-05-01",
  "period_end": "2026-06-01",
  "total_pages": 5432,
  "total_documents": 87,
  "total_failed": 2,
  "quota_limit": 100000,
  "quota_remaining": 94568,
  "by_mime_type": {
    "application/pdf": { "documents": 65, "pages": 3200, "failed": 1 }
  }
}

Error model

All errors are JSON with at least an error string field. Status codes follow REST conventions:

The SDKs surface these as typed exceptions: AuthError, ValidationError, NotFoundError, RateLimitError (carries retry_after), ServerError, TimeoutError, all extending KreuzbergCloudError (Python) / KreuzbergError (TypeScript).

Concrete examples

Sandbox onboarding (no signup)

# Mint an ephemeral key.
curl -X POST https://api.kreuzberg.dev/v1/sandbox/key
# → { "api_key": "sk_sandbox_...", "expires_at": "...", "pages_remaining": 50 }

import { KreuzbergCloud } from "@kreuzberg/cloud";
const client = await KreuzbergCloud.fromSandbox();
const result = await client.extractAndWait({
  file: new Blob(["Hello world"], { type: "text/plain" }),
});
console.log(result.result?.content);

from kreuzberg_cloud import AsyncKreuzbergCloud
async with await AsyncKreuzbergCloud.from_sandbox() as client:
    job = await client.extract_and_wait(file=b"hello world")
    print(job.status, job.result and job.result.content)

Single-file extract → poll

# 1. Submit.
JOB_ID=$(curl -sX POST https://api.kreuzberg.dev/v1/extract \
  -H "Authorization: Bearer $KREUZBERG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {"filename": "invoice.pdf", "mime_type": "application/pdf",
       "data": "'"$(base64 -w0 invoice.pdf)"'"}
    ],
    "options": {"extraction_config": {"output_format": "markdown"}}
  }' | jq -r '.job_ids[0]')

# 2. Poll until terminal.
curl -s https://api.kreuzberg.dev/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $KREUZBERG_API_KEY"

Other skills

• offloading-extraction — full POST /v1/extract workflow with options.
• tracking-cloud-jobs — polling cadence, webhook signatures.
• presigned-uploads — three-step flow for files >50 MB.
• versioning-documents — retrieve a document, list its versions, diff two versions.
• managing-cloud-usage — quota and per-MIME breakdown.
• sandbox-keys — when to recommend sandbox over production keys.

References

• API docs: https://docs.kreuzberg.cloud
• OpenAPI spec: https://api.kreuzberg.dev/openapi.json
• TypeScript SDK: https://www.npmjs.com/package/@kreuzberg/cloud
• Python SDK: https://pypi.org/project/kreuzberg-cloud-sdk/
• Pricing and signup: https://kreuzberg.dev/cloud

Source: hashgraph-online/awesome-codex-plugins → plugins/kreuzberg-dev/plugins/plugins/kreuzberg-cloud/skills/kreuzberg-cloud/SKILL.md