Getting started

You can use the Riddle Generative AI API to generate Riddles, populated with content from generative AI models.

Not familiar with the API yet? Read the Getting started guide first to learn about authentication and the response format.

Providing context

Generally there are two approaches you can take for providing context / content:

  1. Topic: Supply a topic or theme for the Riddle, e.g. 'Soccer', 'Harry Potter'
  2. URL: Provide a URL to a website, blog or article that contains the content you want to use for the Riddle. You can also provide multiple URLs in a single request – the AI combines the content of all pages into one Riddle (currently available for quizzes via the /riddle-ai/url/quiz/bulk endpoint).

Asynchronous generation

The Riddle AI generation happens asynchronously, meaning the Riddle will be generated in the background and the Riddle will not be visible in the Creator / on the landing page yet.

The API only returns a UUID and the requested Riddle type:

{
    "UUID": "as12Dcs",
    "type": "Quiz"
}

Tip: You can save this UUID to your database, for example to later call the API to analyse the Riddle's stats or leads.

Knowing when the Riddle is ready

As the Riddle is generated in the background, you need a way to find out when it is actually finished. There are two ways to do that – pick the one that fits your integration:

ApproachHow it worksUse it when
Status endpointYou ask the API for the state of the generation and check again until it is finishedYour code runs as a long-running process (a script, a job, a CLI command) that can keep checking before it continues
Callback URLYou pass a callbackUrl and we send a webhook with the finished Riddle to your serverYour code cannot wait – e.g. a web request that has to return immediately – and you can receive incoming HTTP requests

Status endpoint

Call /riddle-ai/status/{UUID} with the UUID you received from the creation endpoint:

GET https://www.riddle.com/creator/api/v3/riddle-ai/status/as12Dcs

The response tells you where the generation stands:

{
    "UUID": "as12Dcs",
    "type": "Quiz",
    "title": "Formula 1",
    "status": "completed",
    "isFinished": true,
    "error": null,
    "retryAfterSeconds": null
}
PropertyTypeDescription
UUIDstringThe UUID of the generated Riddle
typestringThe Riddle type, e.g. Quiz
titlestring|nullThe title of the Riddle. While the generation is still pending this is an internal placeholder – only rely on it once the status is completed
statusstringpending, completed or failed; see below
isFinishedbooleanfalse while the generation is still running, true once it either completed or failed
errorstring|nullWhy the generation failed; null unless status is failed
retryAfterSecondsinteger|nullHow many seconds to wait before asking for the status again; null once the generation is finished

The three states are:

  • pending: the Riddle is still being generated. It exists, but it has no content yet – do not fetch, update or publish it.
  • completed: everything is done. The content was generated, the build configuration was applied and the Riddle was published, if you asked for it. Only now the Riddle is ready to be used and embedded.
  • failed: the generation did not succeed and error tells you why.

How often to check

The endpoint always answers immediately, so you have to ask again while the generation is still running. Every pending response tells you how long to wait before doing so via retryAfterSeconds:

{
    "UUID": "as12Dcs",
    "type": "Quiz",
    "title": "Riddle Builder",
    "status": "pending",
    "isFinished": false,
    "error": null,
    "retryAfterSeconds": 5
}

A generation usually takes 20 – 60 seconds; generations based on one or more URLs take longer, as the given pages have to be scraped first. So expect to check several times:

# check the status until the generation is finished
while true; do
    STATUS=$(curl --silent --location \
        --request GET 'https://www.riddle.com/creator/api/v3/riddle-ai/status/as12Dcs' \
        --header 'Authorization: Bearer [your API key]')

    echo "$STATUS" | grep -q '"isFinished":true' && break

    sleep 5 # the seconds returned in retryAfterSeconds
done

Important: Always respect retryAfterSeconds and do not poll in a tight loop. If you cannot check periodically at all, use a callbackUrl instead of hammering this endpoint.

Errors

The status endpoint returns a 400 error if the Riddle exists but was not created by the Riddle AI, as there is no generation to report on:

{
    "success": false,
    "code": 400,
    "error": "BAD_REQUEST",
    "message": "Riddle as12Dcs was not created by the Riddle AI."
}

A UUID that does not exist – or that your API key cannot access – results in the usual 404 / 403 errors.

API limits and usage

The generative AI API has strict limits per month, differentiated for each plan:

  • Pro: 150 calls/month
  • Business: 250 calls/month
  • Enterprise: 550 calls/month

This is the same monthly allowance as Riddles generated in the Creator. Calls made through the API and Riddles created in the Creator draw on one shared total.

Fetch current usage

You can check your current usage dynamically by calling the AI usage endpoint. This will return a JSON object with the current usage and limits:

{
    "current": 5,
    "max": 150
}

Note: The returned usage may be multiplied by 12 if your subscription is billed annually. For example, if you are on the Pro plan, the usage will be 150 * 12 = 1800.

Next steps

Table of Contents