[{"data":1,"prerenderedAt":355},["ShallowReactive",2],{"search-api":3},[4,18,30,43,54,65,72,90,105,112,123,131,139,149,159,169,188,204,219,233,243,253,264,273,280,291,300,307,314,330,341,349],{"id":5,"path":6,"dir":7,"title":8,"description":7,"keywords":9,"body":17},"content:15.Api:0.index.md","/api","","Getting started",[10,11,12,13,14,15,16],"Introduction","Specification","Authentication","Response format","Exception handling","Rate limiting","Next steps"," 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://www.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.\nOnce 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\nHTTP method: POST\nHeaders:\n{\n Authorization: \"Bearer [your API key]\"\n}\n Example Request via CURL: curl --location --request POST 'https://www.riddle.com/creator/api/v3/riddle/list' \\\n --header 'Authorization: Bearer [your API key]'\n Response format In case no exception occurs and the API returns HTTP 200 the response will have the following format: {\n \"success\" : true ,\n \"code\" : 200 ,\n \"data\" : \"[response data]\"\n }\n 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: {\n \"success\" : false ,\n \"code\" : 400 ,\n \"error\" : \"BAD_REQUEST\" ,\n \"message\" : \"Bad Request.\"\n }\n 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 further describe 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: {\n \"success\" : false ,\n \"code\" : 400 ,\n \"error\" : \"RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_VALIDATION\" ,\n \"message\" : \"SingleChoice: Block properties are invalid. See the validation errors for more details.\" ,\n \"validationErrors\" : [\n {\n \"message\" : \"Input is not a string.\" ,\n \"code\" : \"NOT_STRING\" ,\n \"property\" : \"title\"\n }\n ]\n }\n Rate limiting 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. Example response: {\n \"success\" : false ,\n \"code\" : 429 ,\n \"error\" : \"API_RATE_LIMIT_EXCEEDED\" ,\n \"message\" : \"Minutely API rate limit of 100 requests exceeded\"\n }\n If your use case requires more requests per minute/hour please contact us via the support chat or via email . Next steps Look at the specification of all available API endpoints : Find out what you can do with the Riddle API. Manage Riddles : List, publish, embed, tag, and delete your Riddles – and fetch their leads. 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. html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":19,"path":20,"dir":21,"title":22,"description":23,"keywords":24,"body":29},"content:15.Api:1.MCP.md","/api/mcp","api","MCP","The Model Context Protocol (MCP) is a standard that lets AI models and agents call external tools and APIs. Riddle's MCP exposes our API to AI agents, so any action you can do via the API – such as listing, building, generating, and analyzing Riddles – can be triggered from an AI chat.",[25,26,27,28,16],"How to use","Available Tools & Resources","Response Format","Troubleshooting"," MCP The M odel C ontext P rotocol (MCP) is a standard that lets AI models and agents call external tools and APIs. Riddle's MCP exposes our API to AI agents, so any action you can do via the API – such as listing, building, generating, and analyzing Riddles – can be triggered from an AI chat. This MCP version is an alpha: not all Creator/API functionality is covered yet (e.g. updating, adding, or removing Riddle blocks). More tools are coming, stay tuned. How to use When using the Riddle MCP, you have two options for authentication: Preferred: Via public MCP URL in Claude (using the CIMD (Client ID Metadata Document) protocol) Via MCP key embedded in the URL Via public MCP URL in Claude To add the Riddle MCP to your Claude account , navigate to Settings > Connectors > Add custom connector. To add the Riddle MCP to your Claude organization , navigate to Organization settings > Connectors > Add > Custom > Web connector. In both cases the following dialogue will show:\n Enter the following: Name: Riddle MCP URL: https://www.riddle.com/creator/api/v3/mcp After clicking on add , you are almost ready to use the MCP in your Claude chats: Click on connect afterwards to link your Riddle account with Claude and if necessary, you'll have to log in. Once you're done with this, you can try asking Claude to list the latest, published Riddles from your account to test the connection. You can also use the whoami tool to verify your account and project access. Via MCP key If you wish to use the MCP with an MCP key, create one on the API keys page (see the Authentication guide for details). Please make sure to pick a MCP key – regular API keys will not work and will return an error. Personal MCP keys are best suited: they give you access both to your personal project and to all projects in which you have the corresponding AI permissions . If you can only create normal API keys, your user role is missing the required permissions – ask a project administrator to grant them or to issue an MCP key for you. Once you have your key, append it to the MCP URL as a path segment: https://www.riddle.com/creator/api/v3/mcp/[MCP_KEY] Replace [MCP_KEY] with your actual key, then add this URL as a custom connector in Claude (same steps as above). Please note that accessing the MCP via a configured MCP key is inferior to the CIMD option. It requires you to embed your key in the URL, and it is less flexible: you need to create a new MCP key for every Riddle account you want to access. With CIMD, each user authorizes with their own Riddle account instead, so no account has to be pre-configured in the URL. Available Tools & Resources Note: You can use standard MCP functionality to list tools and resources available to the model; this will include more verbose information, e.g. API parameters. Below is a short summary, but make sure to fetch the MCP's current capabilities to get the most up-to-date information. Tools (32) The 32 tools fall into six categories: Category Tools Utility & Account 2 Projects 2 Riddle management 9 Builder API 7 AI generation 7 Statistics 5 Utility & Account (2) Test connectivity and check the context of your API key. Tool Description ping Connectivity and authentication test – simply returns \"Pong\". whoami Returns information about the current API key: the authenticated user (ID, email, name) and the linked project/team, if any. Useful to verify authentication and retrieve your user ID or project ID. Projects (2) List projects and fetch project details. Tool Description project_list Lists all projects this token has access to. If it is a project API token, only the project linked to the token will be returned. project_get Fetches a single project by its project ID. Riddle management (9) Find, read, and manage existing Riddles. Tool Description riddle_list Paginated list of Riddles from a single project – filterable by type, status, tags, and search term; sortable. For Riddles across all projects, use riddle_account_list instead. riddle_account_list Paginated list of Riddles across the entire account – the personal project plus all team projects the user has access to. riddle_get Fetches a single Riddle by its UUID – including content, settings, and metadata. riddle_rename Renames a Riddle (new title by UUID). riddle_publish Publishes a Riddle – it becomes available via its public URL. riddle_unpublish Takes a Riddle offline – the public URL is no longer reachable. riddle_delete Deletes a Riddle by its UUID. Only Riddles created via the Builder API can be deleted. riddle_get_embed_code Returns the HTML embed code of a published Riddle. riddle_qr_code Generates a QR code (base64-encoded SVG) for a published Riddle. Builder API (7) Create Riddles with structured parameters (blocks, results, logic, presets, publish settings). Tool Description riddle_builder_quiz Builds a Quiz – question blocks (SingleChoice/MultipleChoice/TextEntry), results with percentage ranges, optional branching logic and leaderboard connection. riddle_builder_poll Builds a Poll – block types include SingleChoice, Matrix, Order, Upvote, NPS, RateIt, Swiper, and Reaction; optional branching logic. riddle_builder_form Builds a Form – FormBuilder blocks with field mapping (e.g. Email, Name); result page with dynamic variables such as %fieldname. riddle_builder_personality Builds a Personality quiz – questions with score arrays per answer, at least 2 personalities with title/description/media. riddle_builder_predictor Builds a Predictor – blocks of type PickTheWinner or GuessTheScore, optional leaderboard connection. riddle_builder_minigame Builds a Minigame – SlotMachine, WheelSpinner (win/loss/free spin with percentages), or Sudoku. riddle_builder_leaderboard Builds a Leaderboard – connects up to 10 Quizzes, Predictors, or Minigames (Name and Email fields required); optional email validation. AI generation (7) Generate Riddles from a topic or URL via the Riddle AI. Processing is asynchronous – the returned UUID can be used with riddle_get to check the status. Check riddle_aiGenerate_usage first to ensure credits are available. Tool Description riddle_aiGenerate_quizFromTopic Creates a Quiz from a topic – difficulty (easy/medium/hard), language, 1–10 questions. riddle_aiGenerate_quizFromUrl Creates a Quiz from a URL – the content is scraped and turned into questions. riddle_aiGenerate_quizFromUrls Creates a Quiz from up to 5 URLs – the contents are combined to generate questions. riddle_aiGenerate_pollFromTopic Creates a Poll from a topic – language, 1–10 questions. riddle_aiGenerate_pollFromUrl Creates a Poll from a URL – the content is scraped and used to generate poll questions. riddle_aiGenerate_personalityFromTopic Creates a Personality quiz from a topic – configurable number of personalities, attributes, and questions. riddle_aiGenerate_usage Returns the current AI usage and maximum allowed usage for the authenticated user. Statistics (5) Views, starts, and submissions on user, project, and Riddle level. Tool Description stats_fetch Aggregated stats (views, starts, submissions) for a single period – namespace: project, user, or riddle; omit the dates for all-time stats. stats_overview_fetch Stats in daily intervals for a given date range – ideal for dashboards, graphs, and trend analysis. stats_riddle_breakdown Detailed breakdown for a specific Riddle – titles, answer choices, views, time spent, and submissions. stats_project_breakdown Stats breakdown for a specific project. stats_user_breakdown Stats breakdown for the authenticated user across all accessible projects – requires a user API key (will fail with project API keys). Resources (6) Resource URI Description getting-started riddle://reference/getting-started Overview of the Riddle MCP server: available tool categories, common workflows, and authentication model. riddle-types riddle://reference/riddle-builder/riddle-types All 7 Riddle types with their required/optional build fields, result structure, and documentation links. block-types riddle://reference/riddle-builder/block-types Question and content block types per Riddle type with required properties and item formats. form-field-types riddle://reference/riddle-builder/form-field-types All 15 form field types for the FormBuilder block with their properties and configuration options. result-blocks riddle://reference/riddle-builder/result-blocks All 9 result page block types with their properties, format options, and styling configuration. ai-languages riddle://reference/ai/languages All available language codes for AI Riddle generation (used in the \"language\" parameter of riddle_aiGenerate_* tools). Builder capabilities The riddle_builder_* tools do more than their short descriptions suggest. Beyond the required title and blocks , most builder tools accept optional parameters that unlock the same power available in the Creator: Branching logic ( logic ): Define a conditional flow over your blocks instead of a fixed linear order – route users to different blocks based on their answers, and merge paths back together. Supported by Quiz, Poll, and Form. Design presets ( preset ): Base the Riddle on an existing design/preset and override settings such as color palette, language, \"remember user\", and auto-open/auto-close dates. Supported by all types except Leaderboard. Publish automation ( publishSettings ): Configure what happens on publish – double opt-in (DOI), email automation, tracking (pixels, analytics), data layer items, showcase visibility, and third-party integrations. Supported by all types except Leaderboard. Leaderboard connections ( leaderboard / riddleConnections ): Attach a Quiz, Predictor, or Minigame to one or more leaderboards on creation, or create a Leaderboard that connects to existing Riddles (which must have Name and Email fields). Publish & queue ( publish , queue ): Publish the Riddle immediately after creation instead of leaving it as a draft, and/or process the creation asynchronously. Project targeting ( project ): Create the Riddle in a specific project, in your personal project, or in the currently selected project. Fetch the builder reference resources ( riddle://reference/riddle-builder/* ) or list the tools via standard MCP functionality to see the exact fields and formats for each of these. Response Format All responses from the MCP will adhere to the same schema as specified in the API docs for the corresponding endpoint.\nE.g. the riddle_get tool will return a response with the same schema as the GET /riddle/{riddle_uuid} API endpoint, including all details about the riddle content, design, etc. Troubleshooting If you encounter any issues while using the MCP, here are some common troubleshooting steps: API authentication failed : Make sure you are using an MCP key (not a regular API key – re-create if in doubt) and that the URL contains the actual key in place of the [MCP_KEY] placeholder. Missing API permissions : Check if your user role has the necessary AI permissions to access the desired projects and perform the intended actions. If you do not have permission to modify roles, ask your account administrators to grant you the required permissions. ... Still not solved? Please reach out to our support team with details about the issue, either via our support chat or via email , including any error messages received and the steps you have already taken to troubleshoot. Next steps Want to continue reading? Read the following API sections to understand the MCP tools in more detail and see example requests and responses for each of them: 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.",{"id":31,"path":32,"dir":33,"title":34,"description":35,"keywords":36,"body":42},"content:15.Api:2.Analyze Riddles:0.Getting started.md","/api/analyze-riddles/getting-started","analyze-riddles","Getting started - Analyze Riddles","Learn how to analyze Riddles via API",[37,38,39,40,41],"Accessing the Stats API","What is tracked in the stats?","How can I use the stats data and which endpoints are available?","Stats data structure","FAQ / Troubleshooting"," Getting started To analyze your Riddles, you can use the Riddle Stats API to retrieve stats for any of your Riddles, projects or for your personal project. This can help you to analyze the performance of your Riddles, to optimize them, and to get insights into your audience. Dealing with this programmatically via the API allows you to automate this process. In the next sections we will cover different aspects and endpoints of the Stats API. Accessing the Stats API To learn how to access the Riddle API please refer to the Getting started guide. If you are already familiar with the API, you can find all available Stats API endpoints here . What is tracked in the stats? Any interaction with a Riddle is tracked. This includes views, starts, finishes, time spent, leads generated, and more. In general, everything you see on your Riddle stats dashboard is available via the API. In addition to that project and user wide stats are tracked as well and can be requested via the API. How can I use the stats data and which endpoints are available? The stats endpoints serve very distinct purposes and structure the data in different ways: Fetch: This endpoint provides raw stats data for a single Riddle, project or user. This is useful if you want to analyze the performance of a Riddle on a high level. Overview fetch: This endpoint provides the raw stats data for a Riddle, project or user but splits up the given time range into multiple data points. This is useful if you want to get insights over a period of time, giving you multiple data points to analyze. Breakdown: This endpoint provides a detailed stats breakdown of a Riddle with all its associated labels/titles. This is useful if you want to analyze the performance of a Riddle on a low/block level and make it additionally human readable. Project breakdown : This endpoint provides a detailed stats breakdown of all Riddles of a project. This is useful if you want to compare the performance of multiple Riddles of a project. Running into a timeout? Try specifying a smaller time range (with dateFrom and dateTo JSON params). User breakdown: This endpoint provides a detailed stats breakdown of all user + project Riddle stats. This is useful if you want to compare the performance of multiple Riddles of various projects. Please note that this endpoint is the slowest of all breakdowns as it accumulates the most data in one response. Running into a timeout? Try specifying a smaller time range (with dateFrom and dateTo JSON params). Stats data structure We have come up with our own format for the stats data. As your Riddle is a collection of blocks, you can think of the stats data as a combination of global stats (views, finishes) and a collection of individual block stats. Please note that this explanation is not applicable to 1.0 Riddles. An example stats object looks like this: {\n \"global_stats\" : {\n \"core_metrics\" : {\n \"view\" : 20 ,\n \"start\" : 6 ,\n \"time\" : 2737546 ,\n \"lead\" : 5 ,\n \"timeActive\" : 434477 ,\n \"lead_completed\" : 4 ,\n \"finish\" : 4\n },\n \"device\" : {\n \"mobile\" : 8 ,\n \"desktop\" : 12\n },\n \"os\" : {\n \"iOS\" : 8 ,\n \"Mac OS\" : 10 ,\n \"Windows\" : 2\n },\n \"region\" : {\n \"GB\" : 16 ,\n \"DE\" : 2 ,\n \"US\" : 2\n },\n \"domain\" : {\n \"riddle.com\" : 19 ,\n \"yourdomain.com\" : 1\n }\n },\n \"block_1_stats\" : {\n \"core_metrics\" : {\n \"view\" : 5 ,\n \"timeActive\" : 29583 ,\n \"submit\" : 5\n },\n \"answer\" : {\n \"2\" : 2 ,\n \"1\" : 2 ,\n \"-1\" : 1\n }\n },\n \"block_2_stats\" : {\n \"core_metrics\" : {\n \"view\" : 6\n },\n \"form\" : {\n \"submit\" : 5\n }\n },\n \"reset_stats\" : {\n \"core_metrics\" : {\n \"view\" : 6 ,\n \"start\" : 3 ,\n \"time\" : 120788 ,\n \"timeActive\" : 69082 ,\n \"finish\" : 3 ,\n \"lead_completed\" : 3 ,\n \"lead\" : 2 ,\n \"times_reset\" : 1\n },\n \"device\" : {\n \"desktop\" : 6\n },\n \"os\" : {\n \"Mac OS\" : 6\n },\n \"region\" : {\n \"GB\" : 6\n },\n \"domain\" : {\n \"riddle.com\" : 6\n }\n }\n }\n Let's go through the different parts of the stats object in the following sections. Global Stats (\"global_stats\") These are the global stats for the Riddle. They are not specific to a block. They can be divided into the categories: core_metrics: most important and easiest metrics such as views, finishes, time / timeActive (in milliseconds), ... device: device type (mobile, desktop, ...) os: operating system (iOS, Windows, ...) region: region with 2 chars (GB, DE, ...) domain: domain of the website where the Riddle was viewed. Riddle.com is the default showcase domain. Block Stats These are the stats for each block. They can be divided into the categories: core_metrics: views answer: the amount of times each answer was selected; to find answer IDs refer to the Riddle GET API endpoint. form: the amount of times the form was submitted / skipped Reset Stats If you choose to reset stats for a Riddle, the stats for the Riddle will be reset and the stats for the reset Riddle will be stored in the \"reset_stats\" object. This makes sure no data is really lost; only hidden for the stats dashboard and the user. FAQ / Troubleshooting Q: Can I access this API with my subscription plan? A: The Stats API is available for the Business and Enterprise plan. If you are on the Pro plan you can still analyze your Riddles via the stats dashboard in the Creator. Q: Can I access stats for a date range? A: Yes, you can access stats for a date range. To do this use the stats fetch endpoint and specify the params \"dateFrom\" & \"dateTo\" in your request. Q: How can I access my accumulated project stats? A: To do this you need to specify the namespace (this is project ) and the project ID (param entityId) in your request to the stats fetch endpoint , example body for project 123: {\n \"namespace\" : \"project\" ,\n \"entityId\" : 123\n }\n Q: How can I access Riddle stats? A: To do this you need to specify the namespace (this is riddle ) and your Riddle UUID (param entityId) in your request to the stats fetch endpoint , example body for Riddle abc123: {\n \"namespace\" : \"riddle\" ,\n \"entityId\" : \"abc123\"\n }\n Q: How can I get insights over a period of time, giving me multiple data points to analyze? A: To build a chart as easy as possible with the stats data you can use the overview fetch endpoint instead of the normal fetch endpoint. The difference in between those two endpoints is that the overview fetch endpoint splits up the given time range into multiple data points. E.g. if you request for a whole month (= 30 days), 15 data points will be returned with each representing two days (30 / 15 = 2). Q: How does the Riddle / Project / user stats breakdown response look like? An example response to the Riddle breakdown endpoint looks like this: {\n \"success\" : true ,\n \"code\" : 200 ,\n \"data\" : {\n \"general\" : {\n \"device\" : {\n \"mobile\" : 5 ,\n \"desktop\" : 3\n },\n \"os\" : {\n \"iOS\" : 5 ,\n \"Windows\" : 2 ,\n \"Mac OS\" : 1\n },\n \"core_metrics\" : {\n \"view\" : 8 ,\n \"lead\" : 4 ,\n \"start\" : 4 ,\n \"time\" : 8315 ,\n \"finish\" : 4\n },\n \"domain\" : {\n \"riddle.com\" : 8\n },\n \"region\" : {\n \"DE\" : 6 ,\n \"GB\" : 1\n }\n },\n \"blocks\" : [\n {\n \"id\" : 2 ,\n \"title\" : \"My Riddle title\" ,\n \"metrics\" : {\n \"view\" : 0 ,\n \"time\" : 0 ,\n \"submit\" : 4\n },\n \"choices\" : [\n {\n \"id\" : 1 ,\n \"title\" : \"Choice 1\" ,\n \"count\" : 1\n },\n {\n \"id\" : 2 ,\n \"title\" : \"Choice 2\" ,\n \"count\" : 2\n },\n {\n \"id\" : 3 ,\n \"title\" : \"Choice 3\" ,\n \"count\" : 1\n }\n ]\n }\n ],\n \"results\" : [\n {\n \"id\" : 3 ,\n \"title\" : \"Thanks for your vote!\" ,\n \"metrics\" : {\n \"view\" : 4\n },\n \"socialShares\" : []\n }\n ]\n }\n }\n If you choose to request a breakdown for either a project or a full user, the response will be similar but an array of all concerned Riddles (either all project Riddles OR all user + project Riddles) will be returned. Here's a high level overview of the structure of the response: {\n \"success\" : true ,\n \"code\" : 200 ,\n \"data\" : {\n \"RIDDLE_ID1\" : {\n \"general\" : {\n ...\n },\n },\n \"RIDDLE_ID2\" : {\n \"general\" : {\n ...\n },\n }\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":44,"path":45,"dir":46,"title":47,"description":48,"keywords":49,"body":53},"content:15.Api:3.Build Riddles:0.Getting started.md","/api/build-riddles/getting-started","build-riddles","Getting started - Build Riddles","Learn how to build Riddles dynamically via API",[50,51,52,16],"Request format","Example: Build a poll","FAQ"," Getting started You can use the Riddle Builder API to create Riddles dynamically via API. This opens up a lot of possibilities, such as: building Riddles dynamically based on user input building Riddles based on data from a database, spreadsheet or from other sources building daily Riddles for contests or promotions Request format With every request to the build endpoint you specify the Riddle type and a \"build\" configuration which defines the structure of the Riddle you want to create. The build configuration, independent of the Riddle type, always consists of the following properties: title : The title of the Riddle blocks : An array of blocks that make up the Riddle (questions, forms, ...). The order in which you send the blocks is the exact order of the Riddle. result / results : A single result (for Poll) or an array of results that can be shown to the user after they have completed the Riddle. Additionally to the build configuration, you must always specify the type of Riddle you want to build. Note: If you use a personal project API key (= access to all of the projects in your account), you can also specify the project in the root to create the Riddle in a specific project. Click here to learn more. Example: Build a poll Now that we have covered the basics how the build configuration is built up, let's look at an example which is building a simple poll: {\n \"type\" : \"Poll\" ,\n \"project\" : 123 ,\n \"build\" : {\n \"title\" : \"Favorite color poll\" ,\n \"blocks\" : [{\n \"title\" : \"What's your favorite color?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"green\" ,\n \"red\"\n ]\n }],\n \"result\" : {\n \"title\" : \"Thank you\" ,\n \"description\" : \"Thanks for your vote.\"\n }\n }\n }\n Going through the example and its properties: type : The Riddle type is set to Poll build.title : The title of the Riddle is set to \"Favorite color poll\" build.blocks : The Riddle consists of one block, a SingleChoice question with the title \"What's your favorite color?\" and two answer items \"green\" and \"red\" build.result : The result that is shown to the user after they have completed the Riddle (only one Result is allowed for Poll!) This build could be extended of course (e.g. with more questions, different types of questions or even form blocks). It is important to note that all builder blocks presented on the next pages follow the same principle as the properties described above, so you can build any Riddle type with the same structure and can dive deeper if required. FAQ Q: Can I access this API? A: You can access the builder API if you are subscribed to our Business or Enterprise subscription plan. Q: How do I access this API? A: To learn how to access the Riddle API please refer to the Getting started guide. Q: Where can I find the builder endpoint? A: The builder API endpoint can be found here . Q: Which Riddle types are currently supported? A: All Riddle types are supported: Poll Quiz Personality Test Form Predictor Leaderboard Minigame Q: Can I publish the built Riddle right after building it? A: Yes, this is possible. Read this section to learn more. Q: Are there any limits to the number of blocks I can add to a Riddle? A: Yes, the maximum number of blocks you can add to a Riddle is 500. Q: Are there any other limits? A: Yes: form fields are limited to 100 per form the maximum number of items in a single/multiple choice question is 100 the maximum used unique image URLs in a Riddle build configuration is 15 Q: Can I use this API to create monetized Riddles? A: Yes, this is possible. To do this you can use the Ad block. Read more about it here . The Riddle type you choose is irrelevant for this - make sure it is engaging enough for your audience though. Q: Can I use this API to create Riddles with a specific design? A: Yes, this is possible if the Riddle is built in a project . You have two options: Use the default project preset ( explained here ). Use the preset property in the build object to define the preset and palette you want to use. Read more about it here . Next steps Here are a few things you can do next - they are all covered in the following pages: Learn about exception handling Create a quiz , poll , personality , form , minigame , or predictor Riddle Connect your built Riddle to leaderboard(s) Add form fields to your Riddle Use the Ad block to monetize your Riddle or add Content blocks Define the publish settings: Enable DOI, email automation, add integrations, and more Define the preset settings and palette you want to use Define the logic settings / flow of your Riddle Build result pages Add media; such as images, videos, and social media content html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":55,"path":56,"dir":46,"title":57,"description":58,"keywords":59,"body":64},"content:15.Api:3.Build Riddles:1.Exception handling.md","/api/build-riddles/exception-handling","Exception handling - Build Riddles","Learn how to handle exceptions when building Riddles via API",[60,61,62,61,63],"Block property validation exception","Example","Block property value invalid","Block type missing"," Exception handling The build configuration can be faulty in many ways: The structure of the build object is invalid The properties of the blocks are invalid The values of the properties are invalid In the next sections we will go over the different types of errors that can occur and how to handle them. Each section contains the unique error code you receive - check the exception handling section for more information about exceptions and their unique exception codes. Block property validation exception Error code: RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_VALIDATION This error occurs when the value of a property of a block is invalid. The response will contain a validationErrors array with all the errors that occurred. Example In this example we use a Predictor build config in which the title is not a string and the items property is missing. The API returns the following: {\n \"success\" : false ,\n \"code\" : 400 ,\n \"error\" : \"RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_VALIDATION\" ,\n \"message\" : \"PredictorPickTheWinnerBlock: Block properties are invalid. See the validation errors for more details.\" ,\n \"validationErrors\" : [\n {\n \"message\" : \"Input is not a string.\" ,\n \"code\" : \"NOT_STRING\" ,\n \"property\" : \"title\"\n },\n {\n \"message\" : \"PredictorPickTheWinnerBlock: Property \\\" items \\\" is required but not set\" ,\n \"code\" : \"REQUIRED\" ,\n \"property\" : \"items\"\n }\n ]\n }\n As you can see the main message of the error gives you a hint about which block is causing the issue. To learn more about the error you can check the validationErrors array; each validation error contains a message , code , and property . Block property value invalid Error code: RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_INVALID This happens if the validation of the properties succeeded but when creating the block the values are invalid. There are too many possible errors to list them all here, but the error message will give you a hint about what went wrong. Example Adding an integration with a name which does not exist: {\n \"success\" : false ,\n \"code\" : 400 ,\n \"error\" : \"RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_INVALID\" ,\n \"message\" : \"Cannot add \\\" webhook \\\" integration with name \\\" webhook.riddle.com \\\" to Riddle as it does not exist\"\n }\n Block type missing If we try to build a Riddle without setting the type property in a Riddle block the API will return the following error: {\n \"success\" : false ,\n \"code\" : 400 ,\n \"error\" : \"RIDDLE_BUILDER_BLOCK_TYPE_MISSING\" ,\n \"message\" : \"PredictorBuilder: No block type found in block config.\"\n }\n In this case the PredictorBuilder throws the exception. This can happen with other embedded blocks as well, e.g. the result page builder blocks. html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":66,"path":67,"dir":46,"title":68,"description":69,"keywords":70,"body":71},"content:15.Api:3.Build Riddles:2.Project.md","/api/build-riddles/project","Build Riddles in your projects - Build Riddles","Learn how to build Riddles in your projects via API",[61]," Build Riddles in your projects By default the project of the accessing API key will be used - this means that if you use an API key created in your personal project the Riddle will always be added to your personal space. To change this you can specify the project in the root to create the Riddle in a specific project. Example The following example adds the built Riddle to the project with the ID 123 : {\n \"type\" : \"Poll\" ,\n \"project\" : 123 ,\n \"build\" : {\n \"title\" : \"Favorite color poll\" ,\n \"blocks\" : [{\n \"title\" : \"What's your favorite color?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"green\" ,\n \"red\"\n ]\n }],\n \"result\" : {\n \"title\" : \"Thank you\" ,\n \"description\" : \"Thanks for your vote.\"\n }\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":73,"path":74,"dir":75,"title":76,"description":77,"keywords":78,"body":89},"content:15.Api:3.Build Riddles:3.Riddle types and other blocks:1.Poll.md","/api/build-riddles/riddle-types-and-other-blocks/poll","riddle-types-and-other-blocks","Create Poll - Build Riddles","Learn how to build Polls via API",[79,80,81,82,83,84,85,86,87,88,16],"Add Single/multiple choice questions","Add Likert / matrix question","Add order it question","Add upvote question","Add Net Promoter Score question","Add Rate It question","Add Swiper question","Add Reaction Poll question","Result page","Full example"," Create Poll When building a poll you can add: SingleChoice and MultipleChoice questions Other question formats: Likert / Matrix , Order , Upvote , NetPromoterScore , RateIt , Swiper , and Reaction Form fields General blocks One result page Note: Unless otherwise noted, all poll block types below also support a top-level media property (string; the URL of an image or video to display with the question). Wherever an items property is typed as string[] , each item can either be a plain string (used as the item's title ) or an object with title (required), description (optional), and media (optional) – the same format used for PollSwiperItemBlock items, described in the Swiper section below. Add Single/multiple choice questions Properties Property Required Type Description Default title ✓ string The question description string The description of the question media string Media URL to display an image or video with the question type ✓ string set to SingleChoice or MultipleChoice items ✓ string[] An array of possible choices (each item can be a string or an object; see note above) itemsShuffled boolean If set to true , the order of the items/choices will be shuffled false isRequired boolean If set to false , the user can skip the question true layoutType string The layout of the items, either Rows or Columns Rows Example object {\n \"title\" : \"The best noodles?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"Spaghetti\" ,\n \"Fusilli\"\n ]\n }\n Here the difference between SingleChoice and MultipleChoice is that with SingleChoice the user can only select one answer, while with MultipleChoice the user can select multiple answers. Apart from that, they are the same for the build configuration. Add Likert / matrix question A matrix question allows you to ask a question with multiple items and a scale. The user can select one answer for each item. Properties Property Required Type Description Default title ✓ string The question description string The description of the question type ✓ string set to Matrix items ✓ string[] An array of possible choices (each item can be a string or an object; see note above) itemsShuffled boolean If set to true , the order of the items/choices will be shuffled false isRequired boolean If set to false , the user can skip the question true scale string[]|array The scale the user can choose from, e.g. 'Bad', 'Medium', 'Good' 5 scale items from 'Strongly agree' to 'Strongly disagree' isNaEnabled boolean If set to true , the user can select 'Not applicable' for each item false isSingleChoiceEnabled boolean If set to true , the user can select only one answer for each item true layoutType string The layout of the items, either Rows or Columns Rows Example object Here is an example with only the required configuration properties: {\n \"title\" : \"I am happy with the following aspects of Riddle.\" ,\n \"description\" : \"Choose one from 'Strongly agree' to 'Strongly disagree'\" ,\n \"type\" : \"Matrix\" ,\n \"items\" : [\n \"Design\" ,\n \"Usability\" ,\n \"Performance\"\n ]\n }\n For the next example we additionally shuffle the items, customize the scale (and its values) and set the other flags. {\n \"title\" : \"I am happy with the following aspects of Riddle.\" ,\n \"description\" : \"Choose one from 'Bad' to 'Good'\" ,\n \"type\" : \"Matrix\" ,\n \"items\" : [\n \"Design\" ,\n \"Usability\" ,\n \"Performance\"\n ],\n \"itemsShuffled\" : true ,\n \"scale\" : {\n \"0\" : \"Bad\" ,\n \"2\" : \"Medium\" ,\n \"4\" : \"Good\"\n },\n \"isNaEnabled\" : true ,\n \"isSingleChoiceEnabled\" : false\n }\n As you can see in the above example the scale property can be an array of strings, where the index of the string is the value that will be saved in the database (e.g. user has selected Bad => scale value 0 will be saved as the response.). By default the scale values are a series of auto incremented integers. Simply omit the keys/indices to use the default scale values, e.g. {\"scale\": [\"Bad\", \"Medium\", \"Good\"]} . Add order it question An order it question allows you to ask a question with multiple items and the user can drag and drop them into the order they prefer. Properties Property Required Type Description Default title ✓ string The question description string The description of the question type ✓ string set to Order items ✓ string[] An array of possible choices (each item can be a string or an object; see note above) itemsShuffled boolean If set to true , the order of the items/choices will be shuffled false isRequired boolean If set to false , the user can skip the question true layoutType string The layout of the items, either Rows or Columns Rows rankFormat string How the ranks of the items are displayed, either Number , Letter or NumberEnum Number upDownButtons boolean If set to true , up and down buttons are shown to change the order of the items instead of drag and drop true Example object {\n \"title\" : \"What are your favorite animals?\" ,\n \"description\" : \"Drag and drop the items into the order you prefer\" ,\n \"type\" : \"Order\" ,\n \"items\" : [\n \"Dog\" ,\n \"Cat\" ,\n \"Bird\" ,\n \"Fish\"\n ],\n \"layoutType\" : \"Rows\" ,\n \"rankFormat\" : \"Number\" ,\n \"upDownButtons\" : false\n }\n Add upvote question An upvote question allows you to ask a question with multiple items and the user can select one or more items to upvote. Properties Property Required Type Description Default title ✓ string The question description string The description of the question type ✓ string set to Upvote items ✓ string[] An array of possible choices (each item can be a string or an object; see note above) itemsShuffled boolean If set to true , the order of the items/choices will be shuffled false isRequired boolean If set to false , the user can skip the question true layoutType string The layout of the items, either Rows or Columns Rows maxVotes integer The maximum number of items the user can upvote 1 Example object {\n \"title\" : \"What do you like most about Riddle?\" ,\n \"description\" : \"Select one or more items\" ,\n \"type\" : \"Upvote\" ,\n \"items\" : [\n \"Design\" ,\n \"Usability\" ,\n \"Performance\"\n ],\n \"itemsShuffled\" : true ,\n \"maxVotes\" : 2\n }\n Add Net Promoter Score question Properties Property Required Type Description Default title ✓ string The question description string The description of the question type ✓ string set to NetPromoterScore positiveTitle ✓ string The title of the positive score, e.g. I completely agree negativeTitle ✓ string The title of the negative score, e.g. I completely disagree Example object {\n \"title\" : \"How likely are you to recommend Riddle to a friend?\" ,\n \"description\" : \"Select one of the options below\" ,\n \"type\" : \"NetPromoterScore\" ,\n \"positiveTitle\" : \"I completely agree\" ,\n \"negativeTitle\" : \"I completely disagree\"\n }\n Add Rate It question Properties Property Required Type Description Default title ✓ string The question description string The description of the question type ✓ string set to RateIt items ✓ string[] An array of possible choices (each item can be a string or an object; see note above) itemsShuffled boolean If set to true , the order of the items/choices will be shuffled false isRequired boolean If set to false , the user can skip the question true layoutType string The layout of the items, either Rows or Columns Rows displayType string The display type of the items, either Stars or Numbers Stars starCount integer The number of stars to display (if displayType is set to Stars ); allowed range 1-10 5 numberMin integer The minimum number to display (if displayType is set to Numbers ); allowed range -10 to 10 1 numberMax integer The maximum number to display (if displayType is set to Numbers ); allowed range -10 to 10 10 Note: starCount and numberMin / numberMax are mutually exclusive. If displayType is set to Stars , you cannot set numberMin or numberMax . If displayType is set to Numbers , you cannot set starCount . Setting the properties for the wrong displayType will throw a validation error. Example object {\n \"title\" : \"How would you rate Riddle?\" ,\n \"type\" : \"RateIt\" ,\n \"items\" : [\n \"Design\" ,\n \"Usability\" ,\n \"Performance\"\n ],\n \"itemsShuffled\" : true\n }\n Add Swiper question Properties Property Required Type Description Default title ✓ string The question description string The description of the question type ✓ string set to Swiper items string[] An array with exactly two PollSwiperItemBlock items (FIRST: Negative, SECOND: Positive); described in detail below colorLikeButtonBackground string The background color of the like button #59e1abff colorLikeButtonIcon string The color of the like button icon #000000ff colorLikeButtonText string The color of the like button text #000000ff colorDislikeButtonBackground string The background color of the dislike button #000000ff colorDislikeButtonIcon string The color of the dislike button icon #ffffff colorDislikeButtonText string The color of the dislike button text #ffffff Specifying negative / positive items If you want to specify the negative / positive items in more detail, pass two PollSwiperItemBlock objects in the items array. Each of these blocks has the following properties: Property Required Type Description Default title string The title of the item emoji string The emoji to display in the item, e.g. 👍 or 👎 media string The URL of the image or video to display in the item Note : Only one of title , emoji , and media can be set. If you set title , the emoji and media will not be displayed. If you set emoji , the title and media will not be displayed. If you set media , the title and emoji will not be displayed. Example object {\n \"title\" : \"How do you feel about Riddle?\" ,\n \"description\" : \"Swipe left or right to answer\" ,\n \"type\" : \"Swiper\" ,\n \"items\" : [\n {\n \"emoji\" : \"😞\"\n },\n {\n \"emoji\" : \"😍\"\n }\n ]\n }\n Add Reaction Poll question A reaction poll allows users to react to a question using a scale, e.g. from 'strongly disagree' to 'strongly agree'. Properties Property Required Type Description Default title ✓ string The question description string The description of the question type ✓ string set to Reaction reactionType string The type of reaction (allowed: AgreeDisagree , LikeDislike ) reactionScale string[] Custom scale, e.g. \"Bad\", \"Okay\", \"Good\" Note: You need to set either reactionType or reactionScale . If you set a custom reactionScale , the reactionType will be ignored. Note: If you set a custom reactionScale , it must contain at least 3 items and an odd number of items – an even number of items will be rejected. Example object with predefined reaction scale {\n \"title\" : \"How do you feel about Riddle?\" ,\n \"description\" : \"Select one of the options below\" ,\n \"type\" : \"Reaction\" ,\n \"reactionType\" : \"AgreeDisagree\"\n }\n Example object with custom reaction scale {\n \"title\" : \"How do you feel about Riddle?\" ,\n \"description\" : \"Select one of the options below\" ,\n \"type\" : \"Reaction\" ,\n \"reactionScale\" : [\n \"Bad\" ,\n \"Okay\" ,\n \"Good\"\n ]\n }\n Result page In a poll only one result page is allowed which is specified in build.result . Basic results have a title and description property. Example in build.result : {\n \"title\" : \"Thank you!\" ,\n \"description\" : \"We are happy to have you here\"\n }\n If you want to create complex result pages with texts, images, answered blocks, ... click here to learn how to build advanced result pages . Full example {\n \"type\" : \"Poll\" ,\n \"build\" : {\n \"title\" : \"Poll example (Builder API)\" ,\n \"blocks\" : [\n {\n \"title\" : \"What's your favorite color?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"Red\" ,\n \"Blue\" ,\n \"Green\" ,\n \"Yellow\"\n ]\n },\n {\n \"title\" : \"What are your favorite animals?\" ,\n \"type\" : \"MultipleChoice\" ,\n \"items\" : [\n \"Dog\" ,\n \"Cat\" ,\n \"Bird\" ,\n \"Fish\"\n ]\n },\n {\n \"title\" : \"I am happy with the following aspects of Riddle.\" ,\n \"description\" : \"Choose one from 'Bad' to 'Good'\" ,\n \"type\" : \"Matrix\" ,\n \"items\" : [\n \"Design\" ,\n \"Usability\" ,\n \"Performance\"\n ]\n },\n {\n \"title\" : \"What are your favorite animals?\" ,\n \"description\" : \"Drag and drop the items into the order you prefer\" ,\n \"type\" : \"Order\" ,\n \"items\" : [\n \"Dog\" ,\n \"Cat\" ,\n \"Bird\" ,\n \"Fish\"\n ]\n },\n {\n \"title\" : \"What do you like most about Riddle?\" ,\n \"description\" : \"Select one or more items\" ,\n \"type\" : \"Upvote\" ,\n \"items\" : [\n \"Design\" ,\n \"Usability\" ,\n \"Performance\"\n ]\n },\n {\n \"title\" : \"How likely are you to recommend Riddle to a friend?\" ,\n \"description\" : \"Select one of the options below\" ,\n \"type\" : \"NetPromoterScore\" ,\n \"positiveTitle\" : \"I completely agree\" ,\n \"negativeTitle\" : \"I completely disagree\"\n },\n {\n \"title\" : \"Hot or not: Riddle\" ,\n \"description\" : \"Swipe left or right to answer\" ,\n \"type\" : \"Swiper\" ,\n \"items\" : [\n {\n \"emoji\" : \"😞\"\n },\n {\n \"emoji\" : \"😍\"\n }\n ]\n },\n {\n \"title\" : \"How do you feel about Riddle?\" ,\n \"description\" : \"Select one of the options below\" ,\n \"type\" : \"Reaction\" ,\n \"reactionType\" : \"AgreeDisagree\"\n }\n ],\n \"result\" : {\n \"title\" : \"Thank you!\" ,\n \"description\" : \"We are happy to have you here\"\n }\n }\n }\n Next steps Now that you know the basics of building a poll, you might want to learn how to: Add form fields to your Riddle Use the Ad block to monetize your Riddle or add Content blocks Define the publish settings: Enable DOI, email automation, add integrations, and more Define the preset and palette you want to use Define the logic / flow of your Riddle Build an advanced result page Add media, such as images, videos, and social media content html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":91,"path":92,"dir":75,"title":93,"description":94,"keywords":95,"body":104},"content:15.Api:3.Build Riddles:3.Riddle types and other blocks:2.Quiz.md","/api/build-riddles/riddle-types-and-other-blocks/quiz","Create Quiz - Build Riddles","Learn how to build Quizzes via API",[96,97,98,99,100,101,102,103,88,16],"Add single/multiple choice questions","Add \"Type the answer\" questions","Add \"Order it\" questions","Add flashcard questions","Add TypeRush questions","Answer explanations","Answer explanations & scores per item","Result pages"," Create Quiz When building a quiz you can add: Quiz questions with answer explanations: SingleChoice , MultipleChoice , and TextEntry (\"Type the answer\") Quiz questions of type Order , Flashcard , and TypeRush Form fields General blocks Multiple result pages: segment users based on their score Add single/multiple choice questions Properties Property Required Type Description Default title ✓ string title of the question description string description of the question media string media URL to display an image or video with the question type ✓ string set to SingleChoice or MultipleChoice items ✓ object key-value array, consisting of the question as the key and the value is a boolean value indicating if the answer is correct itemsShuffled boolean If set to true , the order of the items/choices will be shuffled false itemsRightOrWrong boolean If set to true , the items will be shown as right or wrong true isRequired boolean If set to false , the user can skip the question true score integer The score the user gets for answering this question correctly 1 explanation object An explanation object for the correct answer; learn more wrongExplanation object An explanation object for the incorrect answer; learn more explanationPosition string The position of the explanation (if given), either BelowAnswers or Overlay Overlay layoutType string The layout of the items, either Rows or Columns Rows Example object {\n \"title\" : \"The best noodles?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Spaghetti\" : true ,\n \"Fusilli\" : false\n }\n }\n In this example Spaghetti would be the correct choice. Please note that only one answer option can be correct for SingleChoice questions. If you try to add more than one correct answer the API will return an error. Want to set answer explanations or the score per item? Learn more Add \"Type the answer\" questions Properties Property Required Type Description Default title ✓ string title of the block description string description of the block media string media URL to display an image or video with the question type ✓ string set to TextEntry answers ✓ string[] an array of possible answers isRequired boolean If set to false , the user can skip the question true ignoreCase boolean set to true to ignore the case of the answer (e.g. \"hello\" and \"Hello\" would be considered the same) false ignoreSpaces boolean set to true to ignore spaces in the answer (e.g. \"hello\" and \"h e l l o\" would be considered the same) false lives integer set to a number to give the user multiple attempts to answer the question 1 livesText string the label for lives unlimitedLives boolean set to true to give the user unlimited attempts to answer the question false score integer the score the user gets for answering this question correctly 1 explanation object An explanation object for the correct answer; learn more wrongExplanation object An explanation object for the incorrect answer; learn more explanationPosition string The position of the explanation (if given), either BelowAnswers or Overlay Overlay Example object {\n \"title\" : \"Type 'hello' in either Italian, German, or French.\" ,\n \"type\" : \"TextEntry\" ,\n \"answers\" : [ \"Ciao\" , \"Hallo\" , \"Bonjour\" ]\n }\n Optional properties By default the user must type the exact answer to get the question correct, only has one life/attempt, cannot skip the question, and receives no explanation. To change this behavior you can set ignoreCase , ignoreSpaces , lives , isRequired , and the explanation properties: {\n \"title\" : \"Type 'hello' in either Italian, German, or French.\" ,\n \"type\" : \"TextEntry\" ,\n \"answers\" : [ \"Ciao\" , \"Hallo\" , \"Bonjour\" ],\n \"isRequired\" : false ,\n \"ignoreCase\" : true ,\n \"ignoreSpaces\" : true ,\n \"lives\" : 3 ,\n \"explanation\" : {\n \"title\" : \"Correct!\" ,\n \"description\" : \"Ciao, Hallo, and Bonjour all mean 'hello'\"\n },\n \"wrongExplanation\" : {\n \"title\" : \"Incorrect!\" ,\n \"description\" : \"Ciao, Hallo, and Bonjour all mean 'hello'\"\n },\n \"explanationPosition\" : \"BelowAnswers\"\n }\n Add \"Order it\" questions Properties Property Required Type Description Default title ✓ string title of the question description string description of the question type ✓ string set to Order items ✓ string an array of strings/items to order itemsShuffled boolean If set to true , the order of the items/choices will be shuffled false isRequired boolean If set to false , the user can skip the question true score integer the score the user gets for answering this question correctly 1 layoutType string set to Rows or Columns Rows rankFormat string set to Number , Letter , or NumberEnum Number showCorrectAnswerButton boolean set to true to show the correct answer button false guessesAreUnlimited boolean set to true to allow unlimited guesses; if you include this property at all (with any value, including false ), you cannot also set the other guesses properties below. false guesses integer set to a number to give the user multiple attempts to answer the question 1 guessesIcon string set to Heart , Numeric , or X Heart guessesDisplayLabel string provide a string to display the # of remaining guesses upDownButtons boolean If set to true , up and down buttons are shown to change the order of the items instead of drag and drop true explanation object An explanation object for the correct answer; learn more wrongExplanation object An explanation object for the incorrect answer; learn more explanationPosition string The position of the explanation (if given), either BelowAnswers or Overlay Overlay Example objects An example with only the required options: {\n \"title\" : \"Order the following colors from lightest to darkest.\" ,\n \"type\" : \"Order\" ,\n \"items\" : [ \"red\" , \"blue\" , \"green\" ]\n }\n An example with extensive configuration: {\n \"title\" : \"Order the following colors from lightest to darkest.\" ,\n \"type\" : \"Order\" ,\n \"items\" : [ \"red\" , \"blue\" , \"green\" ],\n \"itemsShuffled\" : true ,\n \"isRequired\" : false ,\n \"score\" : 5 ,\n \"layoutType\" : \"Rows\" ,\n \"rankFormat\" : \"Number\" ,\n \"showCorrectAnswerButton\" : true ,\n \"guesses\" : 3 ,\n \"guessesIcon\" : \"Heart\" ,\n \"guessesDisplayLabel\" : \"Cat lives\" ,\n \"upDownButtons\" : false ,\n \"explanation\" : {\n \"title\" : \"Correct!\" ,\n \"description\" : \"The correct order is red, blue, green\"\n },\n \"wrongExplanation\" : {\n \"title\" : \"Incorrect!\" ,\n \"description\" : \"The correct order is red, blue, green\"\n },\n \"explanationPosition\" : \"BelowAnswers\"\n }\n Want to set the score per item? Learn more Add flashcard questions Properties Property Required Type Description Default title ✓ string title of the question description string description of the question media string media URL to display an image or video with the question type ✓ string set to Flashcard hint string hint for the question score integer the score the user gets for answering this question correctly 1 backside ✓ object object with title and optionally description + media ; this is the content the user sees when flipping the flashcard Example object {\n \"title\" : \"Capital of germany\" ,\n \"description\" : \"Germany is a country in Europe\" ,\n \"hint\" : \"Starts with a 'B'\" ,\n \"type\" : \"Flashcard\" ,\n \"backside\" : {\n \"title\" : \"Berlin\" ,\n \"description\" : \"Berlin is the capital of Germany\"\n }\n }\n Add TypeRush questions Properties Property Required Type Description Default title ✓ string title of the question description string description of the question media string media URL to display an image or video with the question type ✓ string set to TypeRush items ✓ string |object either an array of strings or an array of objects, each containing answers (string ), score (integer), and optionally hint (string) and media (string) rankFormat string set to Number , Letter , or NumberEnum Number isRequired boolean If set to false , the user can skip the question true isIgnoringCase boolean set to true to ignore the case of the answer (e.g. \"hello\" and \"Hello\" would be considered the same) true isIgnoringSpaces boolean set to true to ignore spaces in the answer (e.g. \"hello\" and \"h e l l o\" would be considered the same) true isHintEnabled boolean set to true to enable hints for each item true score integer the score the user gets for answering this question correctly; can either be set on question or answer level; must be >= 1 1 Example: Simple TypeRush object {\n \"title\" : \"Name Germany's three biggest cities\" ,\n \"description\" : \"A very hard question\" ,\n \"type\" : \"TypeRush\" ,\n \"items\" : [ \"Berlin\" , \"Hamburg\" , \"Munich\" ],\n \"score\" : 5\n }\n Please note that if you provide a score for the whole question, you must not provide scores for individual answers, and vice versa; if you try to set both, the API will return an error. Example: Sophisticated TypeRush object {\n \"title\" : \"Name Germany's three biggest cities\" ,\n \"description\" : \"A very hard question\" ,\n \"type\" : \"TypeRush\" ,\n \"items\" : [\n {\n \"answers\" : [ \"Berlin\" ],\n \"score\" : 2 ,\n \"hint\" : \"Starts with B\"\n },\n {\n \"answers\" : [ \"Hamburg\" ],\n \"score\" : 3 ,\n \"hint\" : \"Starts with H\"\n },\n {\n \"answers\" : [ \"Munich\" ],\n \"score\" : 4 ,\n \"hint\" : \"Starts with M\"\n }\n ],\n \"rankFormat\" : \"Letter\" ,\n \"isRequired\" : false ,\n \"isIgnoringSpaces\" : false ,\n \"isHintEnabled\" : false\n }\n Answer explanations You can add an answer explanation to SingleChoice , MultipleChoice , and TextEntry questions. To do this add an explanation object to the quiz question block configuration, consisting of: Property Required Type Description title ✓ string The title of the explanation description string The description of the explanation media string A media URL to an image to display as part of the explanation If you wish to have an incorrect answer explanation, you can add the wrongExplanation with the same properties as explanation to the block. If only explanation is provided, it will be shown as an explanation for both correct and incorrect answers. To modify where the explanation is shown, you can set the explanationPosition property to either BelowAnswers or Overlay . If set to BelowAnswers , the explanation will be shown below the answer options. If set to Overlay , the explanation will be shown in an overlay on top of the question (default: Overlay ). Example object {\n \"title\" : \"Type 'hello' in either Italian, German, or French.\" ,\n \"type\" : \"TextEntry\" ,\n \"answers\" : [ \"Ciao\" , \"Hallo\" , \"Bonjour\" ],\n \"explanation\" : {\n \"title\" : \"My correct explanation\" ,\n \"description\" : \"My correct explanation description\" ,\n \"media\" : \"https://example.com/correct-image.jpg\"\n },\n \"wrongExplanation\" : {\n \"title\" : \"My wrong explanation\" ,\n \"description\" : \"My wrong explanation description\" ,\n \"media\" : \"https://example.com/wrong-image.jpg\"\n },\n \"explanationPosition\" : \"BelowAnswers\"\n }\n Answer explanations & scores per item Just as in the Riddle Creator, you can provide an explanation and score for each item/answer individually. This works for each Quiz block type with items, i.e. SingleChoice , MultipleChoice , Order . (In Order both a per-item score and explanation are supported) Please note that you must either provide an explanation + a score for each answer, one for all, or none. Per-item score values must be >= 0; negative scores will be rejected. Example SingleChoice object: {\n \"title\" : \"The best noodles?\" ,\n \"type\" : \"SingleChoice\" ,\n \"explanationPosition\" : \"BelowAnswers\" ,\n \"items\" : {\n \"Spaghetti\" : {\n \"isCorrect\" : true ,\n \"score\" : 2 ,\n \"explanation\" : {\n \"title\" : \"Correct!\" ,\n \"description\" : \"Spaghetti is the best noodle\"\n }\n },\n \"Fusilli\" : {\n \"isCorrect\" : false ,\n \"score\" : 0 ,\n \"explanation\" : {\n \"title\" : \"Incorrect!\" ,\n \"description\" : \"Spaghetti is the best noodle\"\n }\n }\n }\n }\n In the example above Spaghetti would be the correct choice and the user would get 2 points for selecting it. If they select Fusilli they would get 0 points and see the explanation \"Spaghetti is the best noodle\". This results in a maximum score of 2. Note: The optional property explanationPosition must be set on the block level although the explanations are set on the item level. Example Order object: {\n \"title\" : \"The best noodles?\" ,\n \"type\" : \"Order\" ,\n \"items\" : {\n \"Spaghetti\" : {\n \"score\" : 2\n },\n \"Fusilli\" : {\n \"score\" : 1\n }\n }\n }\n In the example above Spaghetti would be the correct choice and the user would get 2 points for putting it into the right order index. If they select Fusilli as second they would get 1 points and see the explanation \"Spaghetti is the best noodle\". This results in a maximum score of 3. Result pages In a quiz you can specify multiple result pages to segment users based on their scores. For example users who score between 0-50% will see one result, users who score between 51-100% will see another result. Each result has a title , description , minPercentage , and maxPercentage property. As there can be multiple results, we store the results in an array in build.results : [\n {\n \"title\" : \"My result 0-30%\" ,\n \"description\" : \"Description 1\" ,\n \"minPercentage\" : 0 ,\n \"maxPercentage\" : 50\n },\n {\n \"title\" : \"My result 31-100%\" ,\n \"description\" : \"Description 2\" ,\n \"minPercentage\" : 51 ,\n \"maxPercentage\" : 100\n }\n ]\n If you want to create complex result pages with texts, images, answered blocks, ... click here to learn how to build advanced result pages . Full example Example with all available blocks + options: {\n \"type\" : \"Quiz\" ,\n \"build\" : {\n \"title\" : \"Quiz example (Builder API)\" ,\n \"blocks\" : [\n {\n \"title\" : \"What's the capital of Germany?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Berlin\" : true ,\n \"Lissabon\" : false ,\n \"Leipzig\" : false\n },\n \"explanation\" : {\n \"title\" : \"Correct!\" ,\n \"description\" : \"Berlin is the capital of Germany\"\n },\n \"wrongExplanation\" : {\n \"title\" : \"Incorrect!\" ,\n \"description\" : \"Berlin is the capital of Germany\"\n }\n },\n {\n \"title\" : \"What are valid colors in German?\" ,\n \"type\" : \"MultipleChoice\" ,\n \"items\" : {\n \"rot\" : true ,\n \"schwarz\" : true ,\n \"nero\" : false\n },\n \"explanation\" : {\n \"title\" : \"Correct!\" ,\n \"description\" : \"Only 'rot' and 'schwarz' are valid colors in German\"\n }\n },\n {\n \"title\" : \"Type 'hello' in either Italian, German, or French.\" ,\n \"type\" : \"TextEntry\" ,\n \"answers\" : [\n \"Ciao\" ,\n \"Hallo\" ,\n \"Bonjour\"\n ],\n \"explanation\" : {\n \"title\" : \"Correct!\" ,\n \"description\" : \"Ciao, Hallo, and Bonjour all mean 'hello'\"\n },\n \"wrongExplanation\" : {\n \"title\" : \"Incorrect!\" ,\n \"description\" : \"Ciao, Hallo, and Bonjour all mean 'hello'\"\n },\n \"ignoreCase\" : true ,\n \"ignoreSpaces\" : true ,\n \"lives\" : 3\n },\n {\n \"title\" : \"Order the following colors from lightest to darkest.\" ,\n \"type\" : \"Order\" ,\n \"items\" : [\n \"red\" ,\n \"blue\" ,\n \"green\"\n ],\n \"itemsShuffled\" : true ,\n \"guesses\" : 3\n },\n {\n \"title\" : \"Capital of Germany\" ,\n \"description\" : \"Germany is a country in Europe\" ,\n \"hint\" : \"Starts with a 'B'\" ,\n \"type\" : \"Flashcard\" ,\n \"backside\" : {\n \"title\" : \"Berlin\" ,\n \"description\" : \"Berlin is the capital of Germany\"\n }\n },\n {\n \"title\" : \"Name Germany's three biggest cities\" ,\n \"description\" : \"A very hard question\" ,\n \"type\" : \"TypeRush\" ,\n \"items\" : [\n {\n \"answers\" : [ \"Berlin\" ],\n \"score\" : 2 ,\n \"hint\" : \"Starts with B\"\n },\n {\n \"answers\" : [ \"Hamburg\" ],\n \"score\" : 3 ,\n \"hint\" : \"Starts with H\"\n },\n {\n \"answers\" : [ \"Munich\" ],\n \"score\" : 4 ,\n \"hint\" : \"Starts with M\"\n }\n ]\n }\n ],\n \"results\" : [\n {\n \"title\" : \"Not so good...\" ,\n \"description\" : \"There's room for improvement\" ,\n \"minPercentage\" : 0 ,\n \"maxPercentage\" : 50\n },\n {\n \"title\" : \"Well done!\" ,\n \"description\" : \"You're a winner\" ,\n \"minPercentage\" : 51 ,\n \"maxPercentage\" : 100\n }\n ]\n }\n }\n Next steps Now that you know the basics of building a quiz, you might want to learn how to: Add form fields to your Riddle Use the Ad block to monetize your Riddle or add Content blocks Connect your built Riddle to leaderboard(s) Define the publish settings: Enable DOI, email automation, add integrations, and more Define the preset and palette you want to use Define the logic / flow of your Riddle Build advanced result pages Add media, such as images, videos, and social media content html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":106,"path":107,"dir":75,"title":108,"description":109,"keywords":110,"body":111},"content:15.Api:3.Build Riddles:3.Riddle types and other blocks:3.Form.md","/api/build-riddles/riddle-types-and-other-blocks/form","Create Form - Build Riddles","Learn how to build Forms via API",[87,88,16]," Create Form Building a standalone form to exclusively collect user data can be done via the API. When building a form you can add: Form fields General blocks One result page Result page In a form only one result page is allowed which is specified in build.result . Basic results only consist of a title and description property. Example: {\n \"title\" : \"Thank you!\" ,\n \"description\" : \"We are happy to have you here\"\n }\n If you want to create complex result pages with texts, images, ... click here to learn how to build advanced result pages . Full example Note: The example below uses dynamic variables to personalize the result page. Click here to learn more about dynamic variables . {\n \"type\" : \"Form\" ,\n \"build\" : {\n \"title\" : \"My data collection form\" ,\n \"blocks\" : [\n {\n \"title\" : \"Please enter your data.\" ,\n \"type\" : \"FormBuilder\" ,\n \"fields\" : {\n \"Your email\" : \"Email\" ,\n \"Your name\" : \"Name\"\n }\n }\n ],\n \"result\" : {\n \"title\" : \"Thank you!\" ,\n \"description\" : \"Thank you for entering your data %name. We will get back to you soon.\"\n }\n }\n }\n Next steps Now that you know the basics of building a form, you might want to learn how to: Add form fields to your Riddle Use the Ad block to monetize your Riddle or add Content blocks Define the publish settings: Enable DOI, email automation, add integrations, and more Define the preset and palette you want to use Define the logic / flow of your Riddle Build an advanced result page Add media, such as images, videos, and social media content html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":113,"path":114,"dir":75,"title":115,"description":116,"keywords":117,"body":122},"content:15.Api:3.Build Riddles:3.Riddle types and other blocks:4.Form fields.md","/api/build-riddles/riddle-types-and-other-blocks/form-fields","Add form fields - Build Riddles","Learn how to build Form fields via API",[118,119,120,121],"Add a form builder","Customizing form fields","Adding single standalone form field blocks","Embed an already published form"," Add form fields Form fields can be added to any Riddle type (Poll, Quiz, Form, Predictor, Personality). You can choose between two options: Add a form builder to this Riddle Add a single standalone form field block to this Riddle Embed an already published Riddle form from your (personal) project Embedding another form allows you to reuse a form you have already created (= central data collection) but also allows you to build more complex forms than with the builder API. Add a form builder Like any other block you might add, such as SingleChoice , you can add form fields to the Riddle build by adding a FormBuilder block item to the blocks array. Properties The form fields / builder block consists of: Property Required Type Description Default title ✓ string The title of the form builder description string The description of the form builder type ✓ string Set to FormBuilder fields ✓ object An object where the key is the field label and the value is the field type OR an advanced configuration object. The field type must be one of the available form fields isRequired boolean Whether the form is required; if set to false the form can be skipped false media string A media URL to display as part of the form builder Example The FormBuilder block isolated: {\n \"title\" : \"My form builder\" ,\n \"type\" : \"FormBuilder\" ,\n \"fields\" : {\n \"Your email\" : \"Email\" ,\n \"Your name\" : \"Name\"\n }\n }\n Used in a poll build: {\n \"type\" : \"Poll\" ,\n \"build\" : {\n \"title\" : \"My new poll\" ,\n \"blocks\" : [\n {\n \"title\" : \"The best noodles?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"Spaghetti\" ,\n \"Fusilli\"\n ]\n },\n {\n \"title\" : \"My form builder\" ,\n \"type\" : \"FormBuilder\" ,\n \"fields\" : {\n \"Your email\" : \"Email\" ,\n \"Your name\" : \"Name\"\n }\n }\n ],\n \"result\" : {\n \"title\" : \"Thank you!\" ,\n \"description\" : \"We are happy to have you here\"\n }\n }\n }\n Note: You can add as many form builders as you like as long as you stay within the 500 blocks limit . Available form fields Name Email Phone URL Number Country ShortText LongText DatePicker TimePicker Checkbox Content (see documentation below) Media (see documentation below) Radio buttons (see documentation below) Dropdown (see documentation below) Rating Please note that the field type you send to the API is case-sensitive. Customizing form fields All form fields can be further customized by converting the simple input string, e.g. Email , to an object. This allows you to further customize the field and how it behaves. Here is an example how an Email field can be customized inside a FormBuilder block: {\n \"title\" : \"My form builder\" ,\n \"type\" : \"FormBuilder\" ,\n \"fields\" : {\n \"Your email\" : {\n \"type\" : \"Email\" ,\n \"placeholder\" : \"Enter your email address\" ,\n \"isRequired\" : true ,\n \"requiredMessage\" : \"We will never share your email with anyone else.\"\n }\n }\n }\n Form field properties Each form field supports different options. This table illustrates what options are available for which type: Property Description Available for... description Description of the field all types placeholder Placeholder text Name, Email, Phone, URL, Number prefilledText Prefilled text Name, Email, Phone, URL, Number isRequired Whether the field is required all types requiredMessage Message shown when the field is required but not filled all types isHidden Whether the field is hidden; useful in combination with the Riddle data layer Name, Email, Phone, URL, Number regex Regex to validate the field Name, Email, Phone, URL, Number regexValidationMessage Message shown when the regex validation fails Name, Email, Phone, URL, Number checkboxText Text shown next to the checkbox Checkbox starCount Number of rating stars to display; allowed range 0-10 Rating Adding radio buttons and dropdowns The RadioButtons and Dropdown field types can be used to create a list of options. You can add as many options as you like in the items array. Note: On the public API, the fields object of a FormBuilder block (and the items array of a Dropdown or RadioButtons field) is limited to a maximum of 100 entries. Example FormBuilder object: {\n \"title\" : \"My form builder\" ,\n \"type\" : \"FormBuilder\" ,\n \"fields\" : {\n \"Your favorite color\" : {\n \"type\" : \"RadioButtons\" ,\n \"items\" : [\n \"Red\" ,\n \"Green\" ,\n \"Blue\"\n ]\n },\n \"Your favorite animal\" : {\n \"type\" : \"Dropdown\" ,\n \"items\" : [\n \"Dog\" ,\n \"Cat\" ,\n \"Fish\"\n ]\n }\n }\n }\n Adding content and media fields The Content and Media field types can be used to add additional information to your form. Example FormBuilder with Content and Media fields: {\n \"title\" : \"My form builder\" ,\n \"type\" : \"FormBuilder\" ,\n \"fields\" : {\n \"Introduction\" : {\n \"type\" : \"Content\" ,\n \"text\" : \"\u003Ch2>Welcome to the survey!\u003C/h2>\u003Cp>Please fill out the form below.\u003C/p>\"\n },\n \"Cover\" : {\n \"type\" : \"Media\" ,\n \"media\" : \"https://example.com/image.jpg\"\n }\n }\n }\n Note: Every field in the fields object requires a key, even though the Media field does not display a label. You can use any arbitrary key (e.g. \"Cover\" ) for the Media field. Adding single standalone form field blocks If you want to add a single form field instead of a full form builder, you can do so by adding the respective form field type directly to the blocks array. Property Required Type Description Default title ✓ string The title of the form field description string The description of the form field type ✓ string Set to FormField fieldType ✓ string The type of the form field, must be one of the available form fields media string A media URL to display as part of the form field label string A label shown alongside the form field In addition to the common properties, each form field type supports the same options as described in the Customizing form fields section. Full Form example {\n \"type\" : \"Form\" ,\n \"build\" : {\n \"title\" : \"Form example (Builder API)\" ,\n \"blocks\" : [\n {\n \"title\" : \"Your favorite animal\" ,\n \"type\" : \"FormField\" ,\n \"fieldType\" : \"Dropdown\" ,\n \"items\" : [\n \"Dog\" ,\n \"Cat\" ,\n \"Fish\"\n ]\n },\n {\n \"title\" : \"Your email\" ,\n \"type\" : \"FormField\" ,\n \"fieldType\" : \"Email\" ,\n \"placeholder\" : \"Enter your email address\" ,\n \"isRequired\" : true ,\n \"requiredMessage\" : \"We will never share your email with anyone else.\"\n }\n ]\n }\n }\n Embed an already published form You can embed a form from your (personal) project by adding a block of the FormSelect type to the blocks array. Properties The form select block consists of: Property Required Type Description form ✓ string The UUID of the form you want to embed Example The FormSelect block isolated: {\n \"type\" : \"FormSelect\" ,\n \"form\" : \"hQ3SYWur\"\n }\n Used in a poll build: {\n \"type\" : \"Poll\" ,\n \"build\" : {\n \"title\" : \"My new poll\" ,\n \"blocks\" : [\n {\n \"title\" : \"The best noodles?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"Spaghetti\" ,\n \"Fusilli\"\n ]\n },\n {\n \"type\" : \"FormSelect\" ,\n \"form\" : \"hQ3SYWur\"\n }\n ],\n \"result\" : {\n \"title\" : \"Thank you!\" ,\n \"description\" : \"We are happy to have you here\"\n }\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":124,"path":125,"dir":75,"title":126,"description":127,"keywords":128,"body":130},"content:15.Api:3.Build Riddles:3.Riddle types and other blocks:5.Personality.md","/api/build-riddles/riddle-types-and-other-blocks/personality","Create a Personality Test - Build Riddles","Learn how to build Personality Tests via API",[129,96,87,88,16],"Setting personalities"," Create Personality Test When building a personality test you can add: SingleChoice and MultipleChoice questions Form fields General blocks One result page Setting personalities For each personality test build configuration you must define at least two personalities . This is done in the personalities property of the build object. Properties Property Required Type Description Default title ✓ string The title of the personality description string The description of the personality media string A media URL to an image to display as part of the personality Example For the example let's add a SingleChoice question (which is described further in the next section): {\n \"type\" : \"Personality\" ,\n \"build\" : {\n \"personalities\" : [\n {\n \"title\" : \"Introvert\" ,\n \"description\" : \"Prefers solitary activities and quiet environments.\" ,\n \"media\" : \"https://example.com/introvert.jpg\"\n },\n {\n \"title\" : \"Extrovert\" ,\n \"description\" : \"Enjoys socializing and being around others.\" ,\n \"media\" : \"https://example.com/extrovert.jpg\"\n }\n ],\n \"blocks\" : [\n {\n \"title\" : \"Do you enjoy social gatherings?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Yes\" : {\n \"scores\" : [ 0 , 1 ]\n },\n \"No\" : {\n \"scores\" : [ 1 , 0 ]\n }\n }\n }\n ]\n }\n }\n Add single/multiple choice questions Properties Property Required Type Description Default title ✓ string title of the question description string The description of the question media string A media URL to an image to display as part of the question type ✓ string set to SingleChoice or MultipleChoice items ✓ object key-value array, consisting of the question as the key and the value is an object, see specification below itemsShuffled boolean If set to true , the order of the items/choices will be shuffled false layoutType string The layout of the items, either Rows or Columns Rows Example object {\n \"title\" : \"Do you enjoy social gatherings?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Yes\" : {\n \"scores\" : [ 0 , 1 ]\n },\n \"No\" : {\n \"scores\" : [ 1 , 0 ]\n }\n }\n }\n Each item in the items object consists of: Property Required Type Description scores ✓ integer[] An array of integers representing the score for each personality. The order of the scores must match the order of the personalities defined in the personalities array. description string The description of the item media string A media URL to an image to display as part of the item Note: The items object of a SingleChoice / MultipleChoice question and the personalities array are each limited to a maximum of 100 entries. Result page In a personality test only one result page is allowed which is specified in build.result . Basic results have a title and description property. Example in build.result : {\n \"title\" : \"Thank you!\" ,\n \"description\" : \"We are happy to have you here\"\n }\n Tip: The \"winning personality\" and \"other personalities\" are available as blocks in the result page (also used in the full example below). Use them along text, images, etc to create a more engaging result experience. Learn more Full example {\n \"type\" : \"Personality\" ,\n \"build\" : {\n \"title\" : \"Personality example (Builder API)\" ,\n \"personalities\" : [\n {\n \"title\" : \"Pikachu\" ,\n \"description\" : \"You are energetic and love to be around friends.\"\n },\n {\n \"title\" : \"Bulbasaur\" ,\n \"description\" : \"You are calm and enjoy nature.\"\n }\n ],\n \"blocks\" : [\n {\n \"title\" : \"Which vegetables do you like?\" ,\n \"type\" : \"MultipleChoice\" ,\n \"items\" : {\n \"Carrot\" : {\n \"scores\" : [\n 0 ,\n 1\n ]\n },\n \"Broccoli\" : {\n \"scores\" : [\n 1 ,\n 0\n ]\n },\n \"Spinach\" : {\n \"scores\" : [\n 0 ,\n 1\n ]\n }\n }\n },\n {\n \"title\" : \"What is your favorite time of the day?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Morning\" : {\n \"scores\" : [\n 1 ,\n 0\n ]\n },\n \"Afternoon\" : {\n \"scores\" : [\n 1 ,\n 0\n ]\n },\n \"Evening\" : {\n \"scores\" : [\n 0 ,\n 1\n ]\n }\n }\n }\n ],\n \"result\" : {\n \"blocks\" : [\n {\n \"type\" : \"WinningPersonality\"\n },\n {\n \"type\" : \"Text\" ,\n \"text\" : \"\u003Ch2>Thank you for taking the test!\u003C/h2>\u003Cp>We hope you enjoyed finding out which pokemon matches your personality.\u003C/p>\"\n },\n {\n \"type\" : \"OtherPersonalities\"\n },\n {\n \"type\" : \"Share\" ,\n \"title\" : \"Share this personality test!\"\n }\n ]\n }\n }\n }\n Next steps Now that you know the basics of building a personality test, you might want to learn how to: Add form fields to your Riddle Use the Ad block to monetize your Riddle or add Content blocks Define the publish settings: Enable DOI, email automation, add integrations, and more Define the preset and palette you want to use Define the logic / flow of your Riddle Build an advanced result page Add media, such as images, videos, and social media content html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":132,"path":133,"dir":75,"title":134,"description":135,"keywords":136,"body":138},"content:15.Api:3.Build Riddles:3.Riddle types and other blocks:6.Predictor.md","/api/build-riddles/riddle-types-and-other-blocks/predictor","Create Predictor - Build Riddles","Learn how to build Predictors via API",[137,87,88,16],"GuessTheScore / PickTheWinner"," Create Predictor When building a predictor you can add: Predictor questions: GuessTheScore and PickTheWinner Form fields General blocks One result page GuessTheScore / PickTheWinner Both types are configuration-wise exactly the same. The only difference is that GuessTheScore has a different UI/intention than PickTheWinner . Both work in the same way - a new item gets added to build.blocks , consisting of: title : the question title items : the predictor items Note: items must contain exactly 2 items - no more, no less - for both GuessTheScore and PickTheWinner . Example: {\n \"title\" : \"Who will win?\" ,\n \"type\" : \"PickTheWinner\" ,\n \"items\" : [\n {\n \"title\" : \"Team A\"\n },\n {\n \"title\" : \"Team B\"\n }\n ]\n }\n The example above is very basic - if you want to go beyond that, the following optional properties can be set for each item in items : backgroundImage : the URL of the background image logo : the URL of the logo image; e.g. logo of a sports team backgroundColor : the background color of the item textColor : the text color of the item Example with all optional properties set: {\n \"title\" : \"Who will win?\" ,\n \"type\" : \"PickTheWinner\" ,\n \"items\" : [\n {\n \"title\" : \"Team A\" ,\n \"backgroundImage\" : \"https://www.example.com/image.jpg\" ,\n \"logo\" : \"https://www.example.com/logo.jpg\" ,\n \"backgroundColor\" : \"#FF0000\" ,\n \"textColor\" : \"#FFFFFF\"\n },\n {\n \"title\" : \"Team B\" ,\n \"backgroundImage\" : \"https://www.example.com/image.jpg\" ,\n \"logo\" : \"https://www.example.com/logo.jpg\" ,\n \"backgroundColor\" : \"#0000FF\" ,\n \"textColor\" : \"#FFFFFF\"\n }\n ]\n }\n Note: Using both a background image and a color does not make sense; it is only written here to show all possible properties. Please choose one of both. Note: Do not supply an id property for predictor items - IDs are automatically assigned as 0 and 1 , and requests that include an id are rejected. Result page In a predictor only one result page is allowed which is specified in build.result . Basic results have a title and description property. Example: {\n \"title\" : \"Thank you!\" ,\n \"description\" : \"We are happy to have you here\"\n }\n If you want to create complex result pages with texts, images, answered blocks, ... click here to learn how to build advanced result pages . Full example {\n \"type\" : \"Predictor\" ,\n \"build\" : {\n \"title\" : \"Predictor example (Builder API)\" ,\n \"blocks\" : [\n {\n \"title\" : \"Who will win?\" ,\n \"type\" : \"PickTheWinner\" ,\n \"items\" : [{\n \"title\" : \"Team A\" ,\n \"backgroundColor\" : \"#FF0000\" ,\n \"textColor\" : \"#FFFFFF\"\n },\n {\n \"title\" : \"Team B\" ,\n \"backgroundColor\" : \"#0000FF\" ,\n \"textColor\" : \"#FFFFFF\"\n }\n ]\n },\n {\n \"title\" : \"What will be the score?\" ,\n \"type\" : \"GuessTheScore\" ,\n \"items\" : [\n {\n \"title\" : \"Team A\"\n },\n {\n \"title\" : \"Team B\"\n }\n ]\n }\n ],\n \"result\" : {\n \"title\" : \"Thank you!\" ,\n \"description\" : \"We are happy to have you here\"\n }\n }\n }\n Next steps Now that you know the basics of building a predictor, you might want to learn how to: Add form fields to your Riddle Use the Ad block to monetize your Riddle or add Content blocks Define the publish settings: Enable DOI, email automation, add integrations, and more Define the preset and palette you want to use Build an advanced result page Add media, such as images, videos, and social media content html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":140,"path":141,"dir":75,"title":142,"description":143,"keywords":144,"body":148},"content:15.Api:3.Build Riddles:3.Riddle types and other blocks:7.Leaderboard.md","/api/build-riddles/riddle-types-and-other-blocks/leaderboard","Create and connect to Leaderboard - Build Riddles","Learn how to build Leaderboards and connect Riddles to existing leaderboards via API",[145,146,147,28],"Create leaderboard","Connect Riddle to existing leaderboard","Fetch leaderboard entries"," Create and connect to Leaderboard Leaderboards enable you to create more engaging and interactive content with little to zero maintenance. Example use cases include: Creating & running a weekly quiz with a leaderboard Creating & running a Predictor for every match of your sports team You can work with leaderboards in two ways: Create a leaderboard : You can create a leaderboard and connect it to any Quizzes and Predictors right away. Connect to an existing leaderboard : You can connect any Riddle to an existing leaderboard. This is useful if you want to run multiple Riddles with the same leaderboard, e.g. a seasonal leaderboard. Create leaderboard Properties Property Required Type Description title ✓ string The title of the leaderboard riddleConnections string An array of UUIDs of the Riddles that should be connected to the leaderboard; maximum: 10 isEmailValidationRequired boolean Whether email verification is required to appear on the leaderboard Example object Creating an empty leaderboard (= no Riddle connections): {\n \"type\" : \"Leaderboard\" ,\n \"build\" : {\n \"title\" : \"My leaderboard\"\n }\n }\n Creating a leaderboard with Riddle connections: {\n \"type\" : \"Leaderboard\" ,\n \"build\" : {\n \"title\" : \"My leaderboard\" ,\n \"riddleConnections\" : [ \"SampleUUID1\" , \"SampleUUID2\" ]\n }\n }\n Connect Riddle to existing leaderboard Any built quizzes or predictors with at least one Name and Email field can be connected to an existing leaderboard. Note: Connecting multiple Riddles to a single leaderboard is only possible with our Enterprise subscription. Note: leaderboard.connections accepts between 1 and 3 connections (a maximum of 3 leaderboards can be connected to a single Riddle). Connection properties Property Required Type Description identifier string Overrides auto-detection of the leaderboard identifier field; either the label of a form field to use, or a dataLayer: variable nickname string Overrides auto-detection of the leaderboard nickname field; either the label of a form field to use, or a dataLayer: variable Example object Leaderboard connections are specified within build.leaderboard.connections . For example if I want to connect to the leaderboard with the UUID Fw5uSygx to my built Riddle the following build configuration is needed: {\n \"type\" : \"Quiz\" ,\n \"build\" : {\n \"title\" : \"My quiz\" ,\n \"blocks\" : [\n {\n \"title\" : \"What's the capital of Germany?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Berlin\" : true ,\n \"Lissabon\" : false ,\n \"Leipzig\" : false\n }\n },\n {\n \"title\" : \"My form\" ,\n \"type\" : \"FormBuilder\" ,\n \"fields\" : {\n \"Your email\" : \"Email\" ,\n \"Your name\" : \"Name\"\n }\n }\n ],\n \"leaderboard\" : {\n \"connections\" : [ \"Fw5uSygx\" ]\n }\n }\n }\n To show the leaderboard on the result page and to fully engage the user, we advise adding the Leaderboard block to the result page. Click here to learn more. Fetch leaderboard entries To read the entries of a leaderboard, e.g. to display them in your own frontend or to determine the winners of a contest, use the /riddle-leaderboard/entries/{UUID} API endpoint. Property Required Type Description Default page ✓ integer The page you want to return limit integer How many results the page should contain (maximum: 50) 50 search string Search term; exact match for an email address, or partial match for a nickname Example payload: {\n \"page\" : 1 ,\n \"limit\" : 50\n }\n Troubleshooting Make sure that.. the leaderboard UUID is correct the leaderboard is in the same project as the Riddle you are creating you have added a FormBuilder with a Name (or generic Text , which is also accepted as the nickname source) and Email field to your Riddle when you want to connect multiple Riddles: you are subscribed to our Enterprise plan html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":150,"path":151,"dir":75,"title":152,"description":153,"keywords":154,"body":158},"content:15.Api:3.Build Riddles:3.Riddle types and other blocks:8.Minigame.md","/api/build-riddles/riddle-types-and-other-blocks/minigame","Create Minigame - Build Riddles","Learn how to build Minigames via API",[155,156,157,88,16],"Adding a SlotMachine","Adding a WheelSpinner","Adding a Sudoku"," Create Minigame When building a minigame you can add: A SlotMachine block A WheelSpinner block (also called Wheel of fortune ) A Sudoku block Form fields General blocks Adding a SlotMachine Properties Property Required Type Description Default type ✓ string Set to SlotMachine title ✓ string The title of the slot machine description string The description of the slot machine startBalance integer The starting balance of the user 10 winningProbability string Set to Low , Medium or High Medium Example object {\n \"title\" : \"Spin the slot machine\" ,\n \"description\" : \"Try your luck!\" ,\n \"type\" : \"SlotMachine\" ,\n \"startBalance\" : 1000 ,\n \"winningProbability\" : \"High\"\n }\n Adding a WheelSpinner Properties Property Required Type Description Default type ✓ string Set to WheelSpinner title ✓ string The title of the wheel spinner description string The description of the wheel spinner items ✓ object[] An array of the items on the wheel, see WheelSpinnerItem properties below; must contain between 2 and 30 items WheelSpinnerItem properties Property Required Type Description Default title ✓ string The title of the item type ✓ string Set to either Win , Loss , or FreeSpin percent ✓ integer The percentage of the item on the wheel; 0-100 award required if type is Win string The award the user gets backgroundColor string The background color of the item rgba(255, 255, 255, 1) textColor string The text color of the item rgba(0, 0, 0, 1) media string The URL of the media file Note: The percent values across all items must sum to exactly 100, otherwise a validation error is thrown. Example object {\n \"title\" : \"Spin the wheel\" ,\n \"description\" : \"Try your luck!\" ,\n \"type\" : \"WheelSpinner\" ,\n \"items\" : [\n {\n \"title\" : \"Win 100$\" ,\n \"type\" : \"Win\" ,\n \"percent\" : 50 ,\n \"award\" : \"100$\"\n },\n {\n \"title\" : \"Lose 50$\" ,\n \"type\" : \"Loss\" ,\n \"percent\" : 30 ,\n \"award\" : \"-50$\"\n },\n {\n \"title\" : \"Free spin\" ,\n \"type\" : \"FreeSpin\" ,\n \"percent\" : 20 ,\n \"award\" : \"Free spin\"\n }\n ]\n }\n Adding a Sudoku Properties Property Required Type Description Default type ✓ string Set to Sudoku title ✓ string The title of the sudoku block description string The description of the sudoku block media string The URL of the media file difficulty integer The difficulty level of the sudoku; 0-100 50 areRulesVisible boolean Whether the rules are visible to the user true isConflictHighlightingAllowed boolean Whether conflict highlighting is allowed false isGuessCheckingAllowed boolean Whether guess checking is allowed false refreshInterval string The interval in which the sudoku automatically refreshes; set to a value of: None , Hourly , Daily , Weekly , or Monthly None Example object {\n \"title\" : \"Sudoku Challenge\" ,\n \"description\" : \"Solve the puzzle!\" ,\n \"type\" : \"Sudoku\" ,\n \"difficulty\" : 70 ,\n \"areRulesVisible\" : true ,\n \"isConflictHighlightingAllowed\" : true ,\n \"isGuessCheckingAllowed\" : true ,\n \"refreshInterval\" : \"Weekly\"\n }\n Full example {\n \"type\" : \"Minigame\" ,\n \"build\" : {\n \"title\" : \"Minigame example (Builder API)\" ,\n \"blocks\" : [\n {\n \"title\" : \"Spin the slot machine\" ,\n \"description\" : \"Try your luck!\" ,\n \"type\" : \"SlotMachine\" ,\n \"startBalance\" : 1000 ,\n \"winningProbability\" : \"High\"\n },\n {\n \"title\" : \"Spin the wheel\" ,\n \"description\" : \"Try your luck!\" ,\n \"type\" : \"WheelSpinner\" ,\n \"items\" : [\n {\n \"title\" : \"Win 100$\" ,\n \"type\" : \"Win\" ,\n \"percent\" : 50 ,\n \"award\" : \"100$\"\n },\n {\n \"title\" : \"Lose 50$\" ,\n \"type\" : \"Loss\" ,\n \"percent\" : 30 ,\n \"award\" : \"-50$\"\n },\n {\n \"title\" : \"Free spin\" ,\n \"type\" : \"FreeSpin\" ,\n \"percent\" : 20 ,\n \"award\" : \"Free spin\"\n }\n ]\n },\n {\n \"title\" : \"Sudoku Challenge\" ,\n \"description\" : \"Solve the puzzle!\" ,\n \"type\" : \"Sudoku\" ,\n \"difficulty\" : 70 ,\n \"areRulesVisible\" : true ,\n \"isConflictHighlightingAllowed\" : true ,\n \"isGuessCheckingAllowed\" : true ,\n \"refreshInterval\" : \"Weekly\"\n }\n ]\n }\n }\n Next steps Now that you know the basics of building a minigame, you might want to learn how to: Add form fields to your Riddle Use the Ad block to monetize your Riddle or add Content blocks Define the publish settings: Enable DOI, email automation, add integrations, and more Define the preset and palette you want to use Build an advanced result page Add media, such as images, videos, and social media content html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":160,"path":161,"dir":75,"title":162,"description":163,"keywords":164,"body":168},"content:15.Api:3.Build Riddles:3.Riddle types and other blocks:9.General blocks.md","/api/build-riddles/riddle-types-and-other-blocks/general-blocks","General blocks - Build Riddles","Learn how to build ad slots, content blocks and more via API",[165,166,167,88],"Content/Text Block","Ad Block","Quote Block"," General blocks The blocks on this page can be added to any build type, hence considered \"general\". Content/Text Block The Content block is a simple block that can be used to display a title and description. It can be used as an introduction to the quiz (= cover block) or as a conclusion. Properties Property Required Type Description title ✓ string The title of the content block description string The description of the content block media string A media URL to an image to display Example: {\n \"type\" : \"Content\" ,\n \"title\" : \"Welcome to the quiz\" ,\n \"description\" : \"This quiz will test your knowledge about the world\"\n }\n Ad Block In the ad block it is optional to add a title and description . Adding ad blocks is possible in two ways: By using project ad slots By implementing a custom iframe Project ad slots To add an ad to your build using a project ad slot, you need to add the property projectSlot in the Ad block, consisting of: Property Required Type Description Default slotId ✓ integer The ad slot to use variables Object An object with key-value pairs to override ad slot variables Note: projectSlot and iframe are mutually exclusive; you cannot set both on the same Ad block. Example: {\n \"type\" : \"Ad\" ,\n \"projectSlot\" : {\n \"slotId\" : 123456\n }\n }\n Example with variables: {\n \"type\" : \"Ad\" ,\n \"projectSlot\" : {\n \"slotId\" : 123456 ,\n \"variables\" : {\n \"ad-variable-key1\" : \"override-value1\"\n }\n }\n }\n Custom iframe To be more flexible with ads and to be more independent from the Riddle Creator, you can add an Ad block with the iframe object set, consisting of: Property Required Type Description Default url ✓ URL The URL the iframe should link to height integer The height of the iframe in px; automatic resizing does not work with custom iframes 80 Example: {\n \"type\" : \"Ad\" ,\n \"iframe\" : {\n \"url\" : \"https://www.example.com/ad.html\" ,\n \"height\" : 250\n }\n }\n Quote Block The Quote block can be used to display a quote with a author. Properties The quote block consists of: Property Required Type Description Default title ✓ string The title of the quote block description string The description of the quote block media string A media URL to an image to display as the general image type ✓ string Set to Quote quoteText ✓ string The quote text quoteAuthor ✓ string The author of the quote quoteMedia string A media URL to an image to display as the quote image Example {\n \"type\" : \"Quote\" ,\n \"title\" : \"Inspiring Quote\" ,\n \"description\" : \"A quote to inspire you\" ,\n \"media\" : \"https://example.com/general-image.jpg\" ,\n \"quoteText\" : \"The only limit to our realization of tomorrow is our doubts of today.\" ,\n \"quoteAuthor\" : \"Franklin D. Roosevelt\" ,\n \"quoteMedia\" : \"https://example.com/quote-image.jpg\"\n }\n Full example For this example we build a quiz with a content + ad block. {\n \"type\" : \"Quiz\" ,\n \"build\" : {\n \"title\" : \"General blocks example (Builder API)\" ,\n \"blocks\" : [\n {\n \"type\" : \"Content\" ,\n \"title\" : \"Welcome to the quiz\" ,\n \"description\" : \"This quiz will test your knowledge about France\"\n },\n {\n \"type\" : \"MultipleChoice\" ,\n \"title\" : \"What is the capital of France?\" ,\n \"items\" : {\n \"Paris\" : true ,\n \"Lissabon\" : false ,\n \"Berlin\" : false\n }\n },\n {\n \"type\" : \"Ad\" ,\n \"iframe\" : {\n \"url\" : \"https://google.com\"\n }\n },\n {\n \"type\" : \"MultipleChoice\" ,\n \"title\" : \"How do you say 'hello' in French?\" ,\n \"items\" : {\n \"Bonjour\" : true ,\n \"Hallo\" : false ,\n \"Ciao\" : false\n }\n },\n {\n \"type\" : \"Quote\" ,\n \"title\" : \"Inspiring Quote\" ,\n \"quoteText\" : \"The only limit to our realization of tomorrow is our doubts of today.\" ,\n \"quoteAuthor\" : \"Franklin D. Roosevelt\"\n }\n ]\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":170,"path":171,"dir":75,"title":172,"description":173,"keywords":174,"body":187},"content:15.Api:3.Build Riddles:3.Riddle types and other blocks:10.Result Pages.md","/api/build-riddles/riddle-types-and-other-blocks/result-pages","Result pages - Build Riddles","Learn how to build result pages via API",[175,176,177,178,179,180,181,182,183,184,185,186],"Redirect to a URL","Advanced result pages","Add user's score","Add text","Add button","Add share to social block","Add answered blocks","Add image","Add leaderboard","Add winning personality","Add other personalities","Offset any block with margins"," Result pages If you only require a minimal result page with text you need to add a title and description property to the result object. For quiz: {\n \"blocks\" : [ ... ],\n \"results\" : [\n {\n \"minPercentage\" : 0 ,\n \"maxPercentage\" : 50 ,\n \"title\" : \"Bad result\" ,\n \"description\" : \"You answered less than 50% of the questions correctly\"\n },\n {\n \"minPercentage\" : 51 ,\n \"maxPercentage\" : 100 ,\n \"title\" : \"Good result\" ,\n \"description\" : \"You answered more than 50% of the questions correctly\"\n }\n ]\n }\n For any other Riddle type: {\n \"blocks\" : [ ... ],\n \"result\" : {\n \"title\" : \"Thank you!\" ,\n \"description\" : \"We are happy to have you here\"\n }\n }\n This default result page always consists of: Your given title and description A block which allows the user to share the result on different social networks Additionally it may contain: For quiz: a block which shows the user how many questions they answered correctly For personality: a block which shows the user information about their winning personality and other personalities (if available) In most cases this should suffice - if you want to create result URL redirects or advanced result pages similar to the functionality in the Creator , keep reading. Redirect to a URL If you want to redirect the user to a URL after they have completed the Riddle, you can do this by adding a redirectUrl property to the result object. {\n \"blocks\" : [ ... ],\n \"result\" : {\n \"redirectUrl\" : \"https://www.riddle.com\"\n }\n }\n This will redirect the user to https://www.riddle.com after they have completed the Riddle. Note: This result redirecting only works for Poll, Quiz, Form, and Minigame Riddles. Optional properties There are several options you can choose from when adding a result redirect: Property Type Description Default delay integer The delay in seconds before the redirect happens 0 title string The title of the result page. This will be displayed in the browser tab description string The description of the result page. This will be displayed in the browser tab media string The URL of the image shown on the result page (path content.media ) openFullscreen boolean If true the result page will be opened in fullscreen mode, outside of the Riddle true Note : Only with the delay property will the user actually see the title and description. Note : For Quiz Riddles, redirects are defined per result inside the results array. In this case minPercentage and maxPercentage are additionally required to define the score range for which this redirect applies. Example object: {\n \"blocks\" : [ ... ],\n \"result\" : {\n \"redirectUrl\" : \"https://www.riddle.com\" ,\n \"delay\" : 5 ,\n \"title\" : \"Thank you!\" ,\n \"description\" : \"We are happy to have you here\" ,\n \"openFullscreen\" : false\n }\n }\n Advanced result pages You can create advanced result pages with texts, images, answered blocks, and more via the API's result builder. See the result page documentation to see how this works in the Creator. Similar to the Riddle's blocks the result page is also structured in blocks. You can add up to 10 blocks to the result page. To do this send a blocks array in the result object instead of a title and description property: For poll (or any type which only has one result): {\n \"blocks\" : [ ... ],\n \"result\" : {\n \"blocks\" : [\n {\n \"type\" : \"Text\" ,\n \"text\" : \"This is my result page text!\"\n },\n ...\n ]\n }\n }\n For quiz: {\n \"blocks\" : [ ... ],\n \"results\" : [\n {\n \"minPercentage\" : 0 ,\n \"maxPercentage\" : 50 ,\n \"blocks\" : [\n {\n \"type\" : \"Text\" ,\n \"text\" : \"Bad result\"\n },\n ...\n ]\n },\n {\n \"minPercentage\" : 51 ,\n \"maxPercentage\" : 100 ,\n \"blocks\" : [\n {\n \"type\" : \"Text\" ,\n \"text\" : \"Good result\"\n },\n ...\n ]\n }\n ]\n }\n Every result page block consists of a type property and additional properties depending on the block type. For example here is the content for the button block only with required options : {\n \"type\" : \"Button\" ,\n \"label\" : \"My new button!\" ,\n \"url\" : \"https://riddle.com\"\n }\n This will create a button with the label \"My new button!\" which links to https://riddle.com . If we now want to set the optional property isOpenInNewTabEnabled to true the object for this button would look like this: {\n \"type\" : \"Button\" ,\n \"label\" : \"My new button!\" ,\n \"url\" : \"https://riddle.com\" ,\n \"isOpenInNewTabEnabled\" : true \u003C--- optional property\n }\n In the next sections all available blocks are listed with their required and optional properties. Add user's score Displays the user's score in a given format. Properties Property Required Type Description Default format string The format in which the user's score should be displayed, valid values: Score (displays the user's score in an absolute number), ScoreTotalScore (displays the user's score in relation to the total score), ScorePoints ( displays the user's score in points), Percentage (displays the user's score in percentage) colorBg string The background color of the score rgba(0, 0, 0, 0) colorText string The text color of the score #000 colorCircle string The color of the circle #000 colorCircleBg string The background color of the circle rgba(0,0,0,0.1) Example object {\n \"type\" : \"ResultScore\" ,\n \"format\" : \"Score\" ,\n \"colorBg\" : \"#fff\" ,\n \"colorText\" : \"#000\" ,\n \"colorCircle\" : \"#000\" ,\n \"colorCircleBg\" : \"#fff\"\n }\n Add text Displays a regular text block. You can use HTML tags in the text. Tip: Use dynamic variables here to personalize the result page text to user input. Properties Property Required Type Description Default text ✓ string The text to be displayed Example object {\n \"type\" : \"Text\" ,\n \"text\" : \"This is my result page text!\"\n }\n Add button Displays a call to action button that links to a specified URL on click. Tip: Use dynamic variables in the label or URL. Properties Property Required Type Description Default label ✓ string The button text url ✓ string The URL the button should link to isOpenInNewTabEnabled boolean If true the link will open in a new tab false colorBg string The background color of the button #000 colorBgHover string The background color of the button on hover rgba(0,0,0,0.8) colorBorder string The border color of the button #77baf6ff colorBorderHover string The border color of the button on hover #93c3ed colorText string The text color of the button #fff colorTextHover string The text color of the button on hover #fff borderRadius string The border radius of the button; all corners are the same 18px borderWidth string The border width of the button; all sides are the same 0px padding string The padding of the button; all sides are the same 11px textCapitalization string The text capitalization of the button. Valid values: capitalize , uppercase , lowercase , none uppercase textAlign string The text alignment of the button. Valid values: start , end , left , right , center , justify , inherit center textLetterSpacing string The letter spacing of the button 0.12rem textLineHeight string The line height of the button 1.4rem fontSize string The font size of the button 1.6rem fontFamily string The font family for this button. Use the Builder API font families endpoint to get a list of all available values normal fontStyle string The font style of the button. Valid values: normal , italic , oblique normal fontWeight string The font weight of the button. Valid values: normal , bold , bolder , lighter , inherit , n100 , n200 , n300 , n400 , n500 , n600 , n700 , n800 , n900 n600 Example object {\n \"type\" : \"Button\" ,\n \"label\" : \"Click me!\" ,\n \"url\" : \"https://riddle.com\" ,\n \"isOpenInNewTabEnabled\" : true ,\n \"colorBg\" : \"_colorBg\" ,\n \"colorBgHover\" : \"#fff\" ,\n \"colorBorder\" : \"#fff\" ,\n \"colorBorderHover\" : \"#fff\" ,\n \"colorText\" : \"#fff\" ,\n \"colorTextHover\" : \"#fff\" ,\n \"borderRadius\" : \"5px\" ,\n \"borderWidth\" : \"5px\" ,\n \"padding\" : \"5px\" ,\n \"textCapitalization\" : \"lowercase\" ,\n \"textAlign\" : \"inherit\" ,\n \"textLetterSpacing\" : \"20px\" ,\n \"textLineHeight\" : \"20px\" ,\n \"fontFamily\" : \"Arial\" ,\n \"fontSize\" : \"20px\" ,\n \"fontStyle\" : \"oblique\" ,\n \"fontWeight\" : \"bolder\"\n }\n Add share to social block Displays a share block that allows users to share the result on different social networks. You can customize the share messages, URLs and all of the share block's design properties. Properties Property Required Type Description Default label string The label of the share element Share messageTitle string The message users will share and will see as the title in the share dialogue (empty) messageDescription string The description users will see in the share dialogue as a description (empty) messageUrl string The URL users will share (empty) (will go to Riddle showcase, riddle.com/view/X) networks array The networks the user can share the result on. See below to get the available social networks. 'facebook', 'whatsapp', 'twitter' colorBg string The background color of the share block #ffffff00 colorButtonBg string The background color of the share button #000 colorButtonBgHover string The background color of the share button on hover #333 colorButtonIcon string The color of the share button icon #fff colorButtonIconHover string The color of the share button icon on hover #fff colorBrandIsEnabled boolean If true the brand color will be used for the share button false colorText string The text color of the share block #000 buttonBorderRadius string The border radius of the share button 50% buttonGap string The gap between the share buttons 0.8rem buttonIconSize string The size of the share button icon 2.1rem buttonSize string The size of the share button 3.6rem textCapitalization string The text capitalization of the share block. Valid values: capitalize , uppercase , lowercase , none uppercase textAlign string The text alignment of the share block. Valid values: start , end , left , right , center , justify , inherit inherit textLetterSpacing string The letter spacing of the share block 0.12rem textLineHeight string The line height of the share block 1.4rem fontFamily string The font family for this button. Use the Builder API font families endpoint to get a list of all available values none fontSize string The font size of the share block 1.6rem fontStyle string The font style of the share block. Valid values: normal , italic , oblique normal fontWeight string The font weight of the share block. Valid values: normal , bold , bolder , lighter , inherit , n100 , n200 , n300 , n400 , n500 , n600 , n700 , n800 , n900 n400 Example object {\n \"type\" : \"Share\" ,\n \"messageTitle\" : \"Share this poll!\" ,\n \"messageDescription\" : \"This is a description\" ,\n \"networks\" : [ \"facebook\" , \"linkedin\" ]\n }\n Available social networks The following social networks are available to share on (make sure to use the same casing!) : buffer email evernote facebook flipboard instagram instapaper line linkedin messenger odnoklassniki pinterest pocket reddit skype sms telegram tumblr twitter viber vk weibo whatsapp xing yammer Add answered blocks Displays a block that shows the user what they answered and how many votes each answer got (if enabled). Properties Property Required Type Description Default areTotalVotesVisible boolean If true the total number of votes will be displayed true isPercentageVisible boolean If true the percentage of votes will be displayed true isVotesNumberVisible boolean If true the number of votes will be displayed true areAnswerImagesHidden boolean If true the images of the answers will be hidden false areMainImagesHidden boolean If true the main images will be hidden false Example Object {\n \"type\" : \"AnsweredBlocks\" ,\n \"areTotalVotesVisible\" : true\n }\n Add image Displays an image. Properties Property Required Type Description Default media ✓ string The URL of the image Example Object {\n \"type\" : \"Media\" ,\n \"media\" : \"https://www.example.com/image.jpg\"\n }\n Add leaderboard Add a leaderboard to the result page. Properties Property Required Type Description Default leaderboard ✓ string The UUID of the leaderboard you want to connect Example Object {\n \"type\" : \"Leaderboard\" ,\n \"leaderboard\" : \"hQ3SYWur\"\n }\n Add winning personality Displays the user's winning personality. Only available for personality tests. Properties Property Required Type Description Default type ✓ string Set to WinningPersonality showMedia boolean If true the media of the personality will be displayed true format string The format in which the personality will be displayed. Valid values: PercentageTitle , TitlePercentage , PointsTitle , TitlePoints , Title PercentageTitle Example Object {\n \"type\" : \"WinningPersonality\" ,\n \"showMedia\" : true ,\n \"format\" : \"Title\"\n }\n Add other personalities Displays the other personalities. Only available for personality tests. Properties Property Required Type Description Default type ✓ string Set to OtherPersonalities format string The format in which the personalities will be displayed. Valid values: PercentageTitle , TitlePercentage , PointsTitle , TitlePoints , Title PercentageTitle count integer The number of personalities to display 2 layout string The layout in which the personalities will be displayed. Valid values: FullWidth , TwoColumns TwoColumns includeWinningPersonality boolean If true the winning personality will also be displayed false Example Object {\n \"type\" : \"OtherPersonalities\" ,\n \"format\" : \"Title\" ,\n \"count\" : 3 ,\n \"layout\" : \"FullWidth\" ,\n \"includeWinningPersonality\" : false\n }\n Offset any block with margins If you want to create a gap between two result page builder blocks, e.g. to emphasize a certain block, you can use margins to better position the blocks. Note: The margin does not work with pixel values! Instead we use the coordinate system just as in the Creator to position the blocks. This means that setting \"marginTop: 2\" will result in a block offset by two units. We recommend you play around and see what works best for your design. Properties Property Required Type Description Default marginTop integer The margin at the top of the block 0 marginBottom integer The margin at the bottom of the block 0 Example Object {\n \"type\" : \"Text\" ,\n \"text\" : \"This is my result page text!\" ,\n \"marginTop\" : 2 ,\n \"marginBottom\" : 2\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":189,"path":190,"dir":191,"title":192,"description":193,"keywords":194,"body":203},"content:15.Api:3.Build Riddles:4.Settings configuration:1.Publish settings.md","/api/build-riddles/settings-configuration/publish-settings","settings-configuration","Publish settings - Build Riddles","Learn how to publish Riddles and set publish settings via API",[195,196,197,61,198,199,200,201,202,88],"Publishing the built Riddle after creation","Advanced settings","Properties","Integrations","DOI","Email automation","Data Layer","Tracking"," Publish settings Publishing the built Riddle after creation The request body parameter “publish” can be sent with the API to publish the Riddle right after creation, making it easier to embed the generated content on the web page. Example: {\n \"type\" : \"Poll\" ,\n \"publish\" : true ,\n \"build\" : {\n \"blocks\" : [ ... ]\n }\n }\n Advanced settings With these publish settings you can define any settings found in the Riddle Creator Publish screen. Properties You can specify the following optional properties: Property Type Description isShowcaseEnabled boolean Set to false if your Riddle should not be accessible via direct Riddle link (e.g. riddle.com/view/XXX) isDoiEnabled boolean Set to true if you want to enable the Double-Opt-In Feature. For this to work you must add an email address form field first. Learn here how to add form fields. doiConfig object Further configuration for the Double-Opt-In Feature; more information below isEmailAutomationEnabled boolean Set to true if you want to enable the email automation feature. For this to work you must add an email address form field first. Learn here how to add form fields. emailAutomationConfig object Further configuration for the email automation feature; more information below dataLayerItems object A key-value array to create data layer variables; more information below tracking string[] Tracking configuration; more information below integrations object Specify existing integrations to enable; more information below Example The publish settings properties are sent in the publish property of the build object, here's how it looks: {\n \"blocks\" : [ ... ],\n \"publish\" : {\n \"isDoiEnabled\" : true ,\n ...\n }\n }\n Integrations You can add existing Googlesheets & webhook integrations to your Riddle. To do this, you can specify integrations in your publish object. Example: {\n \"blocks\" : [ ... ],\n \"publish\" : {\n \"integrations\" : {\n \"googlesheets\" : \"test@riddle.com\" ,\n \"webhook\" : \"example.com/webhook\"\n }\n }\n }\n In this example we already connected the Googlesheets integration with the email test@riddle.com and the webhook integration with the URL example.com/webhook . The name of the integration you send here must match with the name displayed on the integrations page in the Riddle Creator. If the integration cannot be found, the Riddle build will fail and you will get a RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_INVALID error from the API. DOI To enable DOI, first set isDoiEnabled to true : {\n \"isDoiEnabled\" : true\n }\n Enabling it will set the first email field in the Riddle as the DOI field. If you want to customize the DOI email or confirmation page, you can send the following properties in doiConfig : emailSubject : the DOI email subject emailText : the DOI email text emailConfirmationButtonLabel : the label of the confirmation button in the DOI email confirmationPageHeadline : the headline of the confirmation page confirmationPageBody : the text of the confirmation page confirmationPageUrl : the URL the user is redirected to after confirming the DOI Note: If you send a confirmationPageUrl property, the other confirmation page properties are redundant as the user gets redirected to the URL immediately after confirming the DOI (user does not see extra confirmation page headline/text). Tip: Use dynamic variables for any of the DOI properties to personalize this flow to user input. Example: {\n \"isDoiEnabled\" : true ,\n \"doiConfig\" : {\n \"emailSubject\" : \"Please confirm your email %name\" ,\n \"emailText\" : \"Hi %name, Please confirm your email by clicking the button below.\" ,\n \"emailConfirmationButtonLabel\" : \"Confirm email\" ,\n \"confirmationPageHeadline\" : \"Thank you for confirming your email\" ,\n \"confirmationPageBody\" : \"You can now access the content\" ,\n \"confirmationPageUrl\" : \"https://www.example.com\"\n }\n }\n Email automation To enable email automation, first set isEmailAutomationEnabled to true : {\n \"isEmailAutomationEnabled\" : true\n }\n Enabling it will set the first email field in the Riddle as the email automation field. If you want to customize the email that is sent, you can send the following properties in emailAutomationConfig : subject : the email subject text : the email text Tip: Use dynamic variables for any of the email automation properties to personalize this flow to user input. Example: {\n \"isEmailAutomationEnabled\" : true ,\n \"emailAutomationConfig\" : {\n \"subject\" : \"Thank you for participating %name!\" ,\n \"text\" : \"Thank you for participating in our quiz %name. Here are your results: ...\"\n }\n }\n Data Layer The Riddle Data Layer can be setup with the dataLayerItems property which is a key-value array: The key is the key of the data layer variable (this is used to push to it, e.g. riddle.com/view/XXX?key=value or dataLayer.push({ key: value }) ) and the value is the title of the variable which will be used in the export as the data layer column name. Example: Adding three data layer variables: {\n \"dataLayerItems\" : {\n \"utm_source\" : \"Source\" ,\n \"utm_medium\" : \"Medium\" ,\n \"utm_campaign\" : \"Campaign\"\n }\n }\n Tracking With the tracking property you can define which tracking should be enabled for your Riddle. By default no tracking is enabled. The following tracking options are available (case-sensitive): facebookPixel googleAnalytics googleAnalytics4 googleTagManager matomoTag Example: Activating Google Tag Manager and Matomo Tag: {\n \"tracking\" : [ \"googleTagManager\" , \"matomoTag\" ]\n }\n Full example {\n \"type\" : \"Poll\" ,\n \"publish\" : true ,\n \"build\" : {\n \"blocks\" : [ ... ],\n \"publish\" : {\n \"isDoiEnabled\" : true ,\n \"doiConfig\" : {\n \"emailSubject\" : \"Please confirm your email %name\" ,\n \"emailText\" : \"Hi %name, Please confirm your email by clicking the button below.\" ,\n \"emailConfirmationButtonLabel\" : \"Confirm email\" ,\n \"confirmationPageHeadline\" : \"Thank you for confirming your email\" ,\n \"confirmationPageBody\" : \"You can now access the content\" ,\n \"confirmationPageUrl\" : \"https://www.example.com\"\n },\n \"isEmailAutomationEnabled\" : true ,\n \"emailAutomationConfig\" : {\n \"subject\" : \"Thank you for participating %name!\" ,\n \"text\" : \"Thank you for participating in our quiz %name. Here are your results: ...\"\n },\n \"dataLayerItems\" : {\n \"utm_source\" : \"Source\" ,\n \"utm_medium\" : \"Medium\" ,\n \"utm_campaign\" : \"Campaign\"\n },\n \"tracking\" : [ \"googleTagManager\" , \"matomoTag\" ],\n \"integrations\" : {\n \"googlesheets\" : \"test@riddle.com\" ,\n \"webhook\" : \"https://www.example.com/webhook\"\n }\n }\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":205,"path":206,"dir":191,"title":207,"description":208,"keywords":209,"body":218},"content:15.Api:3.Build Riddles:4.Settings configuration:2.Preset settings.md","/api/build-riddles/settings-configuration/preset-settings","Preset settings - Build Riddles","Learn how to set preset settings via API",[210,211,212,213,214,215,216,217],"Default case","Specifying preset settings","Add remember user configuration","Changing Riddle language","Opening the Riddle at a set time","Closing the Riddle at a set time","Setting Riddle timer","Setting block timer"," Preset settings With the preset settings you can customize: Which project preset and palette to use The remember user configuration The Riddle language When the Riddle automatically opens and closes The Riddle and block timer Default case If no preset setting is specified and the Riddle is created in a project (!) the default preset and its selected palette will be used for the built Riddle. Click here to learn how to set a default preset for your project. Specifying preset settings The preset settings properties are sent in the preset property of the build object. If we now for example want to use a preset and palette from our project the request would look like this: {\n \"blocks\" : [ ... ],\n \"preset\" : {\n \"preset\" : 805 ,\n \"palette\" : \"Zymx\"\n }\n }\n Retrieving preset and palette IDs Retrieving your project's presets and associated palettes is possible through the Builder API presets endpoint . An example response looks like this: {\n \"success\" : true ,\n \"code\" : 200 ,\n \"data\" : [\n {\n \"id\" : 805 ,\n \"name\" : \"My project preset\" ,\n \"palettes\" : [\n {\n \"id\" : \"Zymx\" ,\n \"name\" : \"my palette\"\n }\n ]\n }\n ]\n }\n Add remember user configuration 'Remember user' means writing the user's answers to the local storage, meaning that the user doesn't have to input their name or email again when revisiting the Riddle / website. Properties Property Required Type Description Default isEnabled ✓ boolean Whether the remember user feature is enabled or not false isAutoSubmitEnabled boolean if true, the form will be submitted automatically when the user returns to the Riddle true isDsgvoAccepted boolean Whether the user has accepted the DSGVO false isUserPermissionRequired boolean Whether the user has to give permission to store their data in local storage true Example object {\n \"blocks\" : [ ... ],\n \"preset\" : {\n \"rememberUser\" : {\n \"isEnabled\" : true ,\n \"isAutoSubmitEnabled\" : false ,\n \"isDsgvoAccepted\" : true ,\n \"isUserPermissionRequired\" : false\n }\n }\n }\n Changing Riddle language The language of the Riddle can be changed by setting the language property in the preset settings. The language must be a two-letter ISO code, e.g. 'de' for German, 'en' for English, 'fr' for French, etc. Example object {\n \"blocks\" : [ ... ],\n \"preset\" : {\n \"language\" : \"de\"\n }\n }\n Opening the Riddle at a set time Opening the Riddle at a set time can be done by setting the autoOpenDate property in the preset settings. The value must be a date in the format 'YYYY-mm-dd HH:ii:ss', e.g. '2023-10-01 00:00:00'. Please note that the provided date must be in the timezone Europe/Berlin (German local time) . Example object {\n \"blocks\" : [ ... ],\n \"preset\" : {\n \"autoOpenDate\" : \"2099-10-01 00:00:00\"\n }\n }\n Closing the Riddle at a set time Closing the Riddle at a set time can be done by setting the autoClose property in the preset settings. The property is an object with the following properties: Property Required Type Description Default date ✓ string The date when the Riddle should close. The value must be a date in the format 'YYYY-mm-dd HH:ii:ss', e.g. '2023-10-01 00:00:00'. Please note that the provided date must be in the timezone Europe/Berlin (German local time) resultId integer The ID of the result that should be shown when the Riddle is closed. Use 1 for the first result, 2 for the second result, ...; by default the first result is shown 1 Example object {\n \"blocks\" : [ ... ],\n \"preset\" : {\n \"autoClose\" : {\n \"date\" : \"2099-10-01 00:00:00\" ,\n \"resultId\" : 1\n }\n }\n }\n Setting Riddle timer The Riddle timer is a limit on how long the user has to complete the Riddle. Note: The Riddle timer is only available for Quiz Riddles. It is ignored for all other Riddle types. Properties Property Required Type Description Default timeLimit ✓ integer The time limit in seconds pauseOnNonQuestionBlocks boolean Whether the timer should pause on non-question blocks, such as Form blocks true warningAt integer The time in seconds when the warning should be shown. The warning is a message that tells the user how much time they have left 10 format string The format of the timer. Allowed values: s (Seconds as number), m_s (Minutes:Seconds), x_m_x_s (X minutes Y seconds) s shape string The shape of the timer. Allowed values: circleTimer , barTimer barTimer Example object {\n \"blocks\" : [ ... ],\n \"preset\" : {\n \"riddleTimer\" : {\n \"timeLimit\" : 60 ,\n \"pauseOnNonQuestionBlocks\" : true ,\n \"warningAt\" : 10 ,\n \"format\" : \"s\" ,\n \"shape\" : \"circleTimer\"\n }\n }\n }\n Setting block timer The block timer is a limit on how long the user has to complete a block. The time limit can be set either per block or globally for all blocks. Note: The block timer is only available for Quiz Riddles. It is ignored for all other Riddle types. Properties Property Required Type Description Default timeLimit ✓ integer The time limit in seconds; not required when individualBlockTimes is set pauseOnNonQuestionBlocks boolean Whether the timer should pause on non-question blocks, such as Form blocks true warningAt integer The time in seconds when the warning should be shown. The warning is a message that tells the user how much time they have left 10 format string The format of the timer. Allowed values: s (Seconds as number), m_s (Minutes:Seconds), x_m_x_s (X minutes Y seconds) s shape string The shape of the timer. Allowed values: circleTimer , barTimer barTimer individualBlockTimes int An array of integers that specify the time limit for each block. The order of the blocks is the same as in the blocks property of the build object. The length of the array must be equal to the number of blocks in the Riddle Example objects Setting a global block time limit: {\n \"blocks\" : [ ... ],\n \"preset\" : {\n \"blockTimer\" : {\n \"timeLimit\" : 60 ,\n \"pauseOnNonQuestionBlocks\" : true ,\n \"warningAt\" : 10 ,\n \"format\" : \"s\" ,\n \"shape\" : \"circleTimer\"\n }\n }\n }\n Setting a block time limit for each block: {\n \"blocks\" : [\n {\n \"title\" : \"Solve this Riddle: What is the capital of France?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Paris\" : true ,\n \"Berlin\" : false\n }\n },\n {\n \"title\" : \"Solve this Riddle: What is the capital of Germany?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Berlin\" : true ,\n \"Paris\" : false\n }\n }\n ],\n \"preset\" : {\n \"blockTimer\" : {\n \"individualBlockTimes\" : [ 60 , 30 ]\n }\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":220,"path":221,"dir":191,"title":222,"description":223,"keywords":224,"body":232},"content:15.Api:3.Build Riddles:4.Settings configuration:3.Logic settings.md","/api/build-riddles/settings-configuration/logic-settings","Logic settings - Build Riddles","Learn how to build custom logic flows for your Riddles using the Riddle API.",[225,226,227,228,229,230,231],"Default logic","Prerequisites","Logic settings structure / properties","Pitfalls","Troubleshooting / Error codes","Full example 1: Quiz with answer branching on quiz questions","Full example 2: Poll with branching on a standalone form dropdown field"," Logic settings Just like in the Riddle creator , you can set up custom logic flows for your Riddles using the Builder API. Custom logic flows are available for the following Riddle types via API: Quiz Poll Form Currently, only branching by answers for SingleChoice, MultipleChoice, and standalone Form Dropdown fields is supported. The following will be added soon: Branching by block score or total score Branching by a data layer variable Any other suggestions? Please get in touch via support chat or send an email to hello@riddle.com . Default logic When you create a Riddle via the Builder API without specifying any logic settings, the Riddle will have a default linear logic flow. This means that the blocks will be shown in the exact order they are defined in the blocks array of the build configuration. Prerequisites To be able to work with the logic settings efficiently, it is advised to read about assigning custom IDs to blocks and answer items first. This makes it easier to reference the blocks and answer items in the following logic settings. Logic settings structure / properties The logic settings are defined in the logic property in the build configuration, next to the blocks and result / results properties: {\n \"type\" : \"Quiz\" ,\n \"build\" : {\n \"title\" : \"My quiz with logic\" ,\n \"blocks\" : [\n \"...\" ,\n \"...\" ,\n \"...\"\n ],\n \"results\" : [\n \"...\"\n ],\n \"logic\" : {\n \"...logic tree structure...\"\n }\n }\n }\n The logic settings structure can be compared to a \"tree\" where the root of the tree is the start block, and each branch represents a possible path through the Riddle based on user interactions. This means it can nest indefinitely, as long as there are available blocks in the build configuration. You can use two types of branching: Linear 'branching' Property Required Type Description Default blockId ✓ integer The ID of the block where this logic layer starts. Can reference any block, for example even Content . branchingType string The type of branching to use. For linear branching it is set to linear , but can also be omitted due to being the default value. linear next object An object defining the next block to show after the block defined in blockId has been completed. Example: Sequence of 4 linear blocks {\n \"blockId\" : 1 ,\n \"next\" : {\n \"blockId\" : 2 ,\n \"next\" : {\n \"blockId\" : 3 ,\n \"next\" : {\n \"blockId\" : 4\n }\n }\n }\n }\n Answer branching Property Required Type Description Default blockId ✓ integer The ID of the block where this logic layer starts. Can only reference blocks which support branching (currently SingleChoice, MultipleChoice, and standalone Form Dropdown fields). branchingType ✓ string The type of branching to use. For answer branching, it is set to answer . linear rules ✓ object An array of rule objects defining the branching logic. To see the structure of each rule, see below. Defining rules Note : Each rule itself is also either a linear or answer branching, meaning it can contain a next OR rules property to define what happens after the block defined in blockId has been completed. Properties exclusive to the rule object: Property Required Type Description Default answers ✓ string |int An array of answers that trigger this rule. You can use either the answer text or the given answer ID to identify the answer. Example: Answer branching with linear next {\n \"answers\" : [ \"Answer 1\" , \"Answer 2\" ],\n \"blockId\" : 2 ,\n \"next\" : {\n \"blockId\" : 3\n }\n }\n In spoken form: If the user selects \"Answer 1\" or \"Answer 2\" show block with ID 2, then after completing that block, show block with ID 3. Example: Answer branching, followed by answer branching / rules {\n \"answers\" : [ \"Answer 1\" , \"Answer 2\" ],\n \"blockId\" : 2 ,\n \"branchingType\" : \"answer\" ,\n \"rules\" : [\n \"...\"\n ]\n }\n In spoken form: If the user selects \"Answer 1\" or \"Answer 2\" show block with ID 2, then after completing that block, follow the rules defined in the rules array (and so on). Example: First linear branching, then answer branching, then linear branching {\n \"blockId\" : 1 ,\n \"next\" : {\n \"blockId\" : 2 ,\n \"branchingType\" : \"answer\" ,\n \"rules\" : [\n {\n \"answers\" : [ \"Answer 1\" ],\n \"blockId\" : 3 ,\n \"next\" : {\n \"blockId\" : 4\n }\n },\n {\n \"answers\" : [ \"Answer 2\" ],\n \"blockId\" : 5\n }\n ]\n }\n }\n In spoken form: Start with block ID 1, then show block ID 2. If the user selects \"Answer 1\", show block ID 3, then block ID 4. If the user selects \"Answer 2\", show block ID 5. 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. Instead, 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. Troubleshooting / Error codes The logic settings throws unique error codes which can only occur in this context. Not sure how exception handling works? Check out the basic API exception handling . RIDDLE_BUILDER_BLOCK_PROPERTY_LOGIC_CIRCULAR_REFERENCE A circular reference was detected in the logic settings. This means that a block is referenced again going 'up' the logic tree, which would create an infinite loop. Example faulty logic settings: {\n \"blockId\" : 1 ,\n \"next\" : {\n \"blockId\" : 2 ,\n \"next\" : {\n \"blockId\" : 1\n }\n }\n }\n RIDDLE_BUILDER_BLOCK_PROPERTY_LOGIC_INVALID_RULE The answers provided in an answer branching rule object is either empty or references answers that do not exist in the corresponding block's items array. Example faulty logic settings: {\n \"blockId\" : 1 ,\n \"branchingType\" : \"answer\" ,\n \"rules\" : [\n {\n \"answers\" : [], // empty answers array\n \"blockId\" : 2\n },\n {\n \"answers\" : [ \"Non-existing answer\" ], // answer does not exist in block's items\n \"blockId\" : 3\n }\n ]\n }\n RIDDLE_BUILDER_BLOCK_PROPERTY_LOGIC_NON_UNIQUE_RULES The answers provided in an answer branching rule object are not unique. This means that the same answer is referenced in multiple rules of the same logic layer. Example faulty logic settings: {\n \"blockId\" : 1 ,\n \"branchingType\" : \"answer\" ,\n \"rules\" : [\n {\n \"answers\" : [ \"Answer 1\" , \"Answer 2\" ],\n \"blockId\" : 2\n },\n {\n \"answers\" : [ \"Answer 2\" , \"Answer 3\" ], // \"Answer 2\" is referenced twice\n \"blockId\" : 3\n }\n ]\n }\n RIDDLE_BUILDER_BLOCK_PROPERTY_LOGIC_NON_EXISTING_BLOCK A blockId in the logic settings references a block that does not exist in the blocks array of the build configuration. Example faulty logic settings: {\n \"blockId\" : 999 , // block with ID 999 does not exist in blocks array\n \"next\" : {\n \"blockId\" : 2\n }\n }\n RIDDLE_BUILDER_BLOCK_PROPERTY_LOGIC_UNUSED_BLOCKS Some blocks defined in the blocks array of the build configuration are not referenced in the logic settings. This means that there is no possible way for a user to reach these blocks when taking the Riddle. In the Riddle Creator this is indicated by a warning icon in the publish step, in the Builder API this results in an error to avoid building Riddles with unnecessary/unused blocks. RIDDLE_BUILDER_BLOCK_PROPERTY_LOGIC_LINEAR_ONLY_ALLOWED This can only happen in one scenario: You are trying to use answer branching in a Quiz with Flashcard blocks: This is disallowed as Flashcards have complex logic themselves which does not work with non-linear logic. RIDDLE_BUILDER_BLOCK_PROPERTY_LOGIC_DEAD_ENDS The built logic tree contains dead ends. This means that some blocks are unreachable, or some paths through the logic tree lead nowhere. RIDDLE_BUILDER_BLOCK_PROPERTY_LOGIC_INVALID_NODE A logic node is invalid. This can happen if the node is missing a blockId , if the blockId is not a positive integer, or if the branchingType is not a recognized value. Full example 1: Quiz with answer branching on quiz questions Riddle build configuration (without logic settings in first step): {\n \"type\" : \"Quiz\" ,\n \"build\" : {\n \"title\" : \"Logic example (Builder API)\" ,\n \"blocks\" : [\n {\n \"id\" : 1 ,\n \"title\" : \"What's the capital of Germany?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Berlin\" : true ,\n \"Lissabon\" : false ,\n \"Leipzig\" : false\n }\n },\n {\n \"id\" : 2 ,\n \"title\" : \"What are valid colors in German?\" ,\n \"type\" : \"MultipleChoice\" ,\n \"items\" : {\n \"rot\" : true ,\n \"schwarz\" : true ,\n \"nero\" : false\n }\n },\n {\n \"id\" : 3 ,\n \"title\" : \"Order the following colors from lightest to darkest.\" ,\n \"type\" : \"Order\" ,\n \"items\" : [\n \"red\" ,\n \"blue\" ,\n \"green\"\n ]\n }\n ],\n \"results\" : [\n {\n \"title\" : \"Thanks for taking the quiz!\" ,\n \"minPercentage\" : 0 ,\n \"maxPercentage\" : 100\n }\n ]\n }\n }\n The quiz above consists of three question blocks and one result block. For this example we want to branch based on the \"What's the capital of Germany?\" question. If the user answers \"Berlin\", we want to show the second question (\"What are valid colors in German?\"). If the user answers \"Lissabon\" or \"Leipzig\", we want to skip the second question and go directly to the third question (\"Order the following colors from lightest to darkest.\"). The logic tree / settings then look like this: {\n \"blockId\" : 1 ,\n \"branchingType\" : \"answer\" ,\n \"rules\" : [\n {\n \"answers\" : [ \"Berlin\" ],\n \"blockId\" : 2 ,\n \"next\" : {\n \"blockId\" : 3\n }\n },\n {\n \"answers\" : [ \"Lissabon\" , \"Leipzig\" ],\n \"blockId\" : 3\n }\n ]\n }\n Note: result blocks are not part of the logic tree in the API. Instead, 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 . Optional: Referencing answers by ID As with the blocks , the answer items can also be referenced by their ID instead of the answer text which makes it less confusing and more deterministic when creating logic rules for complex build configurations. Learn more Step by step guide to convert from answer text to answer IDs: Add explicit IDs to the answers in the items property of the SingleChoice question block: {\n \"id\" : 1 ,\n \"title\" : \"What's the capital of Germany?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n { \"id\" : 11 , \"title\" : \"Berlin\" , \"isCorrect\" : true },\n { \"id\" : 22 , \"title\" : \"Lissabon\" , \"isCorrect\" : false },\n { \"id\" : 33 , \"title\" : \"Leipzig\" , \"isCorrect\" : false }\n ]\n }\n Use the answer IDs (i.e. 11, 22, 33) in the logic settings instead of the answer text: {\n \"blockId\" : 1 ,\n \"branchingType\" : \"answer\" ,\n \"rules\" : [\n {\n \"answers\" : [ 11 ],\n \"blockId\" : 2 ,\n \"next\" : {\n \"blockId\" : 3\n }\n },\n {\n \"answers\" : [ 22 , 33 ],\n \"blockId\" : 3\n }\n ]\n }\n Full example Putting it all together, the full request body to create the quiz with the described logic looks like this: {\n \"type\" : \"Quiz\" ,\n \"build\" : {\n \"title\" : \"Logic example (Builder API)\" ,\n \"blocks\" : [\n {\n \"id\" : 1 ,\n \"title\" : \"What's the capital of Germany?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Berlin\" : true ,\n \"Lissabon\" : false ,\n \"Leipzig\" : false\n }\n },\n {\n \"id\" : 2 ,\n \"title\" : \"What are valid colors in German?\" ,\n \"type\" : \"MultipleChoice\" ,\n \"items\" : {\n \"rot\" : true ,\n \"schwarz\" : true ,\n \"nero\" : false\n },\n \"explanation\" : {\n \"title\" : \"Correct!\" ,\n \"description\" : \"Only 'rot' and 'schwarz' are valid colors in German\"\n }\n },\n {\n \"id\" : 3 ,\n \"title\" : \"Order the following colors from lightest to darkest.\" ,\n \"type\" : \"Order\" ,\n \"items\" : [\n \"red\" ,\n \"blue\" ,\n \"green\"\n ],\n \"itemsShuffled\" : true ,\n \"guesses\" : 3\n }\n ],\n \"logic\" : {\n \"blockId\" : 1 ,\n \"branchingType\" : \"answer\" ,\n \"rules\" : [\n {\n \"answers\" : [ \"Berlin\" ],\n \"blockId\" : 2 ,\n \"next\" : {\n \"blockId\" : 3\n }\n },\n {\n \"answers\" : [ \"Lissabon\" , \"Leipzig\" ],\n \"blockId\" : 3\n }\n ]\n },\n \"results\" : [\n {\n \"title\" : \"Thanks for taking the quiz!\" ,\n \"minPercentage\" : 0 ,\n \"maxPercentage\" : 100\n }\n ]\n }\n }\n Full example 2: Poll with branching on a standalone form dropdown field In this example, we have a poll that starts with a standalone form dropdown field asking the user to select their favorite programming language. Based on the user's selection, we will branch to different questions. {\n \"type\" : \"Poll\" ,\n \"build\" : {\n \"title\" : \"Programming Language Quiz\" ,\n \"blocks\" : [\n {\n \"id\" : 1 ,\n \"title\" : \"Select your favorite programming language:\" ,\n \"type\" : \"FormField\" ,\n \"fieldType\" : \"Dropdown\" ,\n \"items\" : [\n \"Python\" ,\n \"JavaScript\" ,\n \"Java\"\n ]\n },\n {\n \"id\" : 2 ,\n \"title\" : \"Why do you like Python?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"Easy to learn\" ,\n \"Great libraries\" ,\n \"Versatile\"\n ]\n },\n {\n \"id\" : 3 ,\n \"title\" : \"Why do you like JavaScript?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"Web development\" ,\n \"Versatile\" ,\n \"Large community\"\n ]\n },\n {\n \"id\" : 4 ,\n \"title\" : \"Why do you like Java?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"Platform independence\" ,\n \"Strong typing\" ,\n \"Enterprise use\"\n ]\n }\n ],\n \"logic\" : {\n \"blockId\" : 1 ,\n \"branchingType\" : \"answer\" ,\n \"rules\" : [\n {\n \"answers\" : [ \"Python\" ],\n \"blockId\" : 2\n },\n {\n \"answers\" : [ \"JavaScript\" ],\n \"blockId\" : 3\n },\n {\n \"answers\" : [ \"Java\" ],\n \"blockId\" : 4\n }\n ]\n },\n \"results\" : [\n {\n \"title\" : \"Thanks for sharing your preferences!\" ,\n \"minPercentage\" : 0 ,\n \"maxPercentage\" : 100\n }\n ]\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":234,"path":235,"dir":236,"title":237,"description":238,"keywords":239,"body":242},"content:15.Api:3.Build Riddles:5.Advanced features:1.Use media.md","/api/build-riddles/advanced-features/use-media","advanced-features","Use media - Build Riddles","Learn how to use media in your Riddle via API",[240,241],"Adding images / videos / audio","Adding social media content"," Use media You can add media, such as images, videos, audio, and social media content, to any block and result in your riddle. Adding images / videos / audio Any media you add to the API payload will be downloaded and copied to the Riddle file server. This ensures your media is optimized for the web, e.g. by resizing images and converting media to the most efficient and most web-friendly format. The following media types are supported: Images (JPG, PNG, GIF) Videos (MP4) Audio (MP3) Other image/video formats may work, but are not officially supported. If you want to use other media types, please contact us at hello@riddle.com . Example SingleChoice object: {\n \"type\" : \"SingleChoice\" ,\n \"title\" : \"What is the capital of France?\" ,\n \"items\" : {\n \"Berlin\" : false ,\n \"Madrid\" : false ,\n \"Paris\" : true\n },\n \"media\" : \"https://example.com/single-choice-image.jpg\"\n }\n Upload limit Uploading media slows down the building process and our servers. To ensure a smooth experience, we have set a limit of 15 media per riddle. If you need more media, please contact us at hello@riddle.com . Advanced properties You can further customize how your media is displayed by: setting alt tags for accessibility and SEO setting attribution metadata to credit the source setting the background or overlay color (Image only) To do this, convert the media property to an object and add the following properties: Property Required Type Description type ✓ string Set to Image , Video , or Audio url ✓ string The URL of the media you want to add altTag string The alt tag of the media (for accessibility and SEO) attributionText string The attribution text of the media (e.g. photographer name) attributionUrl string A link to the source of the media (e.g. photographer website or profile) backgroundColor string Image only. A CSS color code (e.g. #000000 or rgba(0,0,0,0.5) ) to use as background color for the media overlayColor string Image only. A CSS color code (e.g. #000000 or rgba(0,0,0,0.5) ) to use as overlay color for the media Example object: {\n \"type\" : \"SingleChoice\" ,\n \"title\" : \"What is the capital of France?\" ,\n \"items\" : {\n \"Berlin\" : false ,\n \"Madrid\" : false ,\n \"Paris\" : true\n },\n \"media\" : {\n \"type\" : \"Image\" ,\n \"url\" : \"https://example.com/single-choice-image.jpg\" ,\n \"altTag\" : \"An image showing the Eiffel Tower in Paris\" ,\n \"attributionText\" : \"Photo by John Doe\" ,\n \"attributionUrl\" : \"https://johndoe.com\" ,\n \"backgroundColor\" : \"#000000\" ,\n \"overlayColor\" : \"rgba(0,0,0,0.5)\"\n }\n }\n Video-specific properties Media of type Video supports the following additional properties: Property Required Type Description Default previewImageUrl string The URL of an image to show before the video is played autoplay boolean Set to true to enable autoplay, or false to disable it. false loop boolean Set to true to enable looping, or false to disable it. true controls boolean Set to true to show video controls, or false to hide them. true Example object: {\n \"type\" : \"SingleChoice\" ,\n \"title\" : \"What is the capital of France?\" ,\n \"items\" : {\n \"Berlin\" : false ,\n \"Madrid\" : false ,\n \"Paris\" : true\n },\n \"media\" : {\n \"type\" : \"Video\" ,\n \"url\" : \"https://example.com/single-choice-video.mp4\" ,\n \"previewImageUrl\" : \"https://example.com/single-choice-video-preview.jpg\" ,\n \"autoplay\" : false ,\n \"loop\" : true ,\n \"controls\" : true\n }\n }\n Audio Media of type Audio supports the following properties: Property Required Type Description Default url ✓ string The URL of the audio file you want to add previewImage string The URL of an image to show alongside the audio player autoplay boolean Set to true to enable autoplay, or false to disable it. false loop boolean Set to true to enable looping, or false to disable it. true Example object: {\n \"type\" : \"SingleChoice\" ,\n \"title\" : \"What is the capital of France?\" ,\n \"items\" : {\n \"Berlin\" : false ,\n \"Madrid\" : false ,\n \"Paris\" : true\n },\n \"media\" : {\n \"type\" : \"Audio\" ,\n \"url\" : \"https://example.com/single-choice-audio.mp3\" ,\n \"previewImage\" : \"https://example.com/single-choice-audio-preview.jpg\" ,\n \"autoplay\" : false ,\n \"loop\" : true\n }\n }\n Adding social media content The following social media content types are supported: YouTube videos Vimeo videos X ( formerly Twitter ) posts Add a YouTube video Property Required Type Description Default type ✓ string Set to YouTube videoId ✓ string The YouTube video ID (the part after v= in the URL) autoplay boolean Set to true to enable autoplay, or false to disable it. false loop boolean Set to true to enable looping, or false to disable it. true controls boolean Set to true to show video controls, or false to hide them. false Example object: {\n \"type\" : \"Content\" ,\n \"title\" : \"Welcome to the quiz\" ,\n \"description\" : \"This quiz will test your knowledge about France\" ,\n \"media\" : {\n \"type\" : \"YouTube\" ,\n \"videoId\" : \"dQw4w9WgXcQ\" ,\n \"autoplay\" : false ,\n \"loop\" : true ,\n \"controls\" : false\n }\n }\n Add a Vimeo video Property Required Type Description Default type ✓ string Set to Vimeo videoId ✓ string The Vimeo video ID (the part after the last / in the URL) autoplay boolean Set to true to enable autoplay, or false to disable it. false loop boolean Set to true to enable looping, or false to disable it. true controls boolean Set to true to show video controls, or false to hide them. false Example object: {\n \"type\" : \"Content\" ,\n \"title\" : \"Welcome to the quiz\" ,\n \"description\" : \"This quiz will test your knowledge about France\" ,\n \"media\" : {\n \"type\" : \"Vimeo\" ,\n \"videoId\" : \"76979871\" ,\n \"autoplay\" : false ,\n \"loop\" : true ,\n \"controls\" : false\n }\n }\n Add an X post Property Required Type Description Default type ✓ string Set to X url ✓ string The full URL of the X post, e.g. https://x.com/username/status/1234567890 Example object: {\n \"type\" : \"Content\" ,\n \"title\" : \"Welcome to the quiz\" ,\n \"description\" : \"This quiz will test your knowledge about France\" ,\n \"media\" : {\n \"type\" : \"X\" ,\n \"url\" : \"https://x.com/username/status/1234567890\"\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":244,"path":245,"dir":236,"title":246,"description":247,"keywords":248,"body":252},"content:15.Api:3.Build Riddles:5.Advanced features:2.Dynamic variables.md","/api/build-riddles/advanced-features/dynamic-variables","Dynamic variables - Build Riddles","Learn how to use dynamic variables in Riddles",[249,250,251],"Syntax","Dynamic Riddle variables","Dynamic form variables"," Dynamic variables In the Riddle Creator you can use dynamic variables to personalize / dynamically display any Riddle / form data. You can do the same when building a Riddle via the API - all title and description properties can be personalized with dynamic variables. Syntax The following syntax is used to embed dynamic variables into a property: %riddleVariable\n Example: Welcome back, %name!\n riddleVariable then needs to be replaced with the variable you want to use. Keep reading to learn which variables you can use. Dynamic Riddle variables Available variables Riddle type Variable Description All riddle.id The unique ID of the Riddle All riddle.title The title of the Riddle All riddle.image The image of the Riddle - this will be automatically translated to an image in the email automation / DOI Quiz, Poll result.title The title of the user result Quiz score.number The score of the user as a number Quiz score.percentage The score of the user as a percentage Quiz score.max The maximum achievable score the user could have achieved Example You could personalize the result page by using the variables result.title , score.number , and score.max : {\n \"result\" : {\n \"title\" : \"Your result: %result.title\" ,\n \"description\" : \"You scored %score.number out of %score.max\"\n }\n }\n Dynamic form variables Added form fields can be used in any following blocks as dynamic variables. For example, adding a FormBuilder with two Name fields and one Email field makes the following variables available: %name (this will always be the first Name field) %name1 %name2 %email (this will always be the first Email field) %email1 Here's how you could integrate the variables into a SingleChoice quiz question: {\n \"title\" : \"What's the capital of Germany, %name1 %name2?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Berlin\" : true ,\n \"Lissabon\" : false ,\n \"Leipzig\" : false\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":254,"path":255,"dir":236,"title":256,"description":257,"keywords":258,"body":263},"content:15.Api:3.Build Riddles:5.Advanced features:3.Custom IDs.md","/api/build-riddles/advanced-features/custom-ids","Custom IDs - Build Riddles","Learn how to assign custom IDs to blocks, items and results using the Riddle Builder API",[259,260,261,262],"Custom block IDs","Custom item IDs","Custom result IDs","Full Riddle example with custom IDs"," Assigning custom IDs By default any entries in blocks , results , and items are assigned an auto incremented ID. This behaviour can be changed and the IDs can be set explicitly which makes it easier to later work with the Riddle's stats or webhook data. Additionally it makes it easier to configure custom logic settings based on the IDs you have assigned. Custom block IDs You can assign a custom ID to any block by adding the id property to the block object. The ID must be a non-negative integer (0 or greater) and unique (not used in blocks + result / results ). Example object: {\n \"id\" : 101 ,\n \"title\" : \"The best noodles?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"Spaghetti\" ,\n \"Fusilli\"\n ]\n }\n Custom item IDs You can assign a custom ID to any item by adding the id property to the item object. The ID must be a non-negative integer (0 or greater) and unique (only within the same block). Usually, items are defined as an array of strings, for example: {\n \"items\" : [\n \"Spaghetti\" ,\n \"Fusilli\"\n ]\n }\n To be able to assign custom IDs, you need to change the items definition from an array of strings to an array of objects, for example: {\n \"items\" : [\n {\n \"id\" : 201 ,\n \"title\" : \"Spaghetti\"\n },\n {\n \"id\" : 202 ,\n \"title\" : \"Fusilli\"\n }\n ]\n }\n Custom result IDs You can assign a custom ID to any result by adding the id property to the result object. The ID must be a non-negative integer (0 or greater) and unique (not used in blocks + result / results ). Example simple result: {\n \"id\" : 301 ,\n \"title\" : \"Thank you\" ,\n \"description\" : \"Thanks for your vote.\"\n }\n Example advanced result page with blocks: {\n \"id\" : 302 ,\n \"blocks\" : [\n {\n \"type\" : \"Text\" ,\n \"text\" : \"\u003Ch1>Thank you!\u003C/h1>\u003Cp>Thanks for your vote.\u003C/p>\"\n }\n ]\n }\n Full Riddle example with custom IDs {\n \"type\" : \"Poll\" ,\n \"build\" : {\n \"title\" : \"Favorite color poll\" ,\n \"blocks\" : [\n {\n \"id\" : 101 ,\n \"title\" : \"What's your favorite color?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n {\n \"id\" : 201 ,\n \"title\" : \"green\"\n },\n {\n \"id\" : 202 ,\n \"title\" : \"red\"\n }\n ]\n }\n ],\n \"result\" : {\n \"id\" : 301 ,\n \"title\" : \"Thank you\" ,\n \"description\" : \"Thanks for your vote.\"\n }\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":265,"path":266,"dir":236,"title":267,"description":268,"keywords":269,"body":272},"content:15.Api:3.Build Riddles:5.Advanced features:4.Batch&Async processing.md","/api/build-riddles/advanced-features/batchandasync-processing","Batch & asynchronous processing - Build Riddles","Learn how to build and process Riddles in batches/asynchronously via API",[270,271],"Building in batches","Building single Riddles asynchronously"," Batch and asynchronous processing In some cases where lots of Riddles are needed, it may be more efficient to build them in batches. This drastically reduces the overhead of each HTTP request and allows for faster processing. Additionally, single Riddles can also be built asynchronously - this makes migrating to an asynchronous flow much easier with your existing code and processes. Building in batches A batch is a collection of Riddle builds , sent in one payload to the builder API. Example object For example if I want to create a quiz and poll with one request, only one request to the builder batch API endpoint is needed with the batch property set to an array of build configurations: {\n \"batch\" : [\n {\n \"type\" : \"Quiz\" ,\n \"build\" : {\n \"title\" : \"My new quiz\" ,\n \"blocks\" : [\n {\n \"title\" : \"What is the capital of France?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Berlin\" : false ,\n \"Madrid\" : false ,\n \"Paris\" : true\n }\n }\n ]\n }\n },\n {\n \"type\" : \"Poll\" ,\n \"build\" : {\n \"title\" : \"My new poll\" ,\n \"blocks\" : [\n {\n \"title\" : \"What is your favorite color?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : [\n \"Red\" ,\n \"Green\" ,\n \"Blue\"\n ]\n }\n ]\n }\n }\n ]\n }\n Note: Just like in the normal Builder API endpoint, the parameters publish (to publish all Riddles in the batch) and project (to assign all Riddles in the batch to a specific project) are supported. Important factors to consider when using batches The batch size is limited to 100 Riddles per request. The Riddles are created asynchronously and the response will contain a list of UUIDs for Riddles which are only initialized, i.e. not visible yet in the Creator. Building single Riddles asynchronously Building asynchronously means that a single Riddle build is processed in the background and the response will contain a UUID for the Riddle which is only initialized, i.e. not visible yet in the Creator. Example object To mark the build as asynchronous, the queue property must be set to true in the request. The request would look like this: {\n \"type\" : \"Quiz\" ,\n \"queue\" : true ,\n \"build\" : {\n \"title\" : \"My new quiz\" ,\n \"blocks\" : [\n {\n \"title\" : \"What is the capital of France?\" ,\n \"type\" : \"SingleChoice\" ,\n \"items\" : {\n \"Berlin\" : false ,\n \"Madrid\" : false ,\n \"Paris\" : true\n }\n }\n ]\n }\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":274,"path":275,"dir":236,"title":276,"description":277,"keywords":278,"body":279},"content:15.Api:3.Build Riddles:5.Advanced features:5.Deleting built Riddles.md","/api/build-riddles/advanced-features/deleting-built-riddles","Deleting built Riddles - Build Riddles","Learn how to delete built Riddles via API",[]," Deleting built Riddles In contrast to Riddles which were created through our web interface, Riddles built via the Builder API can be deleted through the API. To delete a Riddle, use the Riddle delete endpoint . The UUID of the Riddle can be found in the response of the Riddle build endpoint . Please be aware that deleting a Riddle is irreversible and will remove all data associated with the Riddle. This includes the Riddle itself, its results, and all data collected from participants. Note: Deleting a Riddle built in the Creator is not possible.",{"id":281,"path":282,"dir":283,"title":284,"description":285,"keywords":286,"body":290},"content:15.Api:4.Generate Riddles with AI:0.Getting started.md","/api/generate-riddles-with-ai/getting-started","generate-riddles-with-ai","Getting started - Generate Riddles with AI","Learn how to generate Riddles with AI via API",[287,288,289,16],"Providing context","Asynchronous generation","API limits and usage"," 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: Topic : Supply a topic or theme for the Riddle, e.g. 'Soccer', 'Harry Potter' 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: {\n \"UUID\" : \"as12Dcs\" ,\n \"type\" : \"Quiz\"\n }\n Tip: You can save this UUID to your database, for example to later call the API to analyse the Riddle's stats or leads. Additionally, you can specify a callback URL to receive a webhook when the Riddle is ready to use. API limits and usage The generative AI API has strict limits per month, differentiated for each plan: Pro : 15 calls/month Business : 30 calls/month Enterprise : 50 calls/month 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: {\n \"current\" : 5 ,\n \"max\" : 50\n }\n 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 15 * 12 = 180. Next steps Create a Quiz, Poll, or Personality Test based on a topic Create a Quiz or Poll based on one or more URLs Generate Riddles in your projects html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":292,"path":293,"dir":283,"title":294,"description":295,"keywords":296,"body":299},"content:15.Api:4.Generate Riddles with AI:1.Topic.md","/api/generate-riddles-with-ai/topic","AI Riddle via topic - Generate Riddles with AI","Learn how to generate Riddles with AI based on a topic via API",[297,298],"Generating different Riddle types","Optional parameters"," Generating AI Riddle via topic A topic or theme can be provided to the generative AI API to get a Riddle surrounding a rather general subject; opposing to specific content, e.g. attributed to an URL. Generating different Riddle types Generate a Quiz To generate a quiz about 'Soccer', use the /riddle-ai/topic/quiz API endpoint. Here is an example payload: {\n \"topic\" : \"Soccer\" ,\n \"numQuestions\" : 5 ,\n \"language\" : \"en\" ,\n \"difficulty\" : \"easy\"\n }\n Generate a Poll To generate a poll about 'Harry Potter', use the /riddle-ai/topic/poll API endpoint. Here is an example payload: {\n \"topic\" : \"Harry Potter\" ,\n \"numQuestions\" : 5 ,\n \"language\" : \"en\"\n }\n Generate a Personality test To generate a personality quiz about 'Harry Potter', use the /riddle-ai/topic/personality API endpoint. Example payload: {\n \"topic\" : \"Harry Potter\" ,\n \"numQuestions\" : 5 ,\n \"language\" : \"en\" ,\n \"numAttributes\" : 0 ,\n \"numPersonalities\" : 3\n }\n Optional parameters There are several optional parameters you can use with every Riddle type to further customize the generated Riddle and control its flow: Property Type Description Default project integer|null The project the generated Riddle will be assigned to; pass NULL if it should be added to the personal project publish boolean Whether to publish the Riddle immediately after generation; pass false to only generate a draft false callbackUrl string A URL to which the generated Riddle will be sent; useful as the generation happens asynchronously Tip: Using the callbackUrl parameter is a good way to avoid having to poll the API for the Riddle ID. You can use this URL to trigger a webhook to your server and be notified when the Riddle is ready to use and for embedding. Example Poll object {\n \"topic\" : \"Harry Potter\" ,\n \"numQuestions\" : 5 ,\n \"language\" : \"en\" ,\n \"project\" : 123 ,\n \"publish\" : true ,\n \"callbackUrl\" : \"https://example.com/callback\"\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":301,"path":302,"dir":283,"title":303,"description":304,"keywords":305,"body":306},"content:15.Api:4.Generate Riddles with AI:2.URL.md","/api/generate-riddles-with-ai/url","AI Riddle via URL - Generate Riddles with AI","Learn how to generate Riddles with AI based on a URL via API",[297,298]," Generating AI Riddle via URL A URL can be provided to the AI API to get a Riddle surrounding a rather specific context, as opposed to general content, e.g., topics or trivia quizzes. Generating different Riddle types Generate a Quiz To generate a quiz about any URL, use the /riddle-ai/url/quiz API endpoint. Here is an example payload which generates a quiz about Riddle's pricing: {\n \"url\" : \"https://www.riddle.com/pricing\" ,\n \"language\" : \"en\" ,\n \"numQuestions\" : 5 ,\n \"difficulty\" : \"easy\"\n }\n Generate a Quiz from multiple URLs You can also generate a single quiz from multiple URLs at once. Use the /riddle-ai/url/quiz/bulk API endpoint and pass the URLs as an array via the urls parameter – the AI combines the content of all pages into one quiz: {\n \"urls\" : [\n \"https://www.riddle.com/pricing\" ,\n \"https://www.riddle.com/quiz-maker\"\n ],\n \"language\" : \"en\" ,\n \"numQuestions\" : 5 ,\n \"difficulty\" : \"easy\"\n }\n Generate a Poll To generate a poll about any URL, use the /riddle-ai/url/poll API endpoint. Here is an example payload which generates a poll about Riddle's pricing (not particularly interesting/engaging, but you get the idea): {\n \"url\" : \"https://www.riddle.com/pricing\" ,\n \"language\" : \"en\" ,\n \"numQuestions\" : 5\n }\n Optional parameters There are several optional parameters you can use with every Riddle type to further customize the generated Riddle and control its flow: Property Type Description Default project integer|null The project the generated Riddle will be assigned to; pass NULL if it should be added to the personal project publish boolean Whether to publish the Riddle immediately after generation; pass false to only generate a draft false callbackUrl string A URL to which the generated Riddle will be sent; useful as the generation happens asynchronously Tip: Using the callbackUrl parameter is a good way to avoid having to poll the API for the Riddle ID. You can use this URL to trigger a webhook to your server and be notified when the Riddle is ready to use and for embedding. Example Poll object {\n \"url\" : \"https://www.riddle.com/pricing\" ,\n \"language\" : \"en\" ,\n \"numQuestions\" : 5 ,\n \"project\" : 123 ,\n \"publish\" : true ,\n \"callbackUrl\" : \"https://example.com/callback\"\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":308,"path":309,"dir":283,"title":310,"description":311,"keywords":312,"body":313},"content:15.Api:4.Generate Riddles with AI:3.Project.md","/api/generate-riddles-with-ai/project","Generate Riddles in your projects - Generate Riddles with AI","Learn how to generate Riddles in your projects via API",[61]," Generate Riddles in your projects By default the project of the accessing API key will be used - this means that if you use an API key created in your personal project the newly generated AI Riddle will always be added to your personal space. To change this you can specify the project in the root to create the Riddle in a specific project. Example The following example generates a Riddle about soccer in the project with the ID 12345 : {\n \"topic\" : \"Soccer\" ,\n \"numQuestions\" : 5 ,\n \"language\" : \"en\" ,\n \"difficulty\" : \"easy\" ,\n \"project\" : 12345\n }\n html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":315,"path":316,"dir":317,"title":318,"description":319,"keywords":320,"body":329},"content:15.Api:5.Manage Riddles:0.Getting started.md","/api/manage-riddles/getting-started","manage-riddles","Getting started - Manage Riddles","Learn how to list, publish, embed, and manage your Riddles via API",[321,322,323,324,325,326,327,328,16],"List your Riddles","Get a single Riddle","Rename a Riddle","Publish or unpublish a Riddle","Get the embed code","Get a QR code","Delete a Riddle","Projects"," 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 10 Riddles per page. You can use any combination of the following optional filters: Property Type Description project integer The ID of the project you want to list the Riddles from; if not sent, the project of the API key is used type string Only return Riddles of this type, e.g. Quiz or Poll ; omit to get all types notType string Exclude Riddles of this type tags integer[] An array of tag IDs the Riddles must be tagged with; learn more about tags status string published , modified , or draft ; omit to get all statuses search string Any search term sortBy string created , published , or modified sortOrder string ASC or DESC page integer The page you want to fetch; if not sent, the first page is returned Example: Fetch the most recently published quizzes matching \"onboarding\": {\n \"type\" : \"Quiz\" ,\n \"status\" : \"published\" ,\n \"search\" : \"onboarding\" ,\n \"sortBy\" : \"published\" ,\n \"sortOrder\" : \"DESC\" ,\n \"page\" : 1\n }\n 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, except project . 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 . Rename a Riddle To rename a Riddle, send the new title to the /riddle/rename/{UUID} endpoint: {\n \"title\" : \"My new Riddle title\"\n }\n Publish or unpublish a Riddle /riddle/publish/{UUID} publishes a Riddle – it becomes available via its public URL and embed code. /riddle/unpublish/{UUID} takes a Riddle offline – the public URL is no longer reachable. 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 the projects the user is a member of. /project/{projectId} returns information about a single project. Next steps Manage tags : Organize your Riddles with tags and use them as list filters. Fetch leads : Retrieve the leads collected by a Riddle. Look at the specification of all available API endpoints : Find out what you can do with the Riddle API. html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":331,"path":332,"dir":317,"title":333,"description":334,"keywords":335,"body":340},"content:15.Api:5.Manage Riddles:1.Tags.md","/api/manage-riddles/tags","Tags - Manage Riddles","Learn how to manage Riddle tags via API",[336,337,338,339],"List all tags","Get the tags of a Riddle","Add a tag to a Riddle","Remove a tag from a Riddle"," Manage tags Tags help you organize your Riddles – and they are the most reliable way to find Riddles again programmatically, as you can filter the Riddle list by tag IDs . List all tags To get all tags and their occurrence counts, use the /tag/list API endpoint. Property Required Type Description project integer|null The project ID you want to get the tags from; pass NULL to explicitly get the user's tags; if nothing is sent, the project of the API key is used Get the tags of a Riddle To get all tags of a single Riddle, use the /tag/riddle/list/{UUID} endpoint with the Riddle's UUID. Add a tag to a Riddle To tag a Riddle, use the /tag/riddle/{UUID} endpoint. Send either name or id : Property Required Type Description name (one of the two) string Creates a new tag with the given name and attaches it to the Riddle id (one of the two) integer Attaches an already existing tag to the Riddle Example: Create and attach a new tag: {\n \"name\" : \"summer-campaign\"\n }\n Remove a tag from a Riddle To remove a tag from a Riddle, use the /tag/riddle/{UUID}/{tag} DELETE endpoint, where tag is the tag ID. The endpoint returns the serialized Riddle with its remaining tags, or HTTP 404 if the given tag + Riddle combination could not be found. html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":342,"path":343,"dir":317,"title":344,"description":345,"keywords":346,"body":348},"content:15.Api:5.Manage Riddles:2.Leads.md","/api/manage-riddles/leads","Leads - Manage Riddles","Learn how to fetch the leads of a Riddle via API",[347,16],"Fetching the leads of a Riddle"," Fetch leads Every form submission in a Riddle is stored as a lead . Besides sending leads to integrations or exporting them in the Creator, you can also fetch them directly via the API – e.g. to sync them into your own CRM or database. Note: The leads endpoint is available for the Business and Enterprise plans. Fetching the leads of a Riddle To fetch the leads of a Riddle, use the /leads/riddle/{UUID} API endpoint. By default the newest 25 leads are returned; use the page and limit parameters to paginate through the leads. You can use the following optional parameters: Property Type Description Default page integer The page you want to return first page limit integer How many results the page should contain (maximum: 200) 25 search string Search term; exact match for an email address, or partial match for data in the current page completed boolean Set to true to only return completed leads; if not sent, all leads are returned orderBy string By which field to order; available: createdAt order string The order of the results; ASC or DESC dateFrom string Only return leads from this date on (format: Y-m-d ) dateTo string Only return leads up to this date (format: Y-m-d ) Example: Fetch the 50 newest completed leads of June 2026: {\n \"page\" : 1 ,\n \"limit\" : 50 ,\n \"completed\" : true ,\n \"orderBy\" : \"createdAt\" ,\n \"order\" : \"DESC\" ,\n \"dateFrom\" : \"2026-06-01\" ,\n \"dateTo\" : \"2026-06-30\"\n }\n Next steps Send leads to integrations : Learn how leads work and how to send them to Google Sheets, Mailchimp, webhooks, and more. Analyze your Riddles : Use the Stats API to analyze views, starts, and submissions. html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"id":350,"path":351,"dir":21,"title":352,"description":7,"keywords":353,"body":354},"content:15.Api:6.Docs.md","/api/docs","API Docs",[]," ",1785317386343]