Developers
Build on the Ulsav public API: authentication, pagination, errors, webhooks, and the generated endpoint reference.
Ulsav's public API is a supported product surface from day one. Use it to:
- build participant-facing frontends
- sync Orders and Registrations into your own systems
- run admission tooling
- feed the reporting data your finance team needs
Three surfaces call the same Go application modules:
- the browser UI
- REST clients
- webhooks
Tenancy, capability checks, and lifecycle rules are therefore identical however you connect, and an action refused in the organizer webapp is refused here for the same reason.
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://api.ulsav.com |
| Development | https://api.ulsav.dev |
Every endpoint is versioned under /api/v1. The version is part of the path, not a header.
The live OpenAPI document is served at /api/v1/openapi.json, with interactive documentation at /api/v1/docs. The API reference is generated from that document, so it is the authoritative list of paths, request bodies, and response schemas.
These pages explain what the document cannot:
- how to obtain a credential
- which conventions collections share
- what webhooks guarantee
Credentials
- Anonymous. Discovery and published-content reads declare no authentication and return only public data.
- Organization API key. A machine credential for one Organization's data, created in the organizer webapp and sent as
Authorization: Bearer ulsav_sk_.... - OAuth access token. A user-scoped credential for a signed-in person, issued by Sign in with Ulsav and used by third-party frontends.
Keys and tokens travel in the Authorization header, never in a query string. Ulsav session cookies are first-party only; a third-party frontend never receives them.
Start here
Quickstart
Make a public read, fetch one Event, then call an Organization endpoint with an API key.
Authentication
Anonymous reads, Organization API keys, OAuth access tokens, and the CORS tiers between them.
API keys
Issue, scope, rotate, and revoke an Organization machine credential.
Conventions
Cursor pagination, filters, idempotency, request IDs, rate limits, and versioning.
Errors
The RFC 9457 problem envelope, stable codes, and what to send to support.
Webhooks
Subscribe to signed Organization events, verify them, and replay failed deliveries.
API reference
Every operation, generated from the live OpenAPI document.
The OpenAPI document wins
If a page here and the live OpenAPI document disagree about a path, parameter, or field, trust the document. These pages explain intent; the document describes the shipped contract.