Theme
Requests and responses
Conventions that hold across the whole API, so you only have to learn them once.
Base URL
https://public.eu.zefi.ai/v1The host carries the region your workspace lives in; v1 is the version, which is always in the path.
Paths name resources and nothing else:
/v1/campaigns/{campaign_id}/linksThe workspace is not in the path. A key is bound to one workspace at creation, so there is only ever one answer and the server already has it. Asking callers to repeat it would add a parameter whose only possible use is to be wrong.
One consequence worth planning for: to act on several workspaces you hold several keys and select the key, not a path.
Versioning
v1 is current. Within a version we will add, not break:
- new endpoints
- new fields on existing responses
- new values in an existing enum, where the field already documents that it may grow
Parse defensively — ignore fields you do not recognise — and none of the above will reach you as an incident. Anything that would break a working integration ships as v2, alongside v1, with notice.
Content types
Send Content-Type: application/json on every request with a body. Successful responses are application/json; failures are application/problem+json. See Errors.
Identifiers
Every id is a UUID, rendered as a string, and opaque. An id is stable for the life of the thing it names.
Your own identifiers travel alongside ours rather than replacing them: reference on a create entry is echoed back on that entry's result, so you can match rows to results without trusting array order. Zefi never interprets it.
It is a correlation aid for one response, not a stored field — it is absent from list and retrieve. Keep the link_id you get back if you need to find the link again.
Timestamps
All timestamps are RFC 3339 in UTC, to the millisecond:
json
{ "expires_at": "2026-09-26T12:54:39.000Z" }Send them the same way. A timestamp without a timezone is rejected rather than guessed at.
Pagination
List endpoints are cursor-paginated. Ask for a page size with limit (1–100, default 25), and follow next_cursor:
bash
curl -G "https://public.eu.zefi.ai/v1/campaigns/$CAMPAIGN_ID/links" \
-H "Authorization: Bearer $ZEFI_API_KEY" \
-d limit=100 \
-d cursor="$NEXT_CURSOR"json
{
"items": [ … ],
"next_cursor": "eyJwayI6ICJ3c18xMjMi…"
}There is no total
next_cursor being null is the only signal that a listing is exhausted. There is no count to compare against, and a page can come back shorter than limit while more pages remain. Loop until next_cursor is null — never until a page looks short.
Treat the cursor as opaque: it encodes position, not an offset, and its format is not part of the contract.
Rate limits
Every response carries your remaining budget in RateLimit headers. See Rate limits.
