Kaminari Ad

Your first scan via the API

Submit a creative URL over REST and get back the scan's status, classification, and a screenshot — in a few lines of cURL.

No SDK required — the REST API works from any language. This example uses cURL. The base URL is https://app.kaminari.ad/api/v1.

1. Get an API key

Create a key under Account -> API Keys in the dashboard, then send it as a Bearer token on every request. Treat it like a password.

2. Submit a scan

A scan needs a url (or an ad_tag, or a vast_tag for VAST video ads), a 2-letter country_code, and an emulator_id. List the valid values with GET /api/v1/emulators and GET /api/v1/geos.

Add the optional referrer to run the check from a publisher page: for ad_tag / vast_tag it is the page the tag is embedded in, for url it is where the visitor came from. See the Scans API.

curl -X POST https://app.kaminari.ad/api/v1/scans \
  -H "Authorization: Bearer $KAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/banner.html",
    "referrer": "https://publisher.example/news/article-1",
    "country_code": "US",
    "emulator_id": "samsung_galaxy_a15_android16"
  }'

The response returns the scan id and an initial status of pending. Scans run asynchronously.

3. Read the result

Poll GET /api/v1/scans/{id} until status is completed (or partial / failed):

{
  "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "url": "https://example.com/banner.html",
  "referrer": "https://publisher.example/news/article-1",
  "country_code": "US",
  "emulator_id": "samsung_galaxy_a15_android16",
  "status": "completed",
  "classification": {
    "brand": "Acme",
    "ai_category": { "tier1": "Finance" },
    "iab_v3": { "tier1": "Personal Finance" }
  },
  "redirect_chain": [{ "url": "https://example.com/banner.html" }],
  "screenshot_url": "/api/v1/scans/a1b2c3d4-.../screenshot",
  "created_at": "2026-06-08T16:00:00Z",
  "completed_at": "2026-06-08T16:00:42Z"
}

Screenshots stream through authenticated endpoints (GET /api/v1/scans/{id}/screenshot) — there are no public storage URLs. A scan's tags (findings) are delivered through the scanning.tags.detected webhook and can be used to filter the scan list (GET /api/v1/scans?tag=<slug>).

4. Next steps

  • Subscribe to a webhook to receive scans as they finish instead of polling — see Webhooks.
  • To scan one URL across several countries in one call, use POST /api/v1/scans/bulk — see the Scans API.
  • The full endpoint reference (every parameter and field) is in the interactive Swagger docs at app.kaminari.ad/docs.
← All documentation