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
| Method | Path | Scope |
|---|---|---|
GET | /activities | activities:read |
GET | /activities/{activity_id} | activities:read |
POST | /integrations | integrations:register |
GET | /integrations/{integration_id} | any key bound to the integration |
GET | /integrations/{integration_id}/outcomes | outcomes:read (bound to the integration) |
POST | /integrations/{integration_id}/signing-secret | integrations:register (the key that registered it) |
GET | /ping | activities:read |
GET | /sessions | sessions:read |
POST | /sessions | sessions:write |
GET | /sessions/{session_id} | sessions:read |
GET | /sessions/{session_id}/export | results:read |
GET | /sessions/{session_id}/overview | results:read |
GET | /sessions/{session_id}/results | results:read |
POST | /sessions/{session_id}/transition | sessions:write |
Paths are relative to {MURMLE}/api/public/v1.
Activities
GET /api/public/v1/activities
List Activities. Scope: activities:read.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
kind | query | poll, quiz, survey, qa (optional) | no | |
limit | query | integer | no | min 1, max 100, default 50 |
offset | query | integer | no | min 0, default 0 |
Success: 200.
GET /api/public/v1/activities/{activity_id}
Get Activity. Scope: activities:read.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
activity_id | path | string | yes |
Success: 200.
Integrations
POST /api/public/v1/integrations
Register Integration. Scope: integrations:register. Guide: Self-service registration.
Request body:
| Field | Type | Required | Rules |
|---|---|---|---|
name | string | yes | min length 1, max length 200 |
external_system | string | yes | min length 1, max length 64, pattern ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$ |
issuer | string | yes | min length 1, max length 500 |
jwks_uri | string | yes | min length 1, max length 500 |
webhook_url | string (optional) | no | max length 500 |
instructor_roles | array 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.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
integration_id | path | string | yes |
Success: 200.
GET /api/public/v1/integrations/{integration_id}/outcomes
Pull Outcomes. Scope: outcomes:read (bound to the integration). Guide: Pulling outcomes.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
integration_id | path | string | yes | |
after | query | string (optional) | no | max length 200 |
limit | query | integer | no | min 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.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
integration_id | path | string | yes |
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.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
activity_id | query | string (optional) | no | |
state | query | draft, lobby, running, paused, closed (optional) | no | |
limit | query | integer | no | min 1, max 100, default 50 |
offset | query | integer | no | min 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:
| Field | Type | Required | Rules |
|---|---|---|---|
activity_id | string | yes | |
title | string | no | max length 300, default `` |
mode | live, self_paced | no | default live |
Success: 201.
GET /api/public/v1/sessions/{session_id}
Get Session. Scope: sessions:read.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
session_id | path | string | yes |
Success: 200.
GET /api/public/v1/sessions/{session_id}/export
Export Session. Scope: results:read. Guide: Results and export.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
session_id | path | string | yes | |
shape | query | string | no | pattern ^(wide|long)$, default wide |
format | query | string | no | pattern ^(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.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
session_id | path | string | yes |
Success: 200.
GET /api/public/v1/sessions/{session_id}/results
Session Results. Scope: results:read. Guide: REST API: results and exports.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
session_id | path | string | yes |
Success: 200.
POST /api/public/v1/sessions/{session_id}/transition
Transition. Scope: sessions:write. Guide: REST API: starting and driving a session.
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
session_id | path | string | yes |
Request body:
A JSON object. See the guide linked above for its fields.
Success: 200.