API reference

REST API for the verification layer.

Manage batches, fetch verification data, and subscribe to events. Base URL https://api.certik.io.

Authentication

All requests require a bearer token. Generate keys from your dashboard under Settings → API. Keys are scoped per environment (test / live).

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Never expose live keys in client-side code. Use the <certik-badge> embed for browsers — it uses a public, read-only verification path.

Endpoints

All responses are JSON. Errors follow { error: { code, message } }.

GET/v1/batches

List all batches in your account

Returns paginated batch records with status, purity, and verification URLs.

curl https://api.certik.io/v1/batches \
  -H "Authorization: Bearer $CERTIK_API_KEY"

# 200 OK
{
  "data": [
    {
      "id": "CL-9F2A-7C31-B4E8",
      "batch_id": "NW-24-A1207",
      "product": "BPC-157",
      "purity": 0.9874,
      "status": "authentic",
      "verified_at": "2025-04-12T14:22:00Z",
      "verify_url": "https://certik.io/v/CL-9F2A-7C31-B4E8"
    }
  ],
  "next_cursor": null
}

GET/v1/batches/{id}

Retrieve a single batch

Returns full lab report data including HPLC trace, mass spec, and PDF link.

curl https://api.certik.io/v1/batches/CL-9F2A-7C31-B4E8 \
  -H "Authorization: Bearer $CERTIK_API_KEY"

POST/v1/batches

Creates a batch record. Used when shipping samples programmatically from your ERP or LIMS.

curl -X POST https://api.certik.io/v1/batches \
  -H "Authorization: Bearer $CERTIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_id": "NW-24-A1208",
    "product": "TB-500",
    "lot_size_mg": 5000,
    "manufactured_at": "2025-04-10"
  }'

GET/v1/batches/{id}/assets

Get badge & QR assets for a batch

Returns SVG/PNG asset URLs for the verified badge and QR code.

curl https://api.certik.io/v1/batches/CL-9F2A-7C31-B4E8/assets \
  -H "Authorization: Bearer $CERTIK_API_KEY"

GET/v1/verifications

List verification scan events

Aggregated scan analytics: timestamps, geographies, referring URLs.

curl "https://api.certik.io/v1/verifications?batch=CL-9F2A-7C31-B4E8" \
  -H "Authorization: Bearer $CERTIK_API_KEY"

Webhooks

Subscribe to events to keep your storefront, ERP, or analytics in sync. All payloads are signed with HMAC-SHA256 — verify the Certik-Signature header before trusting the body.

Event	Description
`batch.published`	A new verified batch is live and the badge is active.
`batch.failed`	A batch failed testing. Will not be made public.
`batch.updated`	Batch metadata or report was updated.
`verification.scanned`	A customer scanned the QR or tapped the badge.

// Example payload
{
  "id": "evt_01HX...",
  "type": "batch.published",
  "created": 1745087220,
  "data": {
    "batch_id": "NW-24-A1207",
    "verify_url": "https://certik.io/v/CL-9F2A-7C31-B4E8",
    "purity": 0.9874
  }
}

Rate limits & SDKs

Default limit is 600 requests/minute per key. Verification reads (the public /v/<id> path) are unmetered. Official SDKs are available for Node.js, Python, and Go.

# Node.js
npm install @certik/node

# Python
pip install certik