Battery compliance API for travel platforms.

The public verifier endpoint can be tested without an account. Partner keys only change limits, allowed origins, and support terms; they do not change the verdict contract.

curl -s https://certiwatt.app/api/verify \
  -H 'content-type: application/json' \
  -d '{
    "model_id": "anker-737",
    "ccc_mark": "present",
    "trip": {
      "origin": "CN",
      "destination": "CN",
      "airline": "CA",
      "compartment_intent": "carry_on"
    },
    "options": { "language": "en" }
  }'

Endpoint

POST /api/verify

Auth

Anonymous calls are accepted. Partner traffic uses x-certiwatt-key or Authorization: Bearer when issued.

Rate limit

Public traffic is rate limited and returns 429 with Retry-After. Partner limits are issued with the key.

Contract

OpenAPI contract: /openapi.yaml

{
  "verdict": "conditional",
  "verdict_id": "vdt_01JZ8EXAMPLETRIP00000001",
  "ruleset_version": "2026-05-15",
  "generated_at": "2026-06-06T08:40:12.000Z",
  "expires_at": "2026-06-13T08:40:12.000Z",
  "summary": "Carry-on only. Airline approval may be required.",
  "device_resolved": {
    "model_id": "anker-737",
    "brand": "Anker",
    "model_name": "737 Power Bank",
    "watt_hour": 86.4,
    "recall_status": "not_affected",
    "recall_check_method": "model_match"
  },
  "constraints": [
    { "code": "carry_on_only", "message": "Carry-on only — never in checked baggage." },
    { "code": "max_units_2", "message": "Maximum 2 power banks per passenger." }
  ],
  "warnings": [
    { "code": "airline_approval_review", "severity": "advisory", "message": "Confirm airline handling before departure." }
  ],
  "citations": [
    { "kind": "regulator", "authority": "CAAC", "jurisdiction": "CN", "url": "https://...", "pulled_at": "2026-05-29" },
    { "kind": "airline", "authority": "Singapore Airlines", "jurisdiction": "SG", "url": "https://...", "pulled_at": "2026-05-29" }
  ],
  "verdict_path": ["iata_spare_lithium_battery", "cn_3c_screening", "sq_power_bank_policy"]
}

Use POST /api/trips/verify when the product flow needs a whole itinerary, not a single route. CertiWatt expands origin, transit, and destination into segment verdicts, then returns an aggregate verdict that can be shown in booking, baggage, insurance, support, or agent workflows.

POST /api/trips/verify

{
  "device": { "model_id": "anker-737" },
  "trip": {
    "origin": "CN",
    "transit": ["SG"],
    "destination": "US",
    "airline": "SQ",
    "compartment_intent": "carry_on"
  },
  "options": { "language": "en" }
}

{
  "public_name": "Trip Battery Pass",
  "trip_verdict_id": "trip_lx5t9d3a_q8z1r2p4",
  "verdict": "conditional",
  "summary": "Trip requires conditions or approval on at least one of 2 segments.",
  "segments": [
    {
      "index": 1,
      "origin": "CN",
      "destination": "SG",
      "airline": "SQ",
      "verdict": { "verdict": "conditional", "ruleset_version": "2026-05-15", "verdict_id": "vdt_..." }
    },
    {
      "index": 2,
      "origin": "SG",
      "destination": "US",
      "airline": "SQ",
      "verdict": { "verdict": "allowed", "ruleset_version": "2026-05-15", "verdict_id": "vdt_..." }
    }
  ],
  "device_resolved": { "model_id": "anker-737", "watt_hour": 86.4 },
  "citation_count": 4,
  "ruleset_version": "2026-05-15",
  "generated_at": "2026-06-06T08:40:12.000Z",
  "expires_at": "2026-06-13T08:40:12.000Z"
}

verdict

allowed, conditional, banned, or insufficient.

verdict_id

Stable handle for support reviews, partner logs, and later audit exports.

ruleset_version

The rule corpus used for the answer. The public API currently accepts only the current ruleset_version; unsupported pins return 400.

device_resolved

Canonical model, Wh, certifications, recall_status, recall_check_method, and exact-model recall records when applicable.

constraints

Carry-on-only, approval, quantity, label, certification, onboard-use, or recall constraints that can be rendered in product UI.

citations

Primary source trail for regulator, airline, manufacturer, or recall evidence.

expires_at

Freshness boundary for a platform decision shown inside booking, baggage, insurance, or support workflows.

A public answer layer can summarize policy. A platform integration needs a decision service with freshness, request preservation, source-change visibility, and reviewable evidence for support and operations.

Freshness window

Verdicts carry generated_at and expires_at; source monitoring and ingest dry-runs keep regulator, airline, manufacturer, and recall evidence reviewable before partners rely on it.

Audit trail

Store verdict_id, request payload, ruleset_version, and citations for support review and later audit exports. Unsupported historical ruleset pins return an explicit 400 instead of a silent fallback.

Change intelligence

Partner policy-change access exposes change history, source-watch rows, fingerprints, and review queue signals rather than a stale rules summary.

Serial responsibility

Pattern-backed recalls can resolve affected/not_affected locally; manufacturer-list recalls return external_list_required and an official lookup URL rather than a guessed clearance.

Pilot scope

Response targets, support windows, allowed origins, rate limits, and escalation paths are set in the partner pilot scope, not by anonymous public API use.

The public API surface is useful for discovery and testing. Partner traffic uses an agreed pilot scope, credential setup, and failure-mode review before launch.

Partner auth

Partner traffic uses issued partner API keys; anonymous public calls do not carry pilot support terms.

Allowed origins

Allowed origins, rate limits, Retry-After behavior, production response targets, and support windows are agreement terms.

Failure modes

conditional, banned, insufficient, MODEL_NOT_FOUND, AIRLINE_NOT_COVERED, external_list_required, 429, 5xx, and stale expires_at cannot be converted into allowed.

Ruleset pins

The public API accepts the current ruleset_version only; historical replay requires the stored request payload and a controlled audit export.

Data boundary

No PII is required by default. Use serial_hash unless signed data-flow terms permit raw serial transit.

These endpoints are the integration surface behind the public verifier. Anonymous responses remain useful for discovery; partner or authenticated access unlocks deeper policy fields, change history, and operational support.

POST /api/verify

Trip-specific battery verdict with citations, route factors, recall evidence, airline policy context, ruleset_version, and verdict_id. Requests with transit stops must use POST /api/trips/verify.

POST /api/trips/verify

Multi-leg Trip Battery Pass response with aggregate verdict, per-segment verdicts, citation_count, device_resolved, ruleset_version, generated_at, expires_at, and segment-level errors when coverage is missing.

GET /api/devices

Search covered power-bank models. Supports q, limit, and recent for catalog discovery.

GET /api/devices/[modelId]

Return canonical model facts. Optional serial adds model-level recall serial_evaluation when applicable.

GET /api/devices/[modelId]/recalls

Return exact-model Battery Recall Intelligence with optional serial evaluation.

GET /api/recalls

List model-specific recall records. Supports model_id, status, and serial.

GET /api/airlines

List Airline Policy Intelligence records. Supports q, confidence, and limit.

GET /api/airlines/[code]

Anonymous requests return a public preview; partner/authenticated requests return active rules, citations, policy_fields, and change_log.

GET /api/policy-changes

Anonymous requests return change/watch counts; partner/authenticated requests return change history, source-watch rows, fingerprints, and review queue signals.

GET /api/rules

Search active regulator and airline rules.

GET /api/sources

Return normalized citation evidence for a model or rule.

For transparency and machine discovery, CertiWatt publishes limited static JSON previews. Full airline policy fields, rule logic, change history, audit export, and partner-grade exports remain product/API surfaces.

{
  "long_tail_verdicts": [
    {
      "route_factors": [
        "capacity check is tied to this exact catalog model",
        "Citation sources: CAAC (regulator, CN, 2026-05-29)"
      ],
      "article_body": "Summary plus route factors. Citation sources: CAAC (regulator, CN, 2026-05-29).",
      "ruleset_version": "2026-05-15",
      "citation_count": 3,
      "sources": [
        { "authority": "CAAC", "url": "https://...", "pulled_at": "2026-05-29" }
      ]
    }
  ]
}