Riddle API

https://www.riddle.com/help/api
Admin
Riddle API enables developers to dynamically create, manage, analyze, and embed interactive content...
Tokens:83,139
Snippets:576
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### Example API Request (POST)

Source: https://www.riddle.com/help/api/index

Demonstrates how to make a POST request to the Riddle API, including the URL, HTTP method, and necessary headers for authentication.

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

```

--------------------------------

### API Authentication Example (cURL)

Source: https://www.riddle.com/help/api/getting-started

Shows how to authenticate API requests using an API key with cURL.

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

--------------------------------

### Example API Request via CURL (POST)

Source: https://www.riddle.com/help/api/index

Shows how to execute a POST request to the Riddle API using the CURL command-line tool, including authentication via a Bearer token.

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

```

--------------------------------

### Riddle API Authentication and Example Request

Source: https://www.riddle.com/help/api/getting-started

This section details how to authenticate with the Riddle API using an API key and provides an example of a POST request to the riddle list endpoint.

```APIDOC
## Riddle API Authentication

To access the API, you need an API key. Find or create API keys on the API keys page in the Riddle creator.

### Authentication Method

Use the `Authorization` header with a Bearer token.

```
Headers:
{
    "Authorization": "Bearer [your API key]"
}
```

### Example Request (POST /creator/api/v3/riddle/list)

This example demonstrates how to list riddles using a POST request.

#### Method
POST

#### Endpoint
`https://www.riddle.com/creator/api/v3/riddle/list`

#### Headers
- **Authorization** (string) - Required - Your API key in Bearer token format.

#### Request Example (cURL)

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

--------------------------------

### Riddle API Rate Limiting

Source: https://www.riddle.com/help/api/getting-started

Information about the API's rate limits and how exceeding them is handled.

```APIDOC
## Rate Limiting

The Riddle API has default rate limits: 100 requests per minute and 2000 requests per hour.

*   **Scope**: This is a shared rate limit across all API keys within your Riddle account.
*   **Exceeding Limits**: If you exceed the rate limit, you will receive HTTP 429 responses until the limit window resets.

### Example Rate Limit Exceeded Response (HTTP 429)

```json
{
    "success": false,
    "code": 429,
    "error": "API_RATE_LIMIT_EXCEEDED",
    "message": "Minutely API rate limit of 100 requests exceeded"
}
```

*   **Contact Support**: If you require higher rate limits, please contact Riddle support.
```

--------------------------------

### Riddle Content Structure Example

Source: https://www.riddle.com/help/api/build-riddles/advanced-features/use-media

An example of the expected structure for riddle content, including media.

```APIDOC
## Riddle Content Example

### Description
This is an example of how riddle content, including media like X posts, should be structured.

### Request Body Example
```json
{
    "type": "Content",
    "title": "Welcome to the quiz",
    "description": "This quiz will test your knowledge about France",
    "media": {
        "type": "X",
        "url": "https://x.com/username/status/1234567890"
    }
}
```
```

--------------------------------

### Full Predictor Configuration Example

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/predictor

A comprehensive example demonstrating the structure of a complete predictor, including multiple blocks ('PickTheWinner' and 'GuessTheScore') and a result page. This illustrates how different components are nested within the 'build' object.

```json
{
    "type": "Predictor",
    "build": {
        "title": "Predictor example (Builder API)",
        "blocks": [
            {
                "title": "Who will win?",
                "type": "PickTheWinner",
                "items": [{
                        "title": "Team A",
                        "backgroundColor": "#FF0000",
                        "textColor": "#FFFFFF"
                    },
                    {
                        "title": "Team B",
                        "backgroundColor": "#0000FF",
                        "textColor": "#FFFFFF"
                    }
                ]
            },
            {
                "title": "What will be the score?",
                "type": "GuessTheScore",
                "items": [
                    {
                        "title": "Team A"
                    },
                    {
                        "title": "Team B"
                    }
                ]
            }
        ],
        "result": {
            "title": "Thank you!",
            "description": "We are happy to have you here"
        }
    }
}
```

--------------------------------

### API Exception Response Format

Source: https://www.riddle.com/help/api/getting-started

Depicts the structure of an API response when an exception occurs, including error details.

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

--------------------------------

### Full Form Creation Example (JSON)

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/form

An example demonstrating the complete structure for creating a form using the API. It includes form title, blocks with fields, and a personalized result page utilizing dynamic variables.

```json
{
    "type": "Form",
    "build": {
        "title": "My data collection form",
        "blocks": [
            {
                "title": "Please enter your data.",
                "type": "FormBuilder",
                "fields": {
                    "Your email": "Email",
                    "Your name": "Name"
                }
            }
        ],
        "result": {
            "title": "Thank you!",
            "description": "Thank you for entering your data %name. We will get back to you soon."
        }
    }
}
```

--------------------------------

### Full Poll Example (Builder API)

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/poll

A comprehensive example demonstrating the structure of a complete poll object, including various block types and result page configuration.

```APIDOC
## Full Poll Example (Builder API)

### Description
This example shows a complete poll object, illustrating the usage of different block types such as SingleChoice, MultipleChoice, Matrix, Order, Upvote, NetPromoterScore, Swiper, and Reaction, along with the result page configuration.

### Method
N/A (This describes a data structure, not an endpoint)

### Endpoint
N/A

### Request Example
```json
{
    "type": "Poll",
    "build": {
        "title": "Poll example (Builder API)",
        "blocks": [
            {
                "title": "What's your favorite color?",
                "type": "SingleChoice",
                "items": [
                    "Red",
                    "Blue",
                    "Green",
                    "Yellow"
                ]
            },
            {
                "title": "What are your favorite animals?",
                "type": "MultipleChoice",
                "items": [
                    "Dog",
                    "Cat",
                    "Bird",
                    "Fish"
                ]
            },
            {
                "title": "I am happy with the following aspects of Riddle.",
                "description": "Choose one from 'Bad' to 'Good'",
                "type": "Matrix",
                "items": [
                    "Design",
                    "Usability",
                    "Performance"
                ]
            },
            {
                "title": "What are your favorite animals?",
                "description": "Drag and drop the items into the order you prefer",
                "type": "Order",
                "items": [
                    "Dog",
                    "Cat",
                    "Bird",
                    "Fish"
                ]
            },
            {
                "title": "What do you like most about Riddle?",
                "description": "Select one or more items",
                "type": "Upvote",
                "items": [
                    "Design",
                    "Usability",
                    "Performance"
                ]
            },
            {
                "title": "How likely are you to recommend Riddle to a friend?",
                "description": "Select one of the options below",
                "type": "NetPromoterScore",
                "positiveTitle": "I completely agree",
                "negativeTitle": "I completely disagree"
            },
            {
                "title": "Hot or not: Riddle",
                "description": "Swipe left or right to answer",
                "type": "Swiper",
                "items": [
                    {
                        "emoji": "😞"
                    },
                    {
                        "emoji": "😍"
                    }
                ]
            },
            {
                "title": "How do you feel about Riddle?",
                "description": "Select one of the options below",
                "type": "Reaction",
                "reactionType": "AgreeDisagree"
            }
        ],
        "result": {
            "title": "Thank you!",
            "description": "We are happy to have you here"
        }
    }
}
```
```

--------------------------------

### Full Quiz Example with All Blocks

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/quiz

Provides a comprehensive example of a quiz structure, including various question block types (SingleChoice, MultipleChoice, TextEntry, Order, Flashcard) and result page configurations.

```APIDOC
## Full Quiz Example

### Description
This example demonstrates a complete quiz structure using the Riddle Help API, showcasing different block types for questions and defining multiple result pages.

### Method
N/A (This describes a data structure, not an endpoint)

### Endpoint
N/A

### Parameters
#### Request Body (Example Structure)
- **type** (string) - The type of content, expected to be "Quiz".
- **build** (object) - Contains the main quiz configuration.
  - **title** (string) - The title of the quiz.
  - **blocks** (array) - An array of question block objects.
    - **title** (string) - The question title.
    - **type** (string) - The type of question (e.g., "SingleChoice", "MultipleChoice", "TextEntry", "Order", "Flashcard").
    - **items** (object or array) - Question-specific items (choices, answers, etc.).
    - **explanation** (object) - Feedback for correct answers.
      - **title** (string) - Explanation title.
      - **description** (string) - Explanation description.
    - **wrongExplanation** (object) - Feedback for incorrect answers (optional).
      - **title** (string) - Wrong explanation title.
      - **description** (string) - Wrong explanation description.
    - Additional fields may exist depending on the block type (e.g., `answers`, `ignoreCase`, `lives`, `itemsShuffled`, `guesses`, `description`, `hint`, `backside`).
  - **results** (array) - An array of result page objects (see previous example for details).

### Request Example
```json
{
    "type": "Quiz",
    "build": {
        "title": "Quiz example (Builder API)",
        "blocks": [
            {
                "title": "What's the capital of Germany?",
                "type": "SingleChoice",
                "items": {
                    "Berlin": true,
                    "Lissabon": false,
                    "Leipzig": false
                },
                "explanation": {
                    "title": "Correct!",
                    "description": "Berlin is the capital of Germany"
                },
                "wrongExplanation": {
                    "title": "Incorrect!",
                    "description": "Berlin is the capital of Germany"
                }
            },
            {
                "title": "What are valid colors in German?",
                "type": "MultipleChoice",
                "items": {
                    "rot": true,
                    "schwarz": true,
                    "nero": false
                },
                "explanation": {
                    "title": "Correct!",
                    "description": "Only 'rot' and 'schwarz' are valid colors in German"
                }
            },
            {
                "title": "Type 'hello' in either Italian, German, or French.",
                "type": "TextEntry",
                "answers": [
                    "Ciao",
                    "Hallo",
                    "Bonjour"
                ],
                "explanation": {
                    "title": "Correct!",
                    "description": "Ciao, Hallo, and Bonjour all mean 'hello'"
                },
                "wrongExplanation": {
                    "title": "Incorrect!",
                    "description": "Ciao, Hallo, and Bonjour all mean 'hello'"
                },
                "ignoreCase": true,
                "ignoreSpaces": true,
                "lives": 3
            },
            {
                "title": "Order the following colors from lightest to darkest.",
                "type": "Order",
                "items": [
                    "red",
                    "blue",
                    "green"
                ],
                "itemsShuffled": true,
                "guesses": 3
            },
            {
                "title": "Capital of Germany",
                "description": "Germany is a country in Europe",
                "hint": "Starts with a 'B'",
                "type": "Flashcard",
                "backside": {
                    "title": "Berlin",
                    "description": "Berlin is the capital of Germany"
                }
            }
        ],
        "results": [
            {
                "title": "Not so good...",
                "description": "There's room for improvement",
                "minPercentage": 0,
                "maxPercentage": 50
            },
            {
                "title": "Well done!",
                "description": "You're a winner",
                "minPercentage": 51,
                "maxPercentage": 100
            }
        ]
    }
}
```

### Response
#### Success Response (200)
N/A (This describes a data structure)

#### Response Example
N/A
```

--------------------------------

### Share Object Example

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/result-pages

An example JSON object for the 'Share' content block. This object defines properties like title, description, and the networks on which content can be shared.

```json
{
    "type": "Share",
    "title": "Share this poll!",
    "description": "This is a description",
    "networks": ["fb", "linkedin"]
}
```

--------------------------------

### Configure Order Question (JSON)

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/quiz

Example of a basic order question configuration. Requires title, type, and items. The order of items in the array determines the correct sequence.

```json
{
    "title": "Order the following colors from lightest to darkest.",
    "type": "Order",
    "items": ["red", "blue", "green"]
}
```

--------------------------------

### Image Object Example

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/result-pages

An example JSON object for the 'Media' content block, used to display an image. It requires a 'media' property containing the URL of the image to be displayed.

```json
{
    "type": "Media",
    "media": "https://www.example.com/image.jpg"
}
```

--------------------------------

### Riddle API Response Formats

Source: https://www.riddle.com/help/api/getting-started

This section explains the structure of successful API responses and various error responses, including validation errors.

```APIDOC
## Response Format

### Success Response (HTTP 200)

When no exception occurs, the API returns a JSON object with a `success` flag set to `true`.

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

*   **data** (any) - The actual response data, which can vary depending on the endpoint (e.g., string for embed code, array for riddle lists).

### Exception Handling

In case of an error, the API returns a JSON object with a `success` flag set to `false`.

```json
{
    "success": false,
    "code": [HTTP status code],
    "error": "[Unique error code]",
    "message": "[Error message]"
}
```

*   **code** (integer) - The HTTP response code.
*   **error** (string) - A unique error code for programmatic handling.
*   **message** (string) - A detailed explanation of the error.

### Validation Errors

Validation errors provide specific details about input mistakes.

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

*   **validationErrors** (array) - An array of objects, each detailing a specific validation issue.
```

--------------------------------

### Full Quiz Example with Various Blocks

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/quiz

An example demonstrating a complete quiz structure using the Riddle Help API. It includes various block types such as SingleChoice, MultipleChoice, TextEntry, Order, and Flashcard, along with their configurations and result page definitions.

```json
{
    "type": "Quiz",
    "build": {
        "title": "Quiz example (Builder API)",
        "blocks": [
            {
                "title": "What's the capital of Germany?",
                "type": "SingleChoice",
                "items": {
                    "Berlin": true,
                    "Lissabon": false,
                    "Leipzig": false
                },
                "explanation": {
                    "title": "Correct!",
                    "description": "Berlin is the capital of Germany"
                },
                "wrongExplanation": {
                    "title": "Incorrect!",
                    "description": "Berlin is the capital of Germany"
                }
            },
            {
                "title": "What are valid colors in German?",
                "type": "MultipleChoice",
                "items": {
                    "rot": true,
                    "schwarz": true,
                    "nero": false
                },
                "explanation": {
                    "title": "Correct!",
                    "description": "Only 'rot' and 'schwarz' are valid colors in German"
                }
            },
            {
                "title": "Type 'hello' in either Italian, German, or French.",
                "type": "TextEntry",
                "answers": [
                    "Ciao",
                    "Hallo",
                    "Bonjour"
                ],
                "explanation": {
                    "title": "Correct!",
                    "description": "Ciao, Hallo, and Bonjour all mean 'hello'"
                },
                "wrongExplanation": {
                    "title": "Incorrect!",
                    "description": "Ciao, Hallo, and Bonjour all mean 'hello'"
                },
                "ignoreCase": true,
                "ignoreSpaces": true,
                "lives": 3
            },
            {
                "title": "Order the following colors from lightest to darkest.",
                "type": "Order",
                "items": [
                    "red",
                    "blue",
                    "green"
                ],
                "itemsShuffled": true,
                "guesses": 3
            },
            {
                "title": "Capital of Germany",
                "description": "Germany is a country in Europe",
                "hint": "Starts with a 'B'",
                "type": "Flashcard",
                "backside": {
                    "title": "Berlin",
                    "description": "Berlin is the capital of Germany"
                }
            }
        ],
        "results": [
            {
                "title": "Not so good...",
                "description": "There's room for improvement",
                "minPercentage": 0,
                "maxPercentage": 50
            },
            {
                "title": "Well done!",
                "description": "You're a winner",
                "minPercentage": 51,
                "maxPercentage": 100
            }
        ]
    }
}
```

--------------------------------

### Riddle API Authentication

Source: https://www.riddle.com/help/api/index

To access the Riddle API, you need an API key. This key can be found or created on the API keys page within the Riddle creator. Use this key in the Authorization header for API requests.

```APIDOC
## Riddle API Authentication

### Description
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.

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

### Request Example (cURL)
```bash
curl --location --request POST 'https://www.riddle.com/creator/api/v3/riddle/list' \
--header 'Authorization: Bearer [your API key]'
```
```

--------------------------------

### Non-Existing Block Error Example

Source: https://www.riddle.com/help/api/build-riddles/settings-configuration/logic-settings

An example of faulty logic settings where a `blockId` references a block that is not defined in the main `blocks` array. This will result in an error during build time.

```json
{
    "blockId": 999, // block with ID 999 does not exist in blocks array
    "next": {
        "blockId": 2
    }
}
```

--------------------------------

### Configure Single Choice Question with Item Scores/Explanations (JSON)

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/quiz

Example of a single choice question where each item can have its own score and explanation. This allows for differentiated scoring and feedback based on the selected answer.

```json
{
    "title": "The best noodles?",
    "type": "SingleChoice",
    "items":  {
        "Spaghetti": {
            "isCorrect": true,
            "score": 2,
            "explanation": {
                "title": "Correct!",
                "description": "Spaghetti is the best noodle"
            }
        },
        "Fusilli": {
            "isCorrect": false,
            "score": 0,
            "explanation": {
                "title": "Incorrect!",
                "description": "Spaghetti is the best noodle"
            }
        }
    }
}
```

--------------------------------

### API Rate Limit Exceeded Response

Source: https://www.riddle.com/help/api/index

Example JSON response indicating that the API rate limit has been exceeded, typically returning a 429 HTTP status code and a relevant error message.

```JSON
{
    "success": false,
    "code": 429,
    "error": "API_RATE_LIMIT_EXCEEDED",
    "message": "Minutely API rate limit of 100 requests exceeded"
}

```

--------------------------------

### Successful API Response Format

Source: https://www.riddle.com/help/api/index

Illustrates the JSON structure of a successful response from the Riddle API, typically returning a 'success' flag, HTTP code, and the requested 'data'.

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

```

--------------------------------

### API Exception Handling Response Format

Source: https://www.riddle.com/help/api/index

Details the JSON structure for API responses when an exception occurs, including 'success' as false, an HTTP code, an error code, and a descriptive message.

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

```

--------------------------------

### Riddle API Exception Handling

Source: https://www.riddle.com/help/api/index

Error responses from the Riddle API include a success flag, status code, an error code, and a message. Validation errors provide more specific details about the mistake.

```APIDOC
## Exception handling

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

### Response Example (General Error)
```json
{
    "success": false,
    "code": 400,
    "error": "BAD_REQUEST",
    "message": "Bad Request."
}
```

### Parameters
- `code`: The HTTP response code.
- `error`: An unique error code.
- `message`: An error message with more details.

### Response Example (Validation Error)
```json
{
    "success": false,
    "code": 400,
    "error": "RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_VALIDATION",
    "message": "SingleChoice: Block properties are invalid. See the validation errors for more details.",
    "validationErrors": [
        {
            "message": "Input is not a string.",
            "code": "NOT_STRING",
            "property": "title"
        }
    ]
}
```
```

--------------------------------

### Configure Flashcard Question (JSON)

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/quiz

Example of a flashcard question configuration. Requires title, type, and a backside object containing the content to be revealed upon flipping. Optional description and hint can be provided.

```json
{
    "title": "Capital of germany",
    "description": "Germany is a country in Europe",
    "hint": "Starts with a 'B'",
    "type": "Flashcard",
    "backside": {
        "title": "Berlin",
        "description": "Berlin is the capital of Germany"
    }
}
```

--------------------------------

### Riddle API Rate Limiting

Source: https://www.riddle.com/help/api/index

The Riddle API is rate-limited to 100 requests per minute and 2000 requests per hour per account. Exceeding these limits will result in HTTP 429 responses.

```APIDOC
## Rate limiting

### Description
By default the Riddle API is rate limited to 100 requests per minute, 2000 requests per hour. Note that this is a **shared rate limit across all API keys of your Riddle account** (even if within different projects). If you exceed this limit you will receive HTTP 429 responses until the rate limit window resets.

### Response Example (Rate Limit Exceeded)
```json
{
    "success": false,
    "code": 429,
    "error": "API_RATE_LIMIT_EXCEEDED",
    "message": "Minutely API rate limit of 100 requests exceeded"
}
```

### Notes
If your use case requires more requests per minute/hour please contact Riddle support.
```

--------------------------------

### API Validation Error Response Format

Source: https://www.riddle.com/help/api/index

Shows the JSON structure for API responses when validation errors occur, providing details about the specific validation failures, including messages, codes, and affected properties.

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

```

--------------------------------

### Riddle API Response Format

Source: https://www.riddle.com/help/api/index

Successful API responses (HTTP 200) follow a standard format containing a success flag, status code, and a data field. The structure of the 'data' field varies depending on the endpoint.

```APIDOC
## Response format

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

### Response Example (Success)
```json
{
    "success": true,
    "code": 200,
    "data": "[response data]"
}
```

### Notes
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.
```

--------------------------------

### Configure Publish Settings (JSON)

Source: https://www.riddle.com/help/api/build-riddles/settings-configuration/publish-settings

This example shows how to include advanced publish settings within the 'publish' property of the build object. These settings allow customization of features like DOI enablement.

```json
{
    "blocks": [...],
    "publish": {
        "isDoiEnabled": true,
        ...
    }
}
```

--------------------------------

### Asynchronous Build Request Example (JSON)

Source: https://www.riddle.com/help/api/build-riddles/advanced-features/batchandasync-processing

This JSON object demonstrates how to set the `queue` property to `true` to mark a build as asynchronous. It includes the structure for a 'Quiz' type build with a single-choice block.

```json
{
    "type": "Quiz",
    "queue": true,
    "blocks": [
        {
            "title": "What is the capital of France?",
            "type": "SingleChoice",
            "items":  {
                "Berlin": false,
                "Madrid": false,
                "Paris": true
            }
        }
    ]
}
```

--------------------------------

### Build Riddle API

Source: https://www.riddle.com/help/api/build-riddles/getting-started

This endpoint allows you to build Riddles dynamically. You specify the Riddle type and a build configuration that defines its structure, including title, blocks, and results.

```APIDOC
## POST /websites/riddle_help_api/build

### Description
Builds a Riddle dynamically based on the provided configuration.

### Method
POST

### Endpoint
`/build`

### Parameters
#### Request Body
- **type** (string) - Required - The type of Riddle to build (e.g., "Poll", "Quiz").
- **project** (integer) - Optional - The ID of the project to create the Riddle in (if using a personal project API key).
- **build** (object) - Required - The configuration object for building the Riddle.
  - **title** (string) - Required - The title of the Riddle.
  - **blocks** (array) - Required - An array of blocks that make up the Riddle. The order determines the Riddle's sequence.
    - Each block object should have at least a `title` and `type` property. Specific block types (e.g., `SingleChoice`, `Form`) have additional required properties.
  - **result** (object) - Required for Polls - The result shown after completion.
    - **title** (string) - Required - The title of the result.
    - **description** (string) - Optional - The description of the result.
  - **results** (array) - Required for other Riddle types - An array of results that can be shown to the user.
    - Each result object should have at least `title` and `description` properties.

### Request Example
```json
{
    "type": "Poll",
    "project": 123,
    "build": {
        "title": "Favorite color poll",
        "blocks": [
            {
                "title": "What's your favorite color?",
                "type": "SingleChoice",
                "items": [
                    "green",
                    "red"
                ]
            }
        ],
        "result": {
            "title": "Thank you",
            "description": "Thanks for your vote."
        }
    }
}
```

### Response
#### Success Response (200)
Details of the created Riddle, including its ID and preview URL.

#### Response Example
```json
{
  "riddleId": "some-riddle-id",
  "previewUrl": "https://example.com/preview/some-riddle-id"
}
```

#### Error Response (e.g., 400 Bad Request)
Returns an error message if the request payload is invalid.

#### Error Response Example
```json
{
  "error": "Invalid request payload. Please check the 'build' configuration."
}
```
```

--------------------------------

### Build a Poll using Riddle Builder API

Source: https://www.riddle.com/help/api/build-riddles/getting-started

This JSON object demonstrates how to construct a simple poll using the Riddle Builder API. It specifies the Riddle type as 'Poll', includes a project ID, and defines the poll's title, a single-choice question block, and a result message.

```json
{
    "type": "Poll",
    "project": 123,
    "build": {
        "title": "Favorite color poll",
        "blocks": [{
            "title": "What's your favorite color?",
            "type": "SingleChoice",
            "items": [
                "green",
                "red"
            ]
        }],
        "result": {
            "title": "Thank you",
            "description": "Thanks for your vote."
        }
    }
}
```

--------------------------------

### Example Riddle Object Structure

Source: https://www.riddle.com/help/api/build-riddles/settings-configuration/preset-settings

This JSON object illustrates the structure of a Riddle, including the `preset` object where timer configurations are defined. It shows how to set a global timer with properties like `timeLimit` and `pauseOnNonQuestionBlocks`.

```json
{
    "blocks": [...],
    "preset": {
        "riddleTimer": {
            "timeLimit": 60,
            "pauseOnNonQuestionBlocks": true,
            "warningAt": 10,
            "format": "s",
            "shape": "circleTimer"
        }
    }
}
```

--------------------------------

### Leaderboard Object Example

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/result-pages

An example JSON object for the 'Leaderboard' content block. This block connects a specific leaderboard to the result page, identified by its UUID.

```json
{
    "type": "Leaderboard",
    "leaderboard": "hQ3SYWur"
}
```

--------------------------------

### Answer Branching with Rules

Source: https://www.riddle.com/help/api/build-riddles/settings-configuration/logic-settings

Illustrates how to implement answer branching where, after a block is completed, further branching is determined by a set of rules. This allows for more complex, multi-path logic flows.

```json
{
    "answers": ["Answer 1", "Answer 2"],
    "blockId": 2,
    "branchingType": "answer",
    "rules": [
       "..."
    ]
}
```

--------------------------------

### Configure Double-Opt-In (DOI) Feature (JSON)

Source: https://www.riddle.com/help/api/build-riddles/settings-configuration/publish-settings

This example shows how to enable the Double-Opt-In (DOI) feature by setting 'isDoiEnabled' to true and further customizing the DOI process using the 'doiConfig' object. This includes setting email subjects, texts, and confirmation page details.

```json
{
    "isDoiEnabled": true,
    "doiConfig": {
        "emailSubject": "Please confirm your email %name",
        "emailText": "Hi %name, Please confirm your email by clicking the button below.",
        "emailConfirmationButtonLabel": "Confirm email",
        "confirmationPageHeadline": "Thank you for confirming your email",
        "confirmationPageText": "You can now access the content",
        "confirmationPageUrl": "https://www.example.com"
    }
}
```

--------------------------------

### Retrieve Preset and Palette IDs (JSON)

Source: https://www.riddle.com/help/api/build-riddles/settings-configuration/preset-settings

This JSON example shows a successful response from the Builder API's presets endpoint, detailing how to retrieve project preset IDs and their corresponding palette IDs.

```json
{
    "success": true,
    "code": 200,
    "data": [
        {
            "id": 805,
            "name": "My project preset",
            "palettes": [
                {
                    "id": "Zymx",
                    "name": "my palette"
                }
            ]
        }
    ]
}
```

--------------------------------

### Answered Blocks Object Example

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/result-pages

An example JSON object for the 'AnsweredBlocks' content block. This configuration determines whether vote counts, percentages, and answer images are displayed.

```json
{
    "type": "AnsweredBlocks",
    "areTotalVotesVisible": true
}
```

--------------------------------

### Pitfalls

Source: https://www.riddle.com/help/api/build-riddles/settings-configuration/logic-settings

Tips to avoid common pitfalls when building logic settings in the Riddle builder.

```APIDOC
## Pitfalls

Building the logic settings can be tricky. Here are some tips to avoid common pitfalls:

*   Result blocks are **not** part of the logic tree in the API. They will always be shown at the end of the Riddle logic tree, regardless of the path taken. An end of the logic tree can be defined by adding a logic layer with no `next` property or with the `next` property set to _null_.
*   Make sure to use custom IDs for blocks and answers to make it easier to reference them in the logic settings.
```

--------------------------------

### Generate Riddle with AI (JSON)

Source: https://www.riddle.com/help/api/generate-riddles-with-ai/project

This example shows the JSON payload required to generate a riddle. It specifies the topic, number of questions, language, difficulty, and the target project ID. This is a common input format for many AI-driven content generation APIs.

```json
{
    "topic": "Soccer",
    "numQuestions": 5,
    "language": "en",
    "difficulty": "easy",
    "project": 12345
}
```

--------------------------------

### Quiz Structure with Result Pages

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/quiz

Defines the structure of a quiz, including how to set up multiple result pages segmented by percentage ranges. Each result page consists of a title, description, minimum percentage, and maximum percentage.

```APIDOC
## Quiz Result Pages Structure

### Description
This section details how to configure multiple result pages for a quiz. Users are segmented into these results based on their final score (percentage).

### Method
N/A (This describes a data structure, not an endpoint)

### Endpoint
N/A

### Parameters
#### Request Body (Example Structure)
- **build.results** (array) - Contains a list of result page objects.
  - **title** (string) - Required - The title of the result page.
  - **description** (string) - Required - A description for the result page.
  - **minPercentage** (integer) - Required - The minimum score percentage to qualify for this result.
  - **maxPercentage** (integer) - Required - The maximum score percentage to qualify for this result.

### Request Example
```json
{
    "build": {
        "results": [
            {
                "title": "My result 0-30%",
                "description": "Description 1",
                "minPercentage": 0,
                "maxPercentage": 50
            },
            {
                "title": "My result 31-100%",
                "description": "Description 2",
                "minPercentage": 51,
                "maxPercentage": 100
            }
        ]
    }
}
```

### Response
#### Success Response (200)
N/A (This describes a data structure)

#### Response Example
N/A
```

--------------------------------

### Circular Reference Error Example

Source: https://www.riddle.com/help/api/build-riddles/settings-configuration/logic-settings

An example of faulty logic settings that creates a circular reference, leading to an infinite loop. This highlights a common pitfall where a block references itself indirectly up the logic tree.

```json
{
    "blockId": 1,
    "next": {
        "blockId": 2,
        "next": {
            "blockId": 1
        }
    }
}
```

--------------------------------

### Linear Branching Example - Sequence of Blocks

Source: https://www.riddle.com/help/api/build-riddles/settings-configuration/logic-settings

This JSON object demonstrates a simple linear branching logic flow, where each block is followed by a specific next block in a defined sequence. It uses the 'blockId' and 'next' properties to chain blocks.

```json
{
    "blockId": 1,
    "next": {
        "blockId": 2,
        "next": {
            "blockId": 3,
            "next": {
                "blockId": 4
            }
        }
    }
}

```

--------------------------------

### Configure Text Entry Question with Explanations (JSON)

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/quiz

Configuration for a text entry question including correct answers and optional explanations for both correct and incorrect responses. Explanations can include a title, description, and media URL.

```json
{
    "title": "Type 'hello' in either Italian, German, or French.",
    "type": "TextEntry",
    "answers": ["Ciao", "Hallo", "Bonjour"],
    "explanation": {
        "title": "My correct explanation",
        "description": "My correct explanation description",
        "media": "https://example.com/correct-image.jpg"
    },
    "wrongExplanation": {
        "title": "My wrong explanation",
        "description": "My wrong explanation description",
        "media": "https://example.com/wrong-image.jpg"
    }
}
```

--------------------------------

### Result Page Configuration

Source: https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/poll

Details on how to configure the result page for a poll, including basic title and description properties.

```APIDOC
## Result Page Configuration

### Description
Specifies the configuration for the result page of a poll. A poll can only have one result page, defined within `build.result`. Basic result pages include `title` and `description`.

### Method
N/A (This describes a data structure, not an endpoint)

### Endpoint
N/A

### Parameters
#### Result Object Properties
- **title** (string) - Required - The title of the result page.
- **description** (string) - Required - The description displayed on the result page.

### Request Example
```json
{
    "title": "Thank you!",
    "description": "We are happy to have you here"
}
```
```
Tokens:
Raw