REST quickstart
The shape of the REST API and where to find the full interactive reference.
The public REST API lives under https://app.kaminari.ad/api/v1. Every
endpoint is JSON in, JSON out, authenticated with a Bearer token.
Submit and read a scan
# Submit — url (or ad_tag / vast_tag), 2-letter country_code, emulator_id
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", "country_code": "US", "emulator_id": "samsung_galaxy_a15_android16"}'
# Read
curl https://app.kaminari.ad/api/v1/scans/$SCAN_ID \
-H "Authorization: Bearer $KAM_API_KEY"
Conventions
- IDs are opaque strings (UUIDs) — don't parse them.
- Pagination uses
limit+ an offset/page parameter on list endpoints. - Timestamps are ISO-8601 UTC.
- Discover valid
country_codeandemulator_idvalues viaGET /api/v1/geosandGET /api/v1/emulators. - Add an optional
referrer(http(s) page URL) to check the creative from a publisher page — forad_tag/vast_tagit is the page the tag is embedded in, forurlit is where the visitor came from. See the Scans API.
Full reference
Every endpoint, parameter, and response field — with request/response samples — is in the interactive Swagger reference at app.kaminari.ad/docs. This guide covers the workflows; Swagger is the exhaustive contract.