Getting started

You can use the Riddle Builder API to create and edit 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

Tip: The same build configuration can also be applied on top of Riddles generated by the AI, so you can let the AI write the content while you stay in control of the result pages, design and publish settings. Click here to learn more.

Request format

Every request to the build endpoint has two levels:

1. the root of the payload - which Riddle type to build and how to handle the build itself
2. the build object inside it - the content, design and settings of the Riddle

{
    "type": "Quiz",         // <- root: what to build & how
    "project": 123,
    "publish": true,
    "build": {              // <- the Riddle itself
        "title": "...",
        "blocks": [],
        "results": []
    }
}

1. Root properties

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

2. The build configuration

The build object holds the Riddle itself. Not all properties are available for every Riddle type.

On top of those, each Riddle type accepts a few type specific properties (e.g. personalities and attributes for a personality test). They are documented on the page of each Riddle type.

Note: An unsupported property is ignored by default, so a typo like titel instead of title builds successfully and does nothing. Set strictProperties to true to have it rejected with a 400 instead. When editing an existing Riddle it always is, and that cannot be turned off.

Note: Do not confuse the two publish properties: publish in the root is a boolean that publishes the Riddle after building it, while publish inside build is the object holding the publish settings. They can be combined.

Example: Build a poll

A minimal poll: one question with two answers, and a result page.

{
    "type": "Poll",
    "project": 123,
    "build": {
        "title": "Favorite color poll",
        "blocks": [
            {
                "title": "What's your favorite color?",
                "type": "SingleChoice",
                "items": [
                    { "title": "green" },
                    { "title": "red" }
                ]
            }
        ],
        "result": {
            "title": "Thank you",
            "description": "Thanks for your vote."
        }
    }
}

Every block, settings object and result page on the following pages plugs into this same payload. What changes from Riddle to Riddle is what goes into blocks, not the structure around it.

Limits

The Riddle Builder API applies the following limits to every build:

FAQ

Q: Can I access this API?

A: The Builder API is part of the Business and Enterprise subscription plans.

Q: How do I access this API?

A: With an API key, the same way as every other Riddle endpoint - see the API getting started guide.

Q: Where can I find the builder endpoint?

A: In the API reference.

Q: Which Riddle types are currently supported?

A: All of them: poll, quiz, personality test, form, predictor, leaderboard, minigame, story and placeholder.

Q: What happens if I send a property that does not exist?

A: In a POST /riddle-builder build it is ignored, so a typo like titel instead of title builds successfully and does nothing. Set the root property strictProperties to true to get a 400 instead, naming the offending key and listing the properties that are supported in its place. On an edit unknown properties are always rejected.

Q: Can I change a Riddle after it was built?

A: Yes, with PUT /riddle-builder/{UUID}, which applies the same build configuration as a merge - only what you send changes. It also works for Riddles the Riddle AI generated. See editing Riddles.

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

A: Yes, with "publish": true in the root of the payload. See publishing the built Riddle.

Q: Are there any limits?

A: Yes, on blocks, items, media URLs, logic and batch size - see the limits table above.

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

A: Yes, with the Ad block, in every Riddle type.

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

A: Yes, if the Riddle is built in a project. Either let it use the project's default preset, or name the preset and palette yourself with the preset property. Both are covered in the preset settings.

Next steps

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

• Build a quiz, poll, personality test, form, predictor, minigame, story or placeholder
• Learn the item format every collection uses: an array of objects
• Configure the design, the publish settings and the flow/logic of your Riddle
• Handle the errors a build can answer with
• Read an existing Riddle back or edit it with the same build configuration