Getting started

Introduction

The Riddle API can be used to dynamically list, embed + analyze + create Riddle content.

Example API usages:

  • Get all Riddles by type / name / tag
  • Get embed code for a Riddle
  • Analyze and view stats for Riddles, projects, or your personal project in a given time range
  • Build Quizzes, Polls, Predictors, etc. via build configurations
  • Generate Riddles with AI based on topics or URLs

Specification

Looking for the API Endpoints?

You can find specification for all available API endpoints at https://riddle.com/help/api/docs.

Authentication

To access the API you need an API key. You can find or create new API keys on the API keys page in the Riddle creator. Once you have found or created an API key, you can use it to authenticate against the API.

Example Request:

URL: https://www.riddle.com/creator/api/v3/riddle/list
HTTP method: POST
Headers:
{
    Authorization: "Bearer [your API key]"
}

Example Request via CURL:

curl --location --request POST 'https://www.riddle.com/creator/api/v3/riddle/list' \
--header 'Authorization: Bearer [your API key]' \

Response format

In case no exception occurs and the API returns HTTP 200 the response will have the following format:

{
    "success": true,
    "code": 200,
    "data": "[response data]"
}

The type of data in the response can vary depending on the used endpoint. E.g. while the embed code endpoint returns a string (=> the actual embed code), the riddle list will return an array consisting of all riddles matching the given query.

Make sure to check out the API documentation to see example requests and responses for each endpoint.

Exception handling

In case an exception occurs the response will have a different structure:

{
    "success": false,
    "code": 400,
    "error": "BAD_REQUEST",
    "message": "Bad Request."
}

Let's go through each sent parameter:

  • code: The HTTP response code; Check out https://http.cat to explore various codes.
  • error: An unique error code which is easier to work with when working with this API programmatically.
  • message: An error message which includes more information why what happened. In some cases additional information is redacted to not expose any security-risking information. If that is the case and you want to know more please contact us in the support chat.

Validation errors

The API can also return validation errors to indicate you where a mistake has been made.

For example in the builder API you could mistakenly supply an integer for a quiz question title of type string - this results in a validation error and the structure of the returned response would look like this:

{
    "success": false,
    "code": 400,
    "error": "RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_VALIDATION",
    "message": "PredictorPickTheWinnerBlock: Block properties are invalid. See the validation errors for more details.",
    "validationErrors": [
        {
            "message": "Input is not a string.",
            "code": "NOT_STRING",
            "property": "title"
        }
    ],
}

Next steps

  • Look at the specification of all available API endpoints: Find out what you can do with the Riddle API.
  • Stats API: Use the Riddle Stats API to retrieve stats for any of your Riddles, projects, or for your personal project.
  • Builder API: Use the Riddle Builder API to create Riddles programmatically with defined build configurations.
  • Generative AI API: Use the Riddle Generative AI API to create Riddles programmatically based on topics and URLs.
  • Use the PHP Library: If you use PHP in your project you can use our PHP SDK to integrate the Riddle API. This has the advantage that you don't have to worry about authentication or other boiler plate code and can focus on building your Riddle integration.
Table of Contents