SDK & integration quickstart

Authentication

Issue a key from the API keys page in the dashboard and send it in the Authorization header (format: Bearer YOUR-KEY). Each endpoint advertises the scope it requires; full reference lives in the API documentation.

• csk_live_… — production tenant, billed against your plan quota.
• csk_test_… — sandboxed test tenant, free, no production data.
• Scopes (analyze, account:read) limit a key to the minimum needed. Issue narrow keys per integration.

Submit your first analysis

All three snippets POST a single image to /v1/analyze and parse the verdict. Replace the file path and your environment variable as needed.

cURL

curl -X POST https://api.claimscan.io/v1/analyze \
  -H "Authorization: Bearer $CLAIMSCAN_API_KEY" \
  -H "Idempotency-Key: claim_50421_attempt_1" \
  -F "image=@./return_photo.jpg" \
  -F "orderDate=2026-04-20" \
  -F "productName=Wireless Earbuds" \
  -F "claimDescription=Customer reports the buds arrived crushed."

Node.js

// Node 22+ — global `fetch` and `FormData` are built in.
import { readFile } from "node:fs/promises";

const apiKey = process.env.CLAIMSCAN_API_KEY!;
const imageBytes = await readFile("./return_photo.jpg");

const form = new FormData();
form.set(
  "image",
  new File([imageBytes], "return_photo.jpg", { type: "image/jpeg" })
);
form.set("orderDate", "2026-04-20");
form.set("productName", "Wireless Earbuds");
form.set("claimDescription", "Customer reports the buds arrived crushed.");

const res = await fetch("https://api.claimscan.io/v1/analyze", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Idempotency-Key": "claim_50421_attempt_1",
  },
  body: form,
});

if (!res.ok) {
  // application/problem+json — see /docs/api for the full error catalog.
  const problem = await res.json();
  throw new Error(`Claimscan ${res.status}: ${problem.title}`);
}

const verdict = await res.json();
console.log(verdict.verdict, verdict.confidence, verdict.findings.length);

Python

import os
import requests

API_KEY = os.environ["CLAIMSCAN_API_KEY"]

with open("./return_photo.jpg", "rb") as fp:
    response = requests.post(
        "https://api.claimscan.io/v1/analyze",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Idempotency-Key": "claim_50421_attempt_1",
        },
        files={"image": ("return_photo.jpg", fp, "image/jpeg")},
        data={
            "orderDate": "2026-04-20",
            "productName": "Wireless Earbuds",
            "claimDescription": "Customer reports the buds arrived crushed.",
        },
        timeout=30,
    )

response.raise_for_status()
verdict = response.json()
print(verdict["verdict"], verdict["confidence"], len(verdict["findings"]))

What costs quota and what does not

Reads of your account or smoke-tests of your key never consume quota. Only /v1/analyze does:

# Cheap / free
GET /v1/ping             # liveness probe (no auth, no quota)
GET /v1/auth/whoami      # smoke-test your key (no quota)
GET /v1/account          # plan + period (account:read scope)
GET /v1/account/usage    # remaining quota (account:read scope)

# Quota-consuming
POST /v1/analyze         # 1 unit per call (analyze scope)

Idempotency

Pass an Idempotency-Key header (any string ≤ 255 chars) to safely retry a request without double-charging quota. A second call with the same key + same body within 24 hours returns the original response. Mismatched bodies on a reused key return 409.

Error handling

All errors follow RFC 7807 (application/problem+json). The full catalog with stable type URIs is in the API reference; the headline status codes you should handle:

• 401 — Missing, malformed or revoked key.
• 402 — Monthly quota exceeded — Retry-After header tells you when it resets.
• 403 — Key valid but missing the required scope.
• 413 — Image larger than 25 MiB.
• 422 — Decoded image larger than 100 MP — decompression-bomb guard.
• 429 — Rate limit exceeded — RateLimit-* headers carry the budget.

Native SDKs

Native SDKs ship in the months following GA. Until then the HTTP examples above are the supported integration path.

Need a specific integration sooner? Tell us what you need and we will prioritise.