API Documentation

Authentication

Send your TamperCheck API key as a Bearer token: Authorization: Bearer dt_.... Configure AI providers in the dashboard; the default verified provider is used for analysis.

Analyze endpoint

Request (multipart)

Upload the file as document (PDF, JPG, PNG, WEBP, BMP, TIFF; max 40 MB). Optional fields: document_identifier (your correlation id, max 512 chars) and mode (async or instant).

Async & instant modes

Omit mode or send mode=async for the default: the API enqueues analysis and responds immediately. Send mode=instant when the client can hold the connection open until analysis finishes (typically a few seconds).

Async — upload (default)

curl -sS -X POST "https://api.tampercheck.ai/api/v1/documents/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "document=@./document.pdf" \
  -F "document_identifier=loan-app-12345" \
  -F "mode=async"

Async — 202 response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "original_filename": "statement.pdf",
  "document_identifier": "loan-app-12345",
  "page_count": 3,
  "documents_billed": 3
}

Async — poll status

curl -sS "https://api.tampercheck.ai/api/v1/documents/<job-uuid>/status/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use exponential backoff when polling (e.g. start at 1s, cap around 5–10s). Stop when status is completed or failed.

Instant — upload

curl -sS -X POST "https://api.tampercheck.ai/api/v1/documents/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "document=@./document.pdf" \
  -F "mode=instant"

Response

Instant mode and GET job detail return 200 with verdict (authentic or tampered), risk_score (0–100), findings, calibration, explanation, and timestamps when analysis is done.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "original_filename": "statement.pdf",
  "document_identifier": "loan-app-12345",
  "document_type": "bank_statement",
  "verdict": "tampered",
  "risk_score": 42,
  "confidence": 0.78,
  "findings": [
    {
      "category": "font_inconsistency",
      "severity": "medium",
      "description": "Mixed font metrics in the totals row.",
      "confidence": 0.71
    }
  ],
  "cv_metrics": {},
  "metadata_analysis": null,
  "processing_time_s": 3.2,
  "calibration": {
    "score_breakdown": {},
    "suppressed_count": 0,
    "calibration_notes": [],
    "calibrated_findings": []
  },
  "explanation": "Plain-language summary…",
  "human_summary": "…",
  "created_at": "2026-04-02T12:00:00Z",
  "completed_at": "2026-04-02T12:00:03Z"
}

Error responses

All error responses return a JSON body with error (machine-readable code) and detail (human-readable message). Some errors also include the job id and status.

Example error responses

402 — Insufficient balance

{
  "detail": "Insufficient wallet balance. Please top up at /dashboard/billing."
}

503 — AI service unavailable

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "ai_service_unavailable",
  "detail": "The AI analysis service is temporarily unavailable. Your document was not charged. Please retry in a few moments."
}

422 — Processing failed

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "processing_failed",
  "detail": "Could not decode image bytes"
}

Related endpoints

Same Authorization header on all routes below.

• GET /api/v1/documents/list/ — list jobs for this API key
• GET /api/v1/documents/<uuid>/status/ — poll async jobs (lightweight)
• GET /api/v1/documents/<uuid>/ — full results when status is completed
• GET /api/v1/usage/?since=&until= — usage summary

AI providers

Configure AI provider keys under Dashboard → Developers. The public API does not accept per-request provider headers.

MCP for Claude Code and Cursor

The tampercheck-mcp server exposes the same REST API to coding agents (stdio, local). Set TAMPERCHECK_API_KEY in the server environment.

pip install tampercheck-mcp
claude mcp add --transport stdio --env TAMPERCHECK_API_KEY="dt_..." tampercheck -- tampercheck-mcp

API keys: Dashboard → Developers. Cursor: add the same command in mcp.json. See the tampercheck-mcp README for full setup.