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 12 Riddles per page.

You can use any combination of the following optional filters:

PropertyTypeDescription
projectintegerThe ID of the project you want to list the Riddles from; if not sent, the project of the API key is used
typestringOnly return Riddles of this type, e.g. Quiz or Poll; omit to get all types
notTypestringExclude Riddles of this type
tagsinteger[]An array of tag IDs the Riddles must be tagged with; learn more about tags
statusstringpublished, modified, or draft; omit to get all statuses
searchstringAny search term
originstringapi (built via the Builder API or generated by the Riddle AI) or manual (created by hand in the Creator); omit to get both. Any other value is rejected with Invalid filter origin: "<value>". Allowed: api, manual
sortBystringcreated, published, or modified. Any other value is rejected with Invalid sortBy: <value>. Allowed: created, modified, published
sortOrderstringASC or DESC. Any other value is rejected with Invalid sortOrder: <value>. Allowed: ASC, DESC
pageintegerThe page you want to fetch; if not sent, the first page is returned
pageSizeintegerHow many Riddles to return per page (default 12, maximum 300)

Example: Fetch the most recently published quizzes matching "onboarding":

{
    "type": "Quiz",
    "status": "published",
    "search": "onboarding",
    "sortBy": "published",
    "sortOrder": "DESC",
    "page": 1
}

Pagination

Next to data, the response contains a pagination object so you know whether you have to fetch more pages:

{
    "success": true,
    "data": ["... the Riddles of this page ..."],
    "pagination": {
        "page": 1,
        "pageSize": 12,
        "total": 137,
        "hasMore": true
    }
}

total is the number of Riddles matching your filters, not the total number of Riddles in the project, so you can page through a filtered list with hasMore.

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 and the same pagination object, except project.

Tip: Combine origin: "api" with the delete endpoint to find and clean up the Riddles your integration created.

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.

Both this endpoint and /riddle/list include a features object on each Riddle:

PropertyTypeDescriptionDefault
ctabooleanWhether the Riddle has a call-to-action button
formbooleanWhether the Riddle has a lead generation form
hasDependenciesbooleanWhether the Riddle depends on other Riddles, e.g. if this is a form embedded by other Riddles. Riddle-to-Riddle only - a Question Bank reference never sets this to true
hasEmbeddedRiddlesbooleanWhether the Riddle has other Riddles embedded in it, e.g. forms
hasQuestionBankDependenciesbooleanWhether the Riddle references at least one question bank
hasIntegrationbooleanWhether the Riddle is connected to at least one integration, e.g. MailChimp or Zapier; only present where it was resolvedfalse
connectedLeaderboardsobjectThe leaderboards this Riddle is connected to, each with uuid and title
connectedRiddlesobjectThe Riddles connected to this Riddle, e.g. quizzes embedding this form, each with uuid, type, and title

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

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 projects in a single response by default. If you have a lot of projects, add the query parameters page (1-indexed) and/or pageSize (default 50) to paginate instead - the response then also contains the same pagination object as the Riddle list:

GET /project/list?page=2&pageSize=25

Next steps

Table of Contents