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, only SingleChoice and MultipleChoice 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
        }
    ]
}
}
Table of Contents