Test mode
How it differs from live
| Test key (ctk_test_) | Live key (ctk_live_) | |
|---|---|---|
| Claims it sees | Only test claims; a live claim id is a 404 | Only live claims; a test claim id is a 404 |
| Claims it creates | Test claims, reachable only through a test key (not shown or openable in the app) | Real claims, visible to the organization |
| Photo analysis | A fixed set of realistic items, back in seconds | Full AI analysis and pricing |
| Webhooks | To test endpoints only, "livemode": false (see below) | To live endpoints, for live claims |
| Billing | Never billed | Approved items count toward the plan |
| Rate limits | Same as live | 300 requests a minute per key |
The canned pipeline
In test mode, photos you add are accepted and stored but not sent to the model. Each one comes back at once with a fixed, realistic set of priced items, picked by the photo's externalId (or its filename). That makes test runs fast and repeatable: the same request produces the same inventory every time, which is what you want in a CI suite.
Test endpoints receive every event for test claims, with "livemode": false. The ones the pipeline raises (photos.analysis_completed, items.priced, export.ready) arrive within about a minute of the change, as they do in live mode.
Trying the real pipeline
To see real analysis on your own photos before going live, send the header below with a test key when you add photos. The real pipeline runs, capped at 50 photos per organization per UTC day (then a 429 test_live_ai_cap_reached), and is still never billed. Sending it with a live key is a 400.
X-Contents-Test-Mode: live-aiMoving to live
- Create a live key with the same scopes, and swap it in through configuration, not code.
- Register your webhook endpoint again for live events; test and live endpoints are separate.
- Keep your test key for CI. Nothing about the request shapes changes between modes; see Authentication.
The mode field on GET /api/v1/me tells you which kind of key a process is holding, which is worth a startup check in production.