Stagecast Quiz API

Some support for quizzes when developing and managing moments

Quiz management

get
List quizzes for an event

https://stagecast.se/api/events/:eventId/quizzes/
Retrieve the quizzes available in event identified by eventId
Request
Response
Request
Path Parameters
eventId
required
string
The eventId: A UUID that you can find in the address bar of your browser when you navigate to the event in the Stagecast web console
Headers
X-Token
required
string
The auth token as retrieved when logging in. In order to list quizzes you also need to be part of the "crew" group of the event
Query Parameters
limit
optional
integer
limit parameter defines how many quizzes to return at most (default: 10)
offset
optional
integer
offset parameter defines where the listing should start (default: 0) when listing quizzes
Response
200: OK
[{"_id": "abc123", "title":"...", ...}...]

post
Create a quiz for an event

https://stagecast.se/api/events/:eventId/quizzes/
Create a new quiz object associate to an event
Request
Response
Request
Path Parameters
eventId
required
string
The eventId: A UUID that you can find in the address bar of your browser when you navigate to the event in the Stagecast web console
Headers
X-Token
optional
string
The auth token as retrieved when logging in. In order to create quizzes you also need to be part of the "crew" group of the event
Body Parameters
title
optional
string
The body is a json document with an optional field "title" where you can write some descriptive title for the quiz
Response
201: Created
{
"id": "abc-223-23c-cac",
"event": "dsadas-asdas-d-asdas",
"title": "My cool quiz",
"questionCount": 0
}

put
Update a quiz in an event

https://stagecast.se/api/events/:eventId/quizzes/:quizId
Updates the information in the quiz, such as title and description
Request
Response
Request
Headers
X-Token
required
string
The auth token as retrieved when logging in. In order to update quizzes you also need to be part of the "crew" group of the event
Body Parameters
title
optional
string
The body is a json document with optional fields. "title" is one such field
Response
200: OK

post
Add questions to a quiz

https://stagecast.se/api/events/:eventId/quizzes/:quizId/questions
Post questions to be added to the quiz. You post an array of question objects where each question object includes a question field, a choices field and a correctAnswers field
Request
Response
Request
Path Parameters
quizId
required
string
The quizId - as returned in the requests above
eventId
required
string
The eventId - see above
Headers
X-Token
optional
string
The auth token as retrieved when logging in. In order to add questions to a quiz you also need to be a member of the crew group of the event
Body Parameters
group
optional
string
The group the questions belongs to. Useful for grouping questions by topics.
correctAnswers
required
array
correctAnswers is an array of numbers indicating which of the choices are correct (starting with index 1)
choices
required
array
choices field is an array of choices which are documents with fields "type" and "value", where "type" is either "text" or "image" and "value" is either a string or a url.
question
required
object
question field is an object with fields "type" and "value", where "type" is either "text", "image" or "video" and value is either a string (in the "text" case or a url)
Response
201: Created
Returns the updated quiz object where the questionCount field has been updated with the number of questions you uploaded
{
"id": "abc-223-23c-cac",
"event": "dsadas-asdas-d-asdas",
"title": "My cool quiz",
"questionCount": 12
}
JavaScript
JavaScript
const questions = [
{
group: "work",
question: {"text": "Which is your favourite company?", "image": "https://dn.se/img.jpg"},
choices: [{"text", "Stagecast"}, {"video":"https://dn.se/video.mov"}],
correctAnswers: [1, 2]
},
]
fetch('https://stagecast.se/api/events/abc-123/quizzes/def-456/', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Token': 'asdasdasd...',
},
body: JSON.stringify(questions),
})
.then((response) => response.json())
.then((data) => {
console.log('Success:', data);
})
.catch((error) => {
console.error('Error:', error);
});

get
List questions for a quiz

https://stagecast.se/api/events/:eventId/quizzes/:quizId/questions
Retrieve the questions
Request
Response
Request
Path Parameters
eventId
required
string
The eventId: A UUID that you can find in the address bar of your browser when you navigate to the event in the Stagecast web console
quizId
required
string
The quizId: A UUID that you can find in the address bar of your browser when you navigate to the event in the Stagecast web console
Headers
X-Token
required
string
The auth token as retrieved when logging in. In order to list quizzes you also need to be part of the "crew" group of the event
Query Parameters
limit
optional
integer
limit parameter defines how many questions to return at most (default: 10)
offset
optional
integer
offset parameter defines where the listing should start (default: 0) when listing questions
Response
200: OK
[{"_id": "abc123", "title":"...", ...}...]

put
Update question

https://stagecast.se/api/events/:eventId/quizzes/:quizId/questions/:questionNumber
Update a question. The request takes a question body (see add questions above) that will replace the existing body.
Request
Response
Request
Path Parameters
questionNumber
required
string
The question number
quizId
required
string
The quiz identifier
eventId
required
string
The event identifier
Response
200: OK

delete
Delete question

https://stagecast.se/api/events/:eventId/quizzes/:quizId/questions/:questionNumber
Deletes a question. As a side effect it will also shift down all question indexes where the question index is greater than questionNumber
Request
Response
Request
Path Parameters
questionNumber
required
string
The question number
quizId
required
string
The quiz identifier
eventId
required
string
The event identifier
Response
200: OK

Participants API

get
Get a quiz (via CDN)

https://d5q8k8cx63nj4.cloudfront.net/api/quizzes/:quizId
Read information, such as quiz title, for a quiz
Request
Response
Request
Path Parameters
quizId
required
string
The identifier of the quiz as retrieved from the moment class object (configured in the Stagecast web console)
Response
200: OK
Returns the quiz information, such as title and number of questions in the quiz
{
"id": "abc123",
"title": "Quiz Title",
"event": "abc123",
"seriesDuration": 180000,
"questionDuration": 20000,
"questionCount": 5,
"prizesPerSeries": 1,
"repeat": true,
"questionsPerRound": 3,
"maxRoundsPerSeries": 200,
"seriesPlayed": 328
}

get
Get quiz runtime info

https://stagecast.se/api/quizzes/:quizId/moments/:momentId/info
Read runtime info of a quiz
Request
Response
Request
Path Parameters
momentId
required
string
The moment identifier
quizId
required
string
The quiz identifier
Response
200: OK
{"momentId":"abc-123","totalRoundsStarted":47}

put
Update user profile

https://stagecast.se/api/quizzes/:quizId/moments/:momentId/profile
Stores participant information, such as name, in the participants profile in the quiz in a particular moment.
Request
Response
Request
Path Parameters
momentId
required
string
The moment identifier, as retrieved from the moment runtime configuration
quizId
required
string
The quiz identifier, as retrieved from the moment class object
Headers
X-Token
required
string
The auth token as retrieved in the moment runtime configuration
Response
200: OK
{
"userId": "[email protected]",
"name": "User#9265",
"points": 0,
"bestScore": 0,
"momentId": "9FF7106A-ACB5-4296-8EEB-D40CC4965807",
"prizes": [...prizeRef],
"questionsAnswered": 0,
"roundsPlayed": 0,
"totalRoundsPlayed": 5,
"totalQuestionsAnswered": 0
}

get
Get the user profile

https://stagecast.se/api/quizzes/:quizId/moments/:momentId/profile
Fetch the profile document of the authenticated user
Request
Response
Request
Path Parameters
momentId
required
string
The moment identifier, as retrieved from the moment runtime configuration
quizId
required
string
The quiz identifier, as retrieved from the moment class object
Headers
X-Token
required
string
The auth token as retrieved in the moment runtime configuration
Response
200: OK
{
"userId": "[email protected]",
"name": "User#9265",
"points": 0,
"bestScore": 0,
"momentId": "9FF7106A-ACB5-4296-8EEB-D40CC4965807",
"prizes": [...prizeRef],
"questionsAnswered": 0,
"roundsPlayed": 0,
"totalRoundsPlayed": 5,
"totalQuestionsAnswered": 0
}

get
Fetch question to answer

https://stagecast.se/api/quizzes/:quizId/moments/:momentId/questions/:questionNumber
Retrieves a question from the quiz
Request
Response
Request
Path Parameters
questionNumber
required
string
The number of the question to be retrieved
momentId
required
string
The moment identifier, as retrieved from the moment runtime configuration
quizId
required
string
The identifier of the quiz, as retrieved from the moment class object
Headers
X-Token
required
string
The auth token as retrieved in the moment runtime configuration
Response
200: OK
A question contains a hash (used when later answering the question), the question itself and the available answer choices.
{
"hash": "feg123",
"group": "question group",
"question": {""text"|"image"|"video": "value"},
"choices": [{"text"|"image"|"video": "value"}, ...]
}

put
Answer a question

https://stagecast.se/api/quizzes/:quizId/moments/:momentId/questions/:questionNumber/answer
A participant answers a question previously retrieved by putting the answer while providing the
Request
Response
Request
Path Parameters
questionNumber
required
integer
The number of the question you are answering
momentId
required
string
The moment identifier, as retrieved from the moment runtime configuration
quizId
required
string
The quiz identifier, as retrieved from the moment class object
Headers
X-Token
required
string
The auth token, as retrieved from the moment runtime configuration
Body Parameters
hash
required
string
The hash retrieved when previously fetching the question
answer
required
integer
The answer the user has selected
Response
200: OK
When the user submits its answer the correctAnswers will be returned as well as the points retrieved for this question (questionPoints) as well as the total number of points (totalPoints) retrieved in the quiz. The total points are the difference between the question fetch timestamp and the answer response timestamp.
{
"correctAnswers": [1, 2],
"questionPoints":1234,
"totalPoints":1234340
}

put
Play new round

https://stagecast.se/api/quizzes/:quizId/moments/:momentId/playNewRound
User asks to play a new round. If successful (if user has not yet played all rounds), the user's score will be reset and "currentRound" and "totalRoundsPlayed" will be increased.
Request
Response
Request
Path Parameters
momentId
required
string
The moment identifier
quizId
required
string
The quiz identifier
Headers
X-Token
required
string
The authentication token
Response
200: OK
The user profile object

This call should be made before a round is to be played. It will reset the user's score, it will increment the user's "currentRound" (initial value is zero) and "totalRoundsPlayed" (initial value is zero) by one. This means that "totalRoundsPlayed" will be slightly ahead of time. If it had been called "totalRoundsStarted" it would be more correct but the name is kept for backwards compatibility.

get
Fetch top results for quiz in the current moment (via CDN)

https://d5q8k8cx63nj4.cloudfront.net/api/quizzes/:quizId/moments/:momentId/results
Fetches the current leaderboard in the quiz
Request
Response
Request
Path Parameters
momentId
required
string
The moment identifier as retrieved from the moment runtime configuration
quizId
required
string
The quiz identifier as retrieved from the moment class object
Query Parameters
series
optional
integer
The default is to give you the latest results - from the current series, but if you want historical data from any previous series you can specify the series with an integer parameter. The number is in the interval 1 to n, where n is the number of series played. The returned results will always be the top ten, so using limit and offset together with the series parameter has no effect.
limit
optional
integer
How many results to retrieve (default: 10)
offset
optional
integer
How many results from the top to skip (default: 0)
Response
200: OK
Returns a leaderboard with user profiles and their current total points
{
"leaderboard":[{"position":1, "name":"Stefan", "points": 12344, ...}, {"position":2,"name":"Filippo", "points": 12200, ..\
.}, ... N],
"totalParticipants": 29
}

get
Fetch your own results

https://stagecast.se/api/quizzes/:quizId/moments/:momentId/results/myown
A user fetches its own results
Request
Response
Request
Path Parameters
momentId
required
string
The moment identifier
quizId
required
string
The quiz identifier
Headers
X-Token
required
string
The auth token as retrieved from the moment context
Response
200: OK
{"name":"Stefan", "points": 12344, "position":39}

If you run this request together with GET top results, check that the user position is consistent with the top scorer positions. In fact, the user own position is not cached, while the top scores are.