Deleting built Riddles

In contrast to Riddles which were created through our web interface, Riddles built via the Builder API can be deleted through the API.

To delete a Riddle, use the Riddle delete endpoint. The UUID of the Riddle can be found in the response of the Riddle build endpoint.

Please be aware that deleting a Riddle is irreversible and will remove all data associated with the Riddle. This includes the Riddle itself, its results, and all data collected from participants.

Which Riddles can be deleted

Only programmatically created Riddles can be deleted with an API key:

  • Riddles built via the Riddle Builder API, including queued and batch builds,
  • Riddles created from a template with the MCP tool riddle_template_use, and
  • Riddles generated by the Riddle AI via an API key.

Everything else - most importantly Riddles created in the Creator - is rejected with:

Only Riddles created via the Builder API or generated by the Riddle AI can be deleted with an API key.

This makes the endpoint safe to use for cleaning up Riddles that were created for testing purposes: it can never delete the work of your team.

Deleting also requires the delete Riddle permission for the project the Riddle lives in.

The same rule gates editing and restyling

Deleting is not the only thing this rule decides. Exactly the same condition - reported as origin.apiManageable when you read a Riddle back - gates every write an API key or MCP client may perform on a whole Riddle:

  • deleting it,
  • editing it with a build configuration (PUT /riddle-builder/{UUID} / riddle_builder_update), and
  • restyling it (palette_customize).

Reading is never restricted: any Riddle can be read back as a build configuration, whoever created it.

Because a Riddle created with riddle_template_use counts as programmatically created, it can be edited, restyled and deleted afterwards just like one you built yourself - and it records where it came from: reading it back reports the template's Riddle under context.duplicated.

Response

On success the endpoint answers with the UUID it deleted:

{
    "success": true,
    "data": {
        "deletedUUID": "abcdef12"
    }
}
Table of Contents