SDK & Integrations-Quickstart

Authentifizierung

Schlüssel auf der API-Keys-Seite im Dashboard erzeugen und als Authorization-Header mitschicken (Format: Bearer DEIN-KEY). Jeder Endpoint nennt den geforderten Scope; vollständige Liste in der API-Dokumentation.

• csk_live_… — Produktiv-Tenant, zählt auf dein Plan-Kontingent.
• csk_test_… — Sandboxed Test-Tenant, kostenlos, keine produktiven Daten.
• Scopes (analyze, account:read) begrenzen einen Schlüssel auf das Nötige. Lieber schmale Schlüssel pro Integration als einen Master-Key.

Erste Analyse abschicken

Alle drei Snippets schicken ein einzelnes Bild per POST an /v1/analyze und lesen das Verdikt aus. Dateipfad und Env-Variable anpassen, fertig.

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"]))

Was Kontingent kostet — und was nicht

Lese-Calls auf das Konto und Smoke-Tests des Schlüssels sind kostenlos. Nur /v1/analyze verbraucht Kontingent:

# 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)

Idempotenz

Mit einem Idempotency-Key-Header (beliebiger String ≤ 255 Zeichen) lassen sich Requests gefahrlos wiederholen, ohne das Kontingent doppelt zu belasten. Ein zweiter Call mit gleichem Key + gleichem Body innerhalb von 24 h liefert die Originalantwort. Abweichende Bodies bei wiederverwendetem Key liefern 409.

Fehlerbehandlung

Alle Fehler folgen RFC 7807 (application/problem+json). Vollständiger Katalog mit stabilen type-URIs in der API-Referenz; die Statuscodes, die du behandeln solltest:

• 401 — Schlüssel fehlt, ist falsch formatiert oder widerrufen.
• 402 — Monatskontingent überschritten — Retry-After-Header verrät den Reset-Zeitpunkt.
• 403 — Schlüssel gültig, aber ohne den geforderten Scope.
• 413 — Bild grösser als 25 MiB.
• 422 — Dekodiertes Bild grösser als 100 MP — Decompression-Bomb-Schutz.
• 429 — Rate-Limit erreicht — RateLimit-*-Header zeigen das Budget.

Native SDKs

Native SDKs folgen in den Monaten nach GA. Bis dahin sind die HTTP-Beispiele oben der unterstützte Integrationsweg.

Du brauchst eine bestimmte Integration früher? Sag uns Bescheid — wir priorisieren entsprechend.