Getting started

You can use the Riddle Builder API to create Riddles dynamically via API. This opens up a lot of possibilities, such as:

  • building Riddles dynamically based on user input
  • building Riddles based on data from a database, spreadsheet or from other sources
  • building daily Riddles for contests or promotions

Request format

With every request to the build endpoint you specify the Riddle type and a "build" configuration which defines the structure of the Riddle you want to create.

The build configuration, independent of the Riddle type, always consists of the following properties:

  • title: The title of the Riddle
  • blocks: An array of blocks that make up the Riddle (questions, forms, ...). The order in which you send the blocks is the exact order of the Riddle.
  • result/results: A single result (for Poll) or an array of results that can be shown to the user after they have completed the Riddle

Additionally to the build configuration you must always specify the type of the Riddle you want to build.

Note: If you use a personal project API key (= access to all of the projects in your account), you can also specify the projectId in the root to create the Riddle in a specific project. Click here to learn more.

Example: Build a poll

Now that we have covered the basics how the build configuration is built up, let's look at an example which is building a simple poll:

{
    "type": "Poll",
    "projectId": 123,
    "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."
        }
    }
}

Going through the example and its properties:

  • type: The Riddle type is set to Poll
  • build.title: The title of the Riddle is set to "Favorite color poll"
  • build.blocks: The Riddle consists of one block, a SingleChoice question with the title "What's your favorite color?" and two answer items "green" and "red"
  • build.result: The result that is shown to the user after they have completed the Riddle (only one Result is allowed for Poll!)

This build could be extended of course (e.g. with more questions, different types of questions or even form blocks). It is important to note that all builder blocks presented on the next pages follow the same principle as the properties described above, so you can build any Riddle type with the same structure and can dive deeper if required.

FAQ

Q: Can I access this API?

A: You can access the builder API if you are subscribed to our Business or Enterprise subscription plan.

Q: How do I access this API?

A: To learn how to access the Riddle API please refer to the Getting started guide.

Q: Where can I find the builder endpoint?

A: The builder API endpoint can be found here.

Q: Which Riddle types are currently supported?

A: The following Riddle types are currently supported:

  • Poll
  • Quiz
  • Form
  • Predictor

Not supported Riddle types:

Q: Can I publish the built Riddle right after building it?

A: Yes, this is possible. Read this section to learn more.

Q: Are there any limits to the number of blocks I can add to a Riddle?

A: Yes, the maximum number of blocks you can add to a Riddle is 20.

Q: Are there any other limits?

A: Yes:

  • form fields are limited to 10 per form
  • the maximum number of items in a single/multiple choice question is 10
  • the maximum used images in a Riddle build configuration is 10

Q: Can I use this API to create monetized Riddles?

A: Yes, this is possible. To do this you can use the Ad block. Read more about it here. The Riddle type you choose is irrelevant for this - make sure it is engaging enough for your audience though.

Q: Can I use this API to create Riddles with a specific design?

A: Yes, this is possible if the Riddle is built in a project. You have two options:

Next steps

Here are a few things you can do next - they are all covered in the following pages:

Table of Contents