REST API
The public API lives under {MURMLE}/api/public/v1. It is versioned separately from the
console's own API, because it is a promise to somebody else's code: it changes only additively
within v1.
What it does: list activities, start a session of a published activity and drive it through its questions, read live results, the overview and exports, and the integration endpoints described in the contract. What it does not do: authoring. Activities are built in the console; the API runs and reads them.
The full list of endpoints, parameters and response shapes is the generated API reference.
API keys
A key looks like pk_<prefix>_<secret> and is sent as a bearer token:
GET /api/public/v1/activities HTTP/1.1
Host: murmle.example.org
Authorization: Bearer pk_3f9a1c0b7d2e_Xq...
- Minting. A workspace owner creates keys in Console > Integrations > API keys, choosing a name and the scopes. The secret is shown once, in a panel that stays until you dismiss it. Murmle stores only a hash of it; there is no way to reveal it again.
- The prefix identifies a key without being one. The console shows
pk_<prefix>, and it is safe to quote in a support ticket. - Revoking. Keys are revoked, not deleted, so "what had access last March" stays answerable. A revoked key stops working at once.
- A key belongs to a workspace, not a person. It carries its own scopes rather than inheriting anyone's role, so it does not gain or lose reach when the person who minted it changes role or leaves.
- Failures are uniform. An unknown prefix, a wrong secret and a revoked key all return the
same
401.
Scopes
| Scope | Grants |
|---|---|
activities:read | List and read activities. Also required by GET /ping. |
sessions:read | List and read sessions. |
sessions:write | Start a session of a published activity, and move it through its questions. |
results:read | Live results, the session overview, and response exports. |
outcomes:read | Pull one integration's outcome events. Must be bound to that integration when minted. See Pulling outcomes. |
integrations:register | Register one integration for approval. See Self-service registration. |
A key created without choosing scopes gets activities:read, sessions:read and
results:read. A request that needs a scope the key lacks gets 403 with a detail naming the
scope.
GET /api/public/v1/ping confirms that a key works and returns its workspace and scopes. It needs
activities:read.
Starting and driving a session
POST /sessions takes the activity_id of a published activity, an optional title and an
optional mode. The session uses the privacy mode of the activity's published version - the API
cannot override it - and opens in the lobby.
POST /sessions/{id}/transition with {"action": "..."} moves it:
| Action | Allowed while | Effect |
|---|---|---|
start | lobby, paused | Open the first question for answers. |
open_voting, close_voting | running | Accept, or stop accepting, answers to the current question. |
reveal_results | running | Show the current question's results. |
reveal_answer | running | Show the correct answer. |
show_leaderboard | running | Show the leaderboard. |
next, previous | running | Move to the next question (opened for answers) or the previous one (shown with its results). |
goto | running | Open the question named by interaction_id. |
cue | running | Show the question named by interaction_id without opening it for answers; open_voting opens it. |
pause, resume | running / paused | Pause and resume the session. |
close | lobby, running, paused | End the session. Its join code is released. |
An action in the wrong state returns 409 with a sentence saying why, such as "This is the last
question".
Results and exports
GET /sessions/{id}/results- each question's live result projection, the same data the presenter's screen draws.GET /sessions/{id}/overview- headline numbers: participants, submissions, responses, completion, average score, the privacy mode, and whether the session is scored.GET /sessions/{id}/export?shape=wide|long&format=csv|xlsx- the same file the console exports, described in Results and export.
Privacy rules apply exactly as they do in the console. In any session that is not identified, the export names no one.
Conventions
- JSON in, JSON out, with explicit read models: a response contains the documented fields and nothing else, so a new internal column never appears in the API by accident.
- Errors carry a
detailfield; see API errors. - Pagination on list endpoints is
limit(1-100, default 50) andoffset. - Times are ISO 8601 in UTC.
- Request ids. Every response carries an
X-Request-IDheader. Send your own and it is used instead, which makes a support conversation much shorter. - Rate limits. Pulling outcomes is limited to 60 calls per minute per key, and registration to
5 per minute per key. Over the limit you get
429.