Batch and asynchronous processing

In some cases where lots of Riddles are needed, it may be more efficient to build them in batches. This drastically reduces the overhead of each HTTP request and allows for faster processing.

Additionally, single Riddles can also be built asynchronously - this makes migrating to an asynchronous flow much easier with your existing code and processes.

Building in batches

A batch is a collection of Riddle builds, sent in one payload to the builder API.

Example

For example if I want to create a quiz and poll with one request, only one request to the builder batch API endpoint is needed with the batch property set to an array of build configurations:

{
    "batch": [
        {
            "type": "Quiz",
            "build": {
                "title": "My new quiz",
                "blocks": [
                    {
                        "title": "What is the capital of France?",
                        "type": "SingleChoice",
                        "items": [
                            { "title": "Berlin", "isCorrect": false },
                            { "title": "Madrid", "isCorrect": false },
                            { "title": "Paris", "isCorrect": true }
                        ]
                    }
                ]
            }
        },
        {
            "type": "Poll",
            "build": {
                "title": "My new poll",
                "blocks": [
                    {
                        "title": "What is your favorite color?",
                        "type": "SingleChoice",
                        "items": [
                            { "title": "Red" },
                            { "title": "Green" },
                            { "title": "Blue" }
                        ]
                    }
                ]
            }
        }
    ]
}

Every item of batch needs the same two properties the single build endpoint takes:

On top of the array itself, the following properties are read once per request and applied to every Riddle of the batch:

Note: publish and project are batch-wide - they are read from the top level of the payload, not from the individual items. Setting publish inside a single batch item has no effect. strictProperties is the one property that works on both levels: the batch-wide value is the default, and an item that carries its own strictProperties uses that instead.

Note: A batch is built in the background, so a property rejected because of strictProperties cannot be answered with a 400 - the affected Riddle stays empty instead (see Checking the result of an asynchronous build). Send one build synchronously with strictProperties: true while you develop the configuration: there the offending key is named in the response.

Note: projectId is still accepted as a legacy alias for project.

Important factors to consider when using batches

• The batch size is limited to 100 Riddles per request; an empty batch array is rejected.
• Building in batches requires a Business or Enterprise plan, just like the single build endpoint.
• The Riddles are created asynchronously and the response will contain a list of Riddles which are only initialized, i.e. not visible yet in the Creator.
• The response contains one entry per batch item, in the same order as it was sent:

{
    "success": true,
    "data": {
        "count": 2,
        "items": [
            {
                "UUID": "abcdef12",
                "title": "My new quiz",
                "type": "Quiz"
            },
            {
                "UUID": "34567890",
                "title": "My new poll",
                "type": "Poll"
            }
        ]
    }
}

The title is taken from the title of the build configuration, so the entries can be matched to what you sent even before the builds have finished.

Building single Riddles asynchronously

Building asynchronously means that a single Riddle build is processed in the background and the response will contain a UUID for the Riddle which is only initialized, i.e. not visible yet in the Creator.

Example

To mark the build as asynchronous, the queue property must be set to true in the request. The request would look like this:

{
    "type": "Quiz",
    "queue": true,
    "build": {
        "title": "My new quiz",
        "blocks": [
            {
                "title": "What is the capital of France?",
                "type": "SingleChoice",
                "items": [
                    { "title": "Berlin", "isCorrect": false },
                    { "title": "Madrid", "isCorrect": false },
                    { "title": "Paris", "isCorrect": true }
                ]
            }
        ]
    }
}

The response is a regular Riddle response, but for the initialized Riddle: it already has its UUID, its type and - if you sent one - its title, while its data is still empty. Everything else in build is applied a moment later, in the background.

publish, project and strictProperties work exactly as they do for a synchronous build; publish: true publishes the Riddle once the background build has finished. strictProperties: true is still enforced - but in the background, so the rejected key cannot be reported back to you and the Riddle stays empty instead.

Checking the result of an asynchronous build

Queued builds - both queue: true and every item of a batch - are processed after the response was sent, so build errors cannot be returned to you. There is no status field to poll either. Instead:

• Fetch the Riddle by its UUID once, e.g. via the Riddle endpoint. A Riddle that is still empty either has not been processed yet or its build configuration was rejected.
• Because of that, we recommend building one Riddle synchronously (without queue) while you develop your build configuration: a synchronous build validates the whole configuration and answers with a precise error message. Once the payload is known to be valid, switch to queue: true or the batch endpoint for the bulk work.
• Or check the payload up front: POST /riddle-builder/validate dry-runs up to 20 build configurations - the batch items themselves - and reports per item whether it would be accepted and why not, without creating a single Riddle.