Changelog¶

This file tracks meaningful changes to this guide and the published external contract.

Versioning and deprecation policy¶

Guide updates¶

Editorial changes, clarifications, examples, and navigation updates do not require an API-version bump.

API contract changes¶

The public API is versioned through Accept: application/vnd.revento.v1+json.
Breaking response-shape or behavior changes are introduced in a new version.
When a new version is announced, the previous version remains supported for at least 6 months.
Deprecation notices are published here and through Revento's integration-management notices.

Documentation corrections¶

A correction aligns this guide with the existing public API behavior. Corrections remain in the current API version, but may still require changes to code written against an earlier version of the guide. Each correction below states the old documented shape and the current contract.

Non-breaking changes inside a version¶

The following may change inside v1 without a version bump:

Clarified prose, examples, and setup guidance
Additional examples that do not alter the underlying contract
New optional fields documented as additive

Changes that always receive explicit notice¶

New API version availability
Deprecation of an existing version
Scope-consent changes that require existing connections to re-consent
Webhook-delivery changes that affect verification, retry, or payload interpretation

Unreleased¶

This update defines the public v1 contract for the forthcoming release of this guide. It substantially expands and corrects the contract before that release, so no earlier public API version is being deprecated and the 6-month support window does not apply. Future breaking changes after the release of v1 will use a new API version under the policy above.

If you generated a client or implemented response validation from an earlier preview of the guide, regenerate it from the updated OpenAPI document and review the migration notes below.

Added¶

registration_wave.canceled, bringing the webhook catalog to 28 event types. It is sent when an organizer cancels a registration wave. registration_wave.finished is not sent for a canceled wave.
personal_data_withheld on activity resources, in webhook payloads and GET /events/{id}/activities. It distinguishes an empty people field from personal data that was withheld. Unlike the participant resource's flag, this activity-level flag routinely becomes true during normal operation; treat that as an ordinary redaction state, not an exceptional failure.
field on validation_error responses, identifying the invalid parameter.
406 not_acceptable in the error catalog and on read operations.
A complete connection journey covering integration registration, organizer installation, and participant authorization and revocation.
The machine-readable OpenAPI document and the Schemas & tooling guide.
Expanded guidance for secret rotation, token lifetimes, cursor handling, webhook operations, and integration-management endpoints.

Changed¶

Participant identifiers returned by GET /me/profile and POST /oauth/token are now scoped per integration. This includes profile.user_id, the token response's user_id, and the id_token sub claim. The value matches the participant id used by installation-token endpoints and webhook payloads. Do not assume it matches a value stored from an earlier response.
Unresolvable cursors return 400 validation_error with field: "cursor". Start pagination again without a cursor instead of retrying the same request.
Every error body includes request_id.
X-Revento-Request-Id is echoed when valid. Missing or invalid values are replaced with a generated correlation id.
Accept is optional. Omitting it, or sending */* or application/*, selects the current version. Unsupported concrete media types return 406 not_acceptable.

Corrected documentation¶

The following items correct earlier published guidance. They describe the current v1 contract.

Response envelopes and pagination¶

List endpoints return {"items": [...], "next_cursor": ...}. The earlier {data, next_cursor, has_more} shape is not part of the contract.
GET /events/{id} returns {"event": ...} and GET /events/{id}/participants/{id} returns {"participant": ...} rather than a bare resource.
/locations returns a flat, paginated list. venue, building, floor, and thread are bare ids or null, not nested objects.
/threads, /locations, /registration-waves, /roles, and /program paginate with a default page size of 25.
limit is clamped to 1-50. A non-numeric value uses the default of 25.
413 payload_too_large is not listed as an API response; reducing limit is not an error-recovery mechanism.

Resource schemas¶

The event resource now documents all 35 fields. The organization field is organization, and the headline location field is location.
Participant resources do not include user_id, registered_at, last_reviewed_at, last_reviewer_id, or last_review_action. They include is_guest, application_admin_notes, and personal_data_withheld.
Registration-wave resources use start_time, end_time, and base_activities, and now document all 15 fields.
Location and role resources include created_at and updated_at; locations also include venue and thread.
Activity resources include players, host, is_global, time_preference, and type_definition. They do not include duration_minutes or signed_up_participant_ids.
Every declared resource field is present; unavailable values are null. Undeclared resource fields are rejected by the schemas.
Array fields such as players, markers, co_host_ids, registration_waves, and amenities may be null. Check for null before iterating.

Field types and values¶

language and time_preference are arrays, not strings.
A thread's icon_name and color_hex may be null.
min_age is all_ages or 18+. Do not derive constant names directly from enum values.
Timestamp fields do not share one suffix. Use each field's declared format.
capacity_mode is fixed or percentage; notify_when is a timestamp.
Closed vocabularies are declared for publish_status, visibility, capacity_mode, audience, access_mode, and status fields.
access_mode also supports paid_ticket.

Authentication, errors, and profile responses¶

application/json is a response Content-Type, not a supported concrete Accept value. Request application/vnd.revento.v1+json, use a supported wildcard, or omit Accept.
Installation token responses do not include integration_id.
Token responses do not include refresh_expires_in. Track the 90-day refresh window from the latest successful refresh.
user_id and id_token are conditional and always appear together. Both are absent when no participant pseudonym is available.
request_id is an opaque correlation string, not necessarily a UUID. A UUID remains a recommended request-header value.
insufficient_scope includes required_scope as a single scope name. validation_error includes field.
GET /me/profile returns a top-level profile object and does not include locale or event_id.

Webhooks and lifecycle behavior¶

Webhook envelopes do not include a top-level id; the delivery identifier is carried by X-Revento-Delivery-Id. Undeclared envelope fields are rejected by the schemas.
activity_details is a bare identifier, not an object.
actor_id on lifecycle notices is an opaque audit reference, not a participant identifier, and cannot be resolved through this API.
Disconnecting an integration does not send a webhook. A subsequent API call returns 401 token_revoked; existing deletion obligations still apply.
participant.removed removes event membership and registration-wave eligibility, but the participant record and application remain available. The person cannot simply re-apply while the existing application stands, except after rejection or a revision request; treat removal as terminal instead of waiting for another participant.registered event.
The public contract uses one OAuth host and one API host. Testing uses the same hosts and an event you control.

Initial release¶

Initial release of the external integrations developer guide.