Riddle Builder API
Now, building Riddles via API is supported. This opens up a lot of possibilities, such as:
- building Riddles dynamically based on user input
- building Riddles based on data from your database or other sources
- building daily Riddles for contests or promotions
How to access
To learn how to access the Riddle API please refer to the API documentation.
The Riddle Builder API and its endpoint have their own subpage which can be found here.
Payload
You specify the Riddle's structure with a build configuration which is an object.
Poll Example
{
"type": "Poll",
"build": {
"title": "Favorite color poll",
"blocks": [{
"title": "What's your favorite color?",
"type": "SingleChoice",
"items": [
"green",
"red"
]
}],
"result": {
"title": "Thank you",
"description": "Thanks for your vote."
}
}
}
Quiz Example
{
"type": "Quiz",
"build": {
"title": "Germany quiz",
"blocks": [{
"title": "What's the capital of Germany?",
"type": "SingleChoice",
"items": {
"Berlin": true,
"Lissabon": false,
"Leipzig": false
}
}],
"results": [{
"title": "Not so good",
"description": "There's room for improvement",
"minPercentage": 0,
"minPercentage": 50
},
{
"title": "Well done!",
"description": "You're a winner",
"minPercentage": 51,
"minPercentage": 100
}
]
}
}
Specifying Riddle type
The type
property specifies the Riddle type. Currently, only Poll
and Quiz
are supported.
Adding questions
You can add questions to your Riddle by adding blocks to the build.blocks
array. Each block has a title
, type
& items
property:
- The
title
property specifies the question title. - The
type
property specifies the question type.
Currently, onlySingleChoice
andMultipleChoice
are supported. - The
items
property specifies the question's answer items. We'll discuss this in more detail in the next section.
Specifying answer items
For each question you can specify multiple answer items. You do this by adding the items
array. The structure of this array depends on the Riddle type.
In the case of a Riddle, you can specify the answer items green
& red
as a simple list:
{
"type": "Poll",
"build: {
...
"blocks": [
...
{
"title": "What's your favorite color?",
"type": "SingleChoice",
"items": ["green", "red"]
}
]
}
}
No additional data is required, unlike with the Quiz type where you have to specify whether an answer item is correct or not:
{
...
"build: {
...
"blocks": [
{
"title": "What's the capital of Germany?",
"type": "SingleChoice",
"items": {
"Berlin": true,
"Lissabon": false,
"Leipzig": false
}
}
]
}
}
Please note that if you build a SingleChoice
question only one answer option can be correct, otherwise the API will return an error.
Setting the result
For Poll
only one result in build.result
is allowed:
{
...
"build": {
...
"result": {
"title": "Thank you",
"description": "Thanks for your vote."
}
}
}
When building a Quiz
you can add as many results to build.results
as you want as long as the minPercentage
& maxPercentage
attribute of each result don't overlap:
{
...
"build: {
...
"results": [
{
"title": "Not so good",
"description": "There's room for improvement",
"minPercentage": 0,
"minPercentage": 50
},
{
"title": "Well done!",
"description": "You're a winner",
"minPercentage": 51,
"minPercentage": 100
}
]
}
}