API usage

The conventions that apply to every revenexx API call — one gateway, the request headers, JSON, request IDs, and the response headers worth knowing.

Everything you call on revenexx goes through one gateway. The rules on this page — how you authenticate, how requests are versioned, what a response looks like — are the same for every endpoint, whether you reach it with an SDK or by hand. The per-endpoint specifics (paths, parameters, schemas) live in the API Explorer.

One gateway

There is a single base URL, and every path is versioned under /v1:

text

https://api.revenexx.com/v1/...

Requests and responses are JSON (Content-Type: application/json). There is no per-region host and no separate "admin" endpoint — the same gateway serves every capability your tenant has installed.

Request headers

Every request carries the tenant it's scoped to, plus a credential. See Authentication for how to obtain each.

Header	Required	Purpose
`X-Revenexx-Tenant`	Yes	The tenant slug the request is scoped to.
`X-Revenexx-Api-Key`	One credential	A scoped key (`rvxk_…`) for server-side and machine-to-machine calls.
`Authorization: Bearer <jwt>`	One credential	A user token, for calls made on behalf of a signed-in user.

Send either an API key or a Bearer token — not both. The tenant header is always required.

Request IDs

The gateway assigns every request an X-Request-ID, and generates one if you don't send your own. Successful responses echo it back. Error responses may not carry it, so if you want a correlation id you can quote for certain — including on the 4xx responses you are most likely to ask about — send your own and log it: quoting it makes any support request traceable end to end.

Request

curl -i https://api.revenexx.com/v1/products \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..."

Response headers worth knowing

Header	Meaning
`X-Request-ID`	Correlation id for this request — include it in support tickets.
`X-Capability-App`	Which installed app served the capability.
`X-Capability-Degraded`	Present when a fallback implementation served the request.
`X-Cache`	`HIT` or `MISS` when the capability's response is cacheable.

X-Capability-App and X-Capability-Degraded tell you which implementation answered — useful when a capability has been overridden by an App and a response looks unfamiliar. X-Cache appears only on endpoints whose capability declares a cache policy, and never on writes. Assume a response was not cached unless you actually see the header.

From browser JavaScript you can read X-Request-ID, X-Capability-App and X-Capability-Degraded — they are exposed for cross-origin reads. X-Cache is not, so fetch() returns null for it even though it is present on the wire. Read it with a server-side call or curl -i when you need it.

In this section

Rate limits — the per-tenant budget and how to handle 429.
Errors — the error shape and the status codes you'll see.
Debug a failed request — from a failed response to its cause, step by step.
Pagination & filtering — listing conventions.
Retries & idempotency — what's safe to retry.
Versioning & stability — what /v1 guarantees.
Trash — how deleted records wait in the trash, restore, and emptying versus the purge.

Was this page helpful?