API overview
Base URL, authentication, request and response conventions, pagination, idempotency and request IDs for the Diced REST API.
Base URL
https://api.diced.si/v1JSON in and out, over HTTPS. Field names are snake_case and ids carry a prefix: aud_
(audience), lead_ (lead), tp_ (topic), enr_ (enrichment job), wh_ (webhook endpoint),
evt_ (event). The full OpenAPI 3.1 document is public at
https://api.diced.si/v1/openapi.json; the endpoint pages
in this section are generated from it.
Authentication
Create a key in the app under Developers → API keys and send it on every request:
Authorization: Bearer dcd_live_...Keys belong to a workspace and act for it. We store only a hash, so a key is shown once, when you
create it. Revoke a key in the app and it stops working at once. A missing, malformed or revoked
key gets 401 unauthorized with a
WWW-Authenticate: Bearer realm="diced" header.
Requests and responses
- Send bodies as JSON with
Content-Type: application/json. A body that isn't valid JSON is a400invalid_request. - Unknown fields in a request body are rejected, so typos fail loudly.
- Successful responses are JSON objects with a
request_idfield.DELETEanswers204with no body. - Builds and batch jobs are asynchronous and answer
202:POST /v1/audiencesandPOST /v1/enrich/batch. - Errors always have the same shape. See Errors.
Request IDs
Every response, success or error, carries a Diced-Request-Id header (req_...). The same id is
in the body as request_id (or error.request_id). Quote it when you contact
support@diced.si.
Pagination
List endpoints are cursor-paginated:
GET /v1/audiences?limit=50&cursor=eyJ...| Parameter | Default | Max |
|---|---|---|
limit | 25 | 100 |
cursor | The next_cursor from the previous page |
Each page is { "data": [...], "next_cursor": "..." }. next_cursor is null on the last page.
GET /v1/chips pages its ledger the same way, under ledger.
Idempotency
The POSTs that spend chips or start work take an Idempotency-Key header (1 to 255 characters;
a UUID works well):
POST /v1/audiencesPOST /v1/audiences/{id}/revealPOST /v1/enrichPOST /v1/enrich/batch
Repeat a request with the same key within 24 hours and you get the original response back,
with an Idempotent-Replayed: true header and the original request_id, without being charged or
building twice.
- A key is tied to the request that first used it. Reusing it with a different body or path is a
409with codeinvalid_request. - While the first request is still running, a repeat is also a
409. Retry shortly. - If the first request failed (any non-2xx), the key is released: fix the request and retry with the same key.
- Keys are scoped to your workspace.
Rate limits
120 requests per minute per key, with RateLimit-* headers on every response. See
Rate limits.
Versioning
The version is in the path (/v1). Within v1 we only add things: new endpoints, new optional
request fields, new response fields, new event types and new error details. Treat unknown fields
as ignorable. Breaking changes would ship as /v2, announced in the changelog.