---
name: tampercheck-api
description: >-
  Help developers integrate TamperCheck.ai’s public document-fraud API (HTTP, auth,
  multipart upload, responses, billing). Use when writing clients, SDKs, tests, or
  docs for TamperCheck from outside the product codebase.
---

# TamperCheck.ai — API integration (for Claude Code)

## What this skill is for

Use this when the user wants to **call TamperCheck from their own application** (scripts, backends, mobile apps, CI, etc.). Focus on the **public HTTPS API** only. Do **not** assume access to TamperCheck’s internal systems, repositories, or admin tools.

## Product (one sentence)

TamperCheck analyzes uploaded files—**PDFs, camera photos, and scans** (JPG, PNG, WEBP, BMP, TIFF, PDF)—for tampering and fraud signals, returning a **verdict**, **risk score**, and structured **findings**. Processing is **synchronous** on the main ingest endpoint.

## Base URL

- **Production API:** `https://api.tampercheck.ai`

All paths below are relative to that host (e.g. full URL: `https://api.tampercheck.ai/api/v1/documents/`).

## Getting credentials

1. The user signs up at **tampercheck.ai** and opens the **Dashboard**.
2. They create an **API key** under **Developers** (or equivalent). Keys look like `dt_...`.
3. They may need to add a **payment method** and **wallet funds** before requests succeed if trial credits are exhausted.

Third-party integrations never send LLM provider keys (OpenAI, Anthropic, etc.) to TamperCheck’s API body or headers for document analysis—those are configured **in the dashboard** by the account owner.

## Authentication

Every request:

```http
Authorization: Bearer <TAMPERCHECK_API_KEY>
```

Without a valid key, the API responds with **401**.

## Endpoints

| Method | Path | Role |
|--------|------|------|
| `POST` | `/api/v1/documents/` | Upload a document; analysis runs in the same request. |
| `GET` | `/api/v1/documents/list/` | List analysis jobs for this API key. |
| `GET` | `/api/v1/documents/<uuid>/` | Fetch one job by id (must belong to this key). |
| `GET` | `/api/v1/usage/?since=...&until=...` | Usage summary for billing/observability. |

Date query params for usage should be in a format the API accepts (ISO-8601 date/datetime strings are typical).

## `POST /api/v1/documents/` — request

- **Content-Type:** `multipart/form-data`
- **Fields:**
  - **`document`** (required): file — PDF, JPG, PNG, WEBP, BMP, or TIFF; **max 20 MB**.
  - **`document_identifier`** (optional): string (e.g. your loan id or ticket id), up to **512** characters, returned in the response for correlation.
  - **`skip_ai`** (optional): boolean — when true, skip the LLM step and rely on computer-vision signals only.

### Example (`curl`)

```bash
curl -sS -X POST "https://api.tampercheck.ai/api/v1/documents/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "document=@./file.pdf" \
  -F "document_identifier=case-2026-001"
```

### Example notes for generated code

- Use the platform’s multipart upload (e.g. `FormData` in browsers, `multipart.File` in Python, etc.).
- Do not base64 the whole request unless the user explicitly wants a non-multipart flow—**the documented API is multipart**.

## Success response (HTTP 200)

On success, expect JSON including (names may appear in this spirit; always handle unknown fields defensively):

- **`id`**, **`status`** (e.g. completed when done)
- **`original_filename`**, **`document_identifier`**
- **`document_type`** (detected category)
- **`verdict`** — see below
- **`risk_score`** — numeric risk (commonly **0–100**, higher = riskier)
- **`confidence`**
- **`findings`** — array of objects with fields such as **`category`**, **`severity`**, **`description`**, **`confidence`** (and sometimes region/evidence)
- **`ai_analysis`**, **`cv_metrics`**, **`metadata_analysis`** (as applicable)
- **`processing_time_s`**
- **`calibration`** — scoring breakdown and calibrated findings (structure is nested JSON)
- **`explanation`**, **`human_summary`**
- **`created_at`**, **`completed_at`**

Do **not** invent legacy fields such as **`tamper_score`** or a nested **`analysis.points_checked`** unless the live API documentation the user pastes explicitly includes them.

### Verdict values

`verdict` is typically one of:

- `authentic`
- `suspicious`
- `tampered`

## Errors

| Status | Meaning | What to build |
|--------|---------|----------------|
| **401** | Bad or missing API key | Prompt user to fix the key or login to dashboard. |
| **402** | Insufficient wallet balance | Tell the user to **add funds** (billing) before retrying. |
| **400** | Bad file (empty, wrong type, too large) | Validate file type and size client-side when possible. |
| **422** | Processing failed | Read **`error`** in the body; optionally surface **`id`** for support. |

## Billing and trial (product-level)

- Usage is typically **pay-as-you-go** from a **wallet** (e.g. a per-document price such as **$0.50** — always tell the user to confirm current pricing on **tampercheck.ai/pricing**).
- New accounts may receive **trial credits** (e.g. **$5**). When credits run out, expect **402** until the wallet is funded.

## How Claude Code should behave

1. **Prefer official docs** the user provides or links (`https://tampercheck.ai/docs` if available) over guessing fields.
2. **Generate integration code** (HTTP client, error handling for 401/402/422, optional retries only where safe).
3. **Never fabricate** response fields; if uncertain, say what is stable (multipart + Bearer auth + verdict/risk/findings) and suggest a test call.
4. **Keep secrets out of logs** (API keys in env vars, not committed files).
5. **Do not reference** internal implementation details of TamperCheck’s own apps or repositories—this skill describes the **public API contract** only.

## Quick integration checklist

- [ ] API key in environment variable
- [ ] `POST` multipart with `document`
- [ ] Handle **402** with a clear “add funds” path
- [ ] Parse **`verdict`**, **`risk_score`**, **`findings`**
- [ ] Optional: store **`document_identifier`** and **`id`** for support and idempotency discussions with the user