Enriching AI Riddles with a build configuration

By default the generative AI API decides everything about the Riddle it creates – not only the questions and answers, but also the result pages, the design and the publish settings. With the optional build parameter you can take that control back: it accepts a Riddle Builder API configuration which is applied on top of the generated content.

Typical use cases:

• always applying your own project preset and palette, so every generated Riddle is on brand
• replacing the generated result pages with your own copy, calls to action or images
• enabling publish settings (showcase, double opt-in, tracking, data layer variables) right away
• connecting generated quizzes to a leaderboard

How it works

The build parameter is available on all AI creation endpoints (topic and URL based, for every supported Riddle type). Every property it accepts has exactly the same format as in the Riddle Builder API, so you can reuse everything you already know from the Build Riddles section – except for the content itself.

Add it next to the regular AI parameters:

{
    "topic": "Formula 1",
    "numQuestions": 5,
    "language": "en",
    "difficulty": "easy",
    "build": {
        "preset": {
            "preset": 805,
            "palette": "Zymx"
        },
        "publish": {
            "isShowcaseEnabled": true
        }
    }
}

Internally the steps happen in this order:

1. The AI generates the content (questions, answers, personalities, ...)
2. The default content around it (result pages, ...) is created and translated into the requested language
3. Your build configuration is applied on top of the generated Riddle
4. The Riddle is published, if publish was set to true

Because your configuration is applied after the translation, any text you send in the build object is used exactly as you sent it – it is never translated or rewritten by the AI.

What you can configure

Only the configuration around the content can be set – the content itself is generated by the AI. Which properties are available depends on the Riddle type you are generating:

Note: The publish property inside the build object holds the publish settings – it is not the same as the publish boolean in the root of the request, which controls whether the Riddle goes live immediately. You can use both together.

What you cannot configure

The content properties are rejected, as this is exactly what the AI generates for you:

Sending one of them fails the request immediately with a validation error – you do not have to wait for the asynchronous generation to find out:

{
    "success": false,
    "code": 400,
    "error": "RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_VALIDATION",
    "message": "QuizBuilder: Property \"blocks\" is not supported here - the content itself is generated and cannot be specified in the build configuration."
}

If you want to define the questions and answers yourself, use the Riddle Builder API instead – it builds a Riddle entirely from your configuration, without any AI involved.

Result pages

Result pages are the most common reason to use a build configuration, so it is worth knowing how they behave:

• Omit result/results and the result pages generated by the AI are kept as they are.
• Send result/results and the generated result pages are completely replaced by yours. This is a replacement, not a merge – so send all result pages you want the Riddle to have.

Example: Quiz with custom result pages

For a Quiz the result pages are wired into the Riddle logic via their score ranges. When you send your own results, that logic is rebuilt from your score ranges, so make sure the ranges you send cover 0 – 100% without gaps.

{
    "topic": "Formula 1",
    "numQuestions": 5,
    "language": "en",
    "difficulty": "easy",
    "publish": true,
    "build": {
        "results": [
            {
                "minPercentage": 0,
                "maxPercentage": 49,
                "title": "Rookie",
                "description": "Time to brush up on the basics!"
            },
            {
                "minPercentage": 50,
                "maxPercentage": 100,
                "title": "Champion",
                "description": "You know your stuff!"
            }
        ],
        "preset": {
            "preset": 805,
            "palette": "Zymx"
        },
        "publish": {
            "isShowcaseEnabled": true
        }
    }
}

Example: Poll with a single result page

A Poll (and a Personality test) only has one result page, so the property is called result instead of results:

{
    "topic": "Harry Potter",
    "numQuestions": 5,
    "language": "en",
    "build": {
        "title": "What the community thinks",
        "result": {
            "title": "Thanks for voting!",
            "description": "Check back tomorrow for a new poll."
        }
    }
}

Example: Quiz connected to a leaderboard

Leaderboard connections are set in build.leaderboard.connections, exactly as described in Create and connect to Leaderboard.

Important: A leaderboard needs a nickname (and usually an identifier) to rank participants. For built Riddles these are detected automatically from the Name and Email form fields – but an AI generated Riddle contains no form blocks, and you cannot add them via the build configuration because blocks are content. You therefore have to point nickname – and identifier, if the leaderboard requires email verification – to data layer variables instead:

{
    "url": "https://example.com/article",
    "numQuestions": 5,
    "language": "en",
    "difficulty": "medium",
    "publish": true,
    "build": {
        "publish": {
            "dataLayerItems": {
                "nickname": "Nickname",
                "email": "Email"
            }
        },
        "leaderboard": {
            "nickname": "dataLayer:nickname",
            "identifier": "dataLayer:email",
            "connections": ["Fw5uSygx"]
        }
    }
}

The data layer values are then passed in when the Riddle is embedded or opened, e.g. riddle.com/view/XXX?nickname=Ada&email=ada@example.com.

Error handling

There are two moments at which a build configuration can fail:

1. When you send the request. Content properties (blocks, personalities) are validated right away, so you get a 400 response immediately and no AI usage is consumed.
2. While the Riddle is generated. Everything else is validated when the configuration is applied, which happens asynchronously after the AI has returned its content. If it fails, all changes to the Riddle are reverted so it stays usable with the generated content, and the error is stored on the AI prompt.

The error format and the exception types are the same as for the Riddle Builder API – see Exception handling for the full list.

Tip: Build your configuration once with the Riddle Builder API before using it here. Its endpoint is synchronous, so you get validation errors instantly instead of having to wait for an AI generation to complete.

Next steps

• Build Riddles from scratch with the Builder API
• Result pages
• Preset settings
• Publish settings