FAQ

How do I get an API key?

Self-serve from the web-client settings page, or ask Voyage staff to issue one. A key is minted off your brand's connected shop, so any brand already connected to a Shopify shop can get a key with no new app install. See the Quickstart.

Why can't I use my API key to rotate or revoke keys?

Key management requires a session credential — an API key can never manage keys. This is a containment guarantee: a leaked key cannot mint itself a replacement or rotate around its own revocation. See Authentication.

Why do I get a 404 for a profile I expected to exist?

A single-profile read returns 404 for both a non-existent id and an id that belongs to another brand — they are deliberately indistinguishable, so a brand cannot probe for another brand's ids. Confirm the id belongs to your shop scope.

My deep ?offset request returns 400. Why?

offset + limit must stay inside the 10,000-row OpenSearch result window. To enumerate beyond it, drop ?offset and follow the nextCursor token instead. See Pagination.

totalSize seems wrong / too small.

totalSize is an OpenSearch result-window estimate capped at 10,000 — not a true total. When paginating with the cursor, ignore totalSize and keep going until nextCursor is null.

Does ingest need a credential?

No. POST /cdp/ingest is credential-free by design — the browser sends only Content-Type and the server injects the upstream credential. Any Authorization you send is ignored. See Ingest.

What status does a successful ingest return?

Treat success as 2xx. Today the proxy returns the upstream status (typically 200); a parallel change (CDLA-033) moves ingest to 202 Accepted for asynchronous forwarding. Branch on the 2xx class.

Why is the page size capped at 100?

The CDP runs on one shared cluster across every brand. A tight, bounded page size keeps a single caller from degrading the cluster for everyone. The staff-internal cap is higher; the public API is intentionally half of it.