Read API overview¶

The full per-endpoint reference is on Endpoints. This page covers the cross-cutting concerns: authentication, versioning, pagination, correlation IDs, errors. Read this once and the per-endpoint pages become a quick lookup.

Base URL¶

Environment	Base
Production (and sandbox)	`https://api.revento.example/api/v1`

There is no separate sandbox endpoint. Sandbox usage means connecting your integration to a curated test event hosted by Revento — same URL, different event id. See Sandbox & test environment.

URLs in Endpoints are written relative to the base.

Authentication¶

Every API request requires a Bearer header with an installation token (event-scoped) or user token (participant-scoped). Token type matters per endpoint — see the table on each endpoint page.

Authorization: Bearer rev_install_8h3k2m...
Accept: application/vnd.revento.v1+json

Wrong token type for an endpoint returns 403 user_token_required or 403 installation_token_required. See Errors.

API versioning¶

Pin a version with the Accept header. Today there's only v1:

Accept: application/vnd.revento.v1+json

If you omit the Accept header, you get the current default version. Fine for development, risky for production — pin the header so a version transition can't silently change your response shape.

Versioning commitment: any previous version is supported for at least 6 months after the next version is announced, with the deprecation surfaced in your developer console and in the changelog.

Correlation IDs¶

Send a UUID on every request:

X-Revento-Request-Id: 0f8ad6e2-7e1a-4e7e-bc3c-8f5b1c4d2e3f

We echo it back in the response and write it to our logs. When you contact support, hand them this UUID — investigation drops from minutes to seconds.

You can use any UUID format (v4 is fine). It only needs to be unique per request on your side.

Pagination¶

List endpoints return:

{
  "data":        [ /* array of resources */ ],
  "next_cursor": "opaque-string-or-null",
  "has_more":    true
}

To fetch the next page, pass next_cursor as the cursor query parameter:

GET /events/{event_id}/participants?limit=25
GET /events/{event_id}/participants?limit=25&cursor=eyJjIjogIjI...

Rules:

The cursor is opaque. Don't parse it. Format may change without notice.
has_more is the canonical "more pages exist" signal. Don't rely on next_cursor != null — cursors are opaque, and a non-null final cursor is permitted by the contract.
limit defaults to 25, max 50. Kept conservative because list responses can carry custom_form_fields per row and may approach the per-response payload cap on rich-form events. If you receive 413 payload_too_large, reduce limit and retry.

Errors¶

Every error response has the same envelope:

{
  "error":      "string_code",
  "message":    "Human-readable explanation",
  "request_id": "UUID matching X-Revento-Request-Id"
}

The error code is the machine-readable identifier. Branch on this in your code. The message is for humans (logs, support tickets); it may evolve.

Full error catalog is in Errors. The codes you'll see most often:

Code	Meaning
`token_expired`	Refresh and retry
`token_revoked`	Permanent — re-consent required
`insufficient_scope`	Token doesn't grant this endpoint
`event_not_authorized`	Token is for a different event
`rate_limit_exceeded`	Back off (Retry-After header has duration)

Idempotency¶

All current endpoints are read-only GETs, so no idempotency keys are required. Repeating a request gives the same response (modulo data changes between calls).

Headers we always send¶

Every API response includes:

X-RateLimit-Limit:        500
X-RateLimit-Remaining:    487
X-RateLimit-Reset:        1747000000
X-Revento-Request-Id:     {your UUID echoed}
Content-Type:             application/vnd.revento.v1+json; charset=utf-8

See Rate limits for header semantics.

Time format¶

All timestamps in request and response bodies are ISO 8601 in UTC:

{
  "start_date": "2026-08-15T16:00:00Z"
}

We never return local times. Convert to local at your display layer using whatever your stack provides (Intl in browsers, pytz / zoneinfo in Python, etc.). Same convention applies to webhook payloads.

Cursor stability¶

If you're storing cursors (e.g. for resumable sync), be aware:

Cursors remain valid for at least 24 hours.
Cursors are tied to the (endpoint, query, token) tuple — a cursor from /events/{a}/participants doesn't work on /events/{b}/participants.
After 24 hours we make no guarantee. If you need long-running paginated reads, complete them within a session.

Developer console¶

Your developer console (URL provided at registration) is where you:

View your integration's metadata
Manage redirect URIs and webhook URL via your integration manifest
See dead-letter webhook deliveries
Replay specific webhook deliveries
Read audit logs of token issuance and refresh
See current rate-limit status per token
Rotate client_secret and webhook signing secrets

These operations are available in the developer console UI.