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
  • Get stats for a riddle for a given time range
  • Build simple Riddles via the API
  • Get analytics about Riddles / entire accounts/projects
  • ...

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.

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.
  • Builder API: Use the Riddle Builder API to create Riddles dynamically via API.
  • Stats API: Use the Riddle Stats API to retrieve stats for any of your Riddles, projects or for your personal project.
  • 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