Skip to main content

API reference

Every endpoint of the public API, generated at build time from the OpenAPI schema that the backend publishes. Authentication, scopes and conventions are explained in REST API. The schema itself can be downloaded as public-v1.json for code generators and API clients.

All endpoints take Authorization: Bearer pk_<prefix>_<secret> and return JSON with a detail field on errors. Every endpoint can return 401 (no key, or an unknown, wrong or revoked one) and 403 (the key lacks the scope); 422 means a parameter or field broke a rule.

Endpoints​

MethodPathScope
GET/activitiesactivities:read
GET/activities/{activity_id}activities:read
POST/integrationsintegrations:register
GET/integrations/{integration_id}any key bound to the integration
GET/integrations/{integration_id}/outcomesoutcomes:read (bound to the integration)
POST/integrations/{integration_id}/signing-secretintegrations:register (the key that registered it)
GET/pingactivities:read
GET/sessionssessions:read
POST/sessionssessions:write
GET/sessions/{session_id}sessions:read
GET/sessions/{session_id}/exportresults:read
GET/sessions/{session_id}/overviewresults:read
GET/sessions/{session_id}/resultsresults:read
POST/sessions/{session_id}/transitionsessions:write

Paths are relative to {MURMLE}/api/public/v1.

Activities​

GET /api/public/v1/activities​

List Activities. Scope: activities:read.

ParameterInTypeRequiredRules
kindquerypoll, quiz, survey, qa (optional)no
limitqueryintegernomin 1, max 100, default 50
offsetqueryintegernomin 0, default 0

Success: 200.

GET /api/public/v1/activities/{activity_id}​

Get Activity. Scope: activities:read.

ParameterInTypeRequiredRules
activity_idpathstringyes

Success: 200.

Integrations​

POST /api/public/v1/integrations​

Register Integration. Scope: integrations:register. Guide: Self-service registration.

Request body:

FieldTypeRequiredRules
namestringyesmin length 1, max length 200
external_systemstringyesmin length 1, max length 64, pattern ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
issuerstringyesmin length 1, max length 500
jwks_uristringyesmin length 1, max length 500
webhook_urlstring (optional)nomax length 500
instructor_rolesarray of string (optional)no

Any other field is refused with 422.

Success: 201.

GET /api/public/v1/integrations/{integration_id}​

Get Registered Integration. Scope: any key bound to the integration. Guide: Self-service registration.

ParameterInTypeRequiredRules
integration_idpathstringyes

Success: 200.

GET /api/public/v1/integrations/{integration_id}/outcomes​

Pull Outcomes. Scope: outcomes:read (bound to the integration). Guide: Pulling outcomes.

ParameterInTypeRequiredRules
integration_idpathstringyes
afterquerystring (optional)nomax length 200
limitqueryintegernomin 1, max 200, default 50

Success: 200.

POST /api/public/v1/integrations/{integration_id}/signing-secret​

Collect Signing Secret. Scope: integrations:register (the key that registered it). Guide: Self-service registration.

ParameterInTypeRequiredRules
integration_idpathstringyes

Success: 200.

Keys​

GET /api/public/v1/ping​

Ping. Scope: activities:read.

Success: 200.

Sessions​

GET /api/public/v1/sessions​

List Sessions. Scope: sessions:read. Guide: REST API: starting and driving a session.

ParameterInTypeRequiredRules
activity_idquerystring (optional)no
statequerydraft, lobby, running, paused, closed (optional)no
limitqueryintegernomin 1, max 100, default 50
offsetqueryintegernomin 0, default 0

Success: 200.

POST /api/public/v1/sessions​

Create Session. Scope: sessions:write. Guide: REST API: starting and driving a session.

Request body:

FieldTypeRequiredRules
activity_idstringyes
titlestringnomax length 300, default ``
modelive, self_pacednodefault live

Success: 201.

GET /api/public/v1/sessions/{session_id}​

Get Session. Scope: sessions:read.

ParameterInTypeRequiredRules
session_idpathstringyes

Success: 200.

GET /api/public/v1/sessions/{session_id}/export​

Export Session. Scope: results:read. Guide: Results and export.

ParameterInTypeRequiredRules
session_idpathstringyes
shapequerystringnopattern ^(wide|long)$, default wide
formatquerystringnopattern ^(csv|xlsx)$, default csv

Success: 200.

GET /api/public/v1/sessions/{session_id}/overview​

Session Overview. Scope: results:read. Guide: REST API: results and exports.

ParameterInTypeRequiredRules
session_idpathstringyes

Success: 200.

GET /api/public/v1/sessions/{session_id}/results​

Session Results. Scope: results:read. Guide: REST API: results and exports.

ParameterInTypeRequiredRules
session_idpathstringyes

Success: 200.

POST /api/public/v1/sessions/{session_id}/transition​

Transition. Scope: sessions:write. Guide: REST API: starting and driving a session.

ParameterInTypeRequiredRules
session_idpathstringyes

Request body:

A JSON object. See the guide linked above for its fields.

Success: 200.