Skip to main content

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​

ScopeGrants
activities:readList and read activities. Also required by GET /ping.
sessions:readList and read sessions.
sessions:writeStart a session of a published activity, and move it through its questions.
results:readLive results, the session overview, and response exports.
outcomes:readPull one integration's outcome events. Must be bound to that integration when minted. See Pulling outcomes.
integrations:registerRegister 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:

ActionAllowed whileEffect
startlobby, pausedOpen the first question for answers.
open_voting, close_votingrunningAccept, or stop accepting, answers to the current question.
reveal_resultsrunningShow the current question's results.
reveal_answerrunningShow the correct answer.
show_leaderboardrunningShow the leaderboard.
next, previousrunningMove to the next question (opened for answers) or the previous one (shown with its results).
gotorunningOpen the question named by interaction_id.
cuerunningShow the question named by interaction_id without opening it for answers; open_voting opens it.
pause, resumerunning / pausedPause and resume the session.
closelobby, running, pausedEnd 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 detail field; see API errors.
  • Pagination on list endpoints is limit (1-100, default 50) and offset.
  • Times are ISO 8601 in UTC.
  • Request ids. Every response carries an X-Request-ID header. 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.