Getting started
Besides building and generating Riddles, the API also covers the everyday management tasks: listing and searching your Riddles, reading a single Riddle, renaming, publishing and unpublishing, and retrieving the embed code or a QR code – for example to embed Riddles dynamically in your CMS.
Not familiar with the API yet? Read the Getting started guide first to learn about authentication and the response format.
List your Riddles
To get a list of the Riddles in a project, use the /riddle/list API endpoint. By default the project of the accessing API key is used; results are paginated with 10 Riddles per page.
You can use any combination of the following optional filters:
| Property | Type | Description |
|---|---|---|
project | integer | The ID of the project you want to list the Riddles from; if not sent, the project of the API key is used |
type | string | Only return Riddles of this type, e.g. Quiz or Poll; omit to get all types |
notType | string | Exclude Riddles of this type |
tags | integer[] | An array of tag IDs the Riddles must be tagged with; learn more about tags |
status | string | published, modified, or draft; omit to get all statuses |
search | string | Any search term |
sortBy | string | created, published, or modified |
sortOrder | string | ASC or DESC |
page | integer | The page you want to fetch; if not sent, the first page is returned |
Example: Fetch the most recently published quizzes matching "onboarding":
{
"type": "Quiz",
"status": "published",
"search": "onboarding",
"sortBy": "published",
"sortOrder": "DESC",
"page": 1
}
Tip: To list Riddles across your entire account (personal project plus all team projects), use the /riddle/account-list endpoint instead. It supports the same filters, except project.
Get a single Riddle
To retrieve a single Riddle, including its content, settings, and metadata, use the /riddle/{UUID} endpoint with the Riddle's UUID.
This is also useful to look up block and answer IDs, e.g. when working with the Stats API.
Rename a Riddle
To rename a Riddle, send the new title to the /riddle/rename/{UUID} endpoint:
{
"title": "My new Riddle title"
}
Publish or unpublish a Riddle
- /riddle/publish/{UUID} publishes a Riddle – it becomes available via its public URL and embed code.
- /riddle/unpublish/{UUID} takes a Riddle offline – the public URL is no longer reachable.
Both endpoints only require the Riddle UUID, no request body is needed.
Get the embed code
To retrieve the HTML embed code of a published Riddle, use the /riddle/embed-code/{UUID} endpoint. The data property of the response contains the embed code as a string, ready to be placed on your website.
Note: This endpoint also works with old Riddle 1.0 IDs.
Get a QR code
To generate a QR code for a published Riddle (e.g. for print material), use the /riddle/qr-code/{UUID} endpoint.
Delete a Riddle
Riddles built via the Builder API can be deleted via the Riddle delete endpoint. Deleting a Riddle created in the Creator is not possible via the API. Learn more
Projects
Two endpoints help you work with projects, e.g. to find the project IDs used across the API:
- /project/list returns all the projects the user is a member of.
- /project/{projectId} returns information about a single project.
Next steps
- Manage tags: Organize your Riddles with tags and use them as list filters.
- Fetch leads: Retrieve the leads collected by a Riddle.
- Look at the specification of all available API endpoints: Find out what you can do with the Riddle API.