Item formats
Most blocks hold a collection of smaller entries: a question's items, a form's fields, a TierList's tiers, a personality test's personalities. All of these use the same format, so you only have to learn it once - the pages of the individual Riddle types and blocks then only tell you what is specific to that collection.
One format: an array of objects
A collection is an array of objects, and every entry carries its own properties as keys. The entry's text is its title:
"items": [
{ "title": "Spaghetti" },
{ "title": "Fusilli" }
]
That is the whole rule. Beyond title and its own id, an entry only accepts the properties of the collection it sits in - there is no set of keys that every entry shares. A Quiz answer has an isCorrect flag, a form field a type, a personality answer its scores:
"items": [
{ "title": "Rome", "isCorrect": true },
{ "title": "Madrid", "isCorrect": false }
]
"fields": [
{ "title": "Your email", "type": "Email" },
{ "title": "Your name", "type": "Name" }
]
"items": [
{ "title": "I plan every detail", "scores": [3, 0] },
{ "title": "I improvise", "scores": [0, 3] }
]
Which properties those are is listed on the page of the Riddle type or block that owns the collection. A property that is not on that list is rejected, and the error names what the collection does accept:
Matrix scale[0]: "description" is not a supported property of this block. Supported here: title.
A description and a media of its own, for example, exist only on the answers of a choice question and on the entries of a few Poll blocks - not on a Matrix rating, a TierList tier or a Predictor team.
Giving an entry its own id
Every entry of a collection gets an id - auto-generated and counting up from 1 if you do not send one:
"items": [
{ "id": 201, "title": "Spaghetti" },
{ "id": 202, "title": "Fusilli" }
]
An item ID has to be a positive integer and only has to be unique within its own block. Assigning them yourself pays off in three places: logic settings can reference an answer by ID instead of by its exact text, stats and webhook data become stable when a wording changes, and an edit can address the entry. See custom IDs for the full rules.
Editing a collection
When you edit an existing Riddle, the entries of these collections are merged by their id: an entry you do not mention stays as it is, and an entry you send by id is updated with the properties you send.
{
"id": 3,
"items": [
{ "id": 2, "title": "Bonn" }
]
}
An entry without an id is not addressing anything, so an edit rejects it - add "$create": true to send it as a new entry instead:
{
"id": 3,
"items": [
{ "$create": true, "title": "Cologne" }
]
}
The one collection with keys: a Matrix scale
A Likert/matrix question stores the value a rating stands for, and that value is the key of the entry:
"scale": {
"0": { "title": "Bad" },
"2": { "title": "Medium" },
"4": { "title": "Good" }
}
The entries themselves are objects like everywhere else. Send scale as a plain array to get the default values - the index of the entry, counting from 0.
Older configurations: the bare-value shorthand
The object entry above is the only item format the Builder API documentation describes. Older configurations, written when a collection also accepted a bare value in place of an object, may still look different, and what such a value meant depended on the collection it was in:
| What an old configuration may hold | What it means | The same thing as an object |
|---|---|---|
"items": ["Spaghetti", "Fusilli"] | Each value is one entry's title | "items": [{ "title": "Spaghetti" }, { "title": "Fusilli" }] |
"items": {"Rome": true} | The key is the title, the value the isCorrect flag | "items": [{ "title": "Rome", "isCorrect": true }] |
"fields": {"Your email": "Email"} | The key is the field label, the value the field type | "fields": [{ "title": "Your email", "type": "Email" }] |
Those configurations keep working on POST /riddle-builder for backwards compatibility, but the shorthand is no longer documented, and it is rejected wherever strict property validation applies: when you edit a Riddle, when you build through the MCP server, and on a create build sent with strictProperties:
SingleChoice: Invalid item at key "Madrid": expected an object with the item's properties as keys, e.g. {"title":"Madrid","isCorrect":false}. A bare bool is not accepted here - only an object can carry an "id", which is what addressing a single item takes.
There is nothing a bare value can express that an object cannot, so move any configuration that still sends one over to the object entry: the text goes into title, every other value into a key of its own.