API for developers

The API lets apps do everything a host does: create and edit events, publish, pause and close them, read responses and results, moderate, answer questions, export, and use the AI features your plan includes. It's built for Android and iOS apps as well as scripts.

The full reference is at /api/v1/openapi.json (OpenAPI 3.1). Load it in any OpenAPI viewer, or generate a client for Kotlin, Swift, TypeScript and more.

Sign-in

Apps (mobile, web, desktop) use OAuth 2.1 with PKCE:

1. Register once: POST /oauth/register with your app name and redirect address. That can be https://…, a loopback address like http://127.0.0.1:8080/callback, or your app's own scheme like com.example.notes:/oauth.
2. Open /oauth/authorize in the system browser (not a web view) with response_type=code, your client_id, redirect_uri, code_challenge (S256), state and the scopes you need, e.g. scope=read write.
3. The host signs in and allows your app (with their password, unless they just signed in). Swap the returned code at POST /oauth/token. A host can have up to 20 apps connected; a code not yet swapped stops working if the host resets their password or changes two-step sign-in.
4. Send Authorization: Bearer <access_token>. Tokens last an hour; refresh with grant_type=refresh_token. Refresh tokens change each time, so always keep the newest. Two refreshes sent within a few seconds with the same token both get the same new pair. Using any older refresh token again disconnects your app, and a connection ends a year after the host allowed it.

The server's details are at /.well-known/oauth-authorization-server. If something is wrong with the request (an unknown scope, no PKCE), the host sees the error on our page; your app only hears back once they've chosen Allow or Cancel.

Scopes:

• read: see events, responses, results, AI summaries and co-hosts. Every GET needs it.
• write: create and change events, publish, pause and close them, moderate and answer.
• manage: invite and remove co-hosts. Ask for it only if you need it: the host is told that people you invite keep their access after your app is disconnected, and the event's owner gets an email for every invitation.

write and manage include read. Unknown or empty scopes are refused (invalid_scope).

New apps are shown to hosts as Unverified app, with your full return address. The site's admin can block an app.

Scripts can use a personal API key from your Account page as the bearer token. You choose what it can do (read only; read and change; or read, change and manage co-hosts) and when it expires (30, 90 or 365 days, or never). Creating one asks for your password (and a code, if you use two-step sign-in), and we email you each time. Resetting your password or changing two-step sign-in deletes all your keys and disconnects your apps.

Good to know

• Replies are { "data": … }; errors are { "error": { "code", "message" } } with a matching HTTP status.
• Up to 120 requests a minute per token, expired ones included (an expired token gets 401, so refresh it). Requests with a wrong token are also limited per IP address. Each network can register a few apps an hour, and each IPv6 /48 a few times that; registering the same app again returns the same client_id. Request bodies can be up to 200 KB. For live screens, poll GET /events/{id}/live every few seconds and redraw when version changes.
• New events start as drafts on the free plan. Payments only happen on the website. GET /events/{id}/upgrade gives the link to open.
• Plan features (templates, AI question suggestions, AI summary) follow each event's plan, just like on the website.
• The site's admin can switch the API off. When it's off, requests get 403 disabled.