Skip to content

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/v1

The 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}/links

The 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.

Zefi API v1