Integration

Riddle integration

Riddle is a quiz, poll and form maker for publishers and marketers. Through this integration an agent can list, search, read, rename, publish, unpublish and tag Riddles, get their embed code and QR code, build and edit Riddles from a JSON build configuration (one at a time or in batches, with a dry-run validator), generate quizzes, polls and personality tests with the Riddle AI from a topic or web pages, read stats for a Riddle, project or account, and manage reusable question banks and their items. Stats and the Builder API need a Business or Enterprise plan, Looker Studio links an Enterprise plan. Lead (form submission) and leaderboard entry routes are not exposed because they return participants' personal data, and the legacy Riddle 1.0 routes are left out. A Riddle's raw content and publish settings are not returned (they can hold form and integration settings); its content is read as a build configuration instead. Authentication is an API key from the Riddle Creator's API keys page, sent as Authorization: Bearer <key>; the rate limit is 100 requests per minute and 2000 per hour, shared by all keys of the account.

Connect Riddle How integrations work

Ask it in chat

Say what should happen.
The workflow builds itself.

When this happens, do that in Riddle.Built from the 60 Riddle tools below, on the connection you add once.

What you can do with Riddle

Each of these is one operation on one endpoint, available both as a workflow step and as a tool an AI agent can call on its own. Nothing bundles several operations into one action, so what a run did stays readable afterwards.

Most endpoints run on the free plan. A few, mainly the ones that publish on your behalf, need a paid plan.

Riddle, 6 operations

add_riddle_tagAdd riddle tagPOSTTags a Riddle: send name to create a new tag and attach it, or id to attach an existing tag (from list_tags). Returns the Riddle with its tags.
delete_riddleDelete riddleDELETEPermanently deletes a Riddle built through the Builder API or generated by the Riddle AI, with its results and all participant data; Riddles made in the Creator are refused. Send dryRun=1 to only check.
get_riddleGet riddleGETReads one Riddle: title, type, owner and project, tags, cover image, features (form, call to action, connected Riddles), plan level, preset id and dates. For its blocks and answer IDs use get_riddle_build_config.
list_account_riddlesList account riddlesPOSTLists the Riddles of the whole account (personal project plus every project), with the same filters, paging and pagination object as list_riddles except project.
list_riddlesList riddlesPOSTLists the Riddles of a project (default: the API key's project), filtered by type, tags, status, origin or search, sorted and paged with page and pageSize; pagination.hasMore says whether more pages exist.
remove_riddle_tagRemove riddle tagDELETERemoves a tag from a Riddle and returns the Riddle with its remaining tags; the tag itself is deleted once neither a Riddle nor a question bank uses it.

List, 5 operations

list_projectsList projectsGETLists the projects the user is a member of (id, name, image). All of them come back in one answer unless page and pageSize are sent, which adds a pagination object.
list_question_banksList question banksGETLists the question banks of a project (default: the API key's project), filtered by type, tags or title search, sorted and paged (pageSize default 12, at most 50).
list_question_bank_tagsList question bank tagsGETLists the tags applied to at least one question bank, with how many banks carry each.
list_riddle_tagsList riddle tagsGETLists the tags of one Riddle.
list_tagsList tagsGETLists the tags of a project with how many Riddles use each (count only counts Riddles; question banks share the same tags).

Stats, 5 operations

fetch_statsFetch statsPOSTReturns the stats of a Riddle, project or user (namespace plus entityId): global views, starts, finishes, leads and time, device, OS, region and domain counts, and per-block stats. Business or Enterprise plan.
fetch_stats_overviewFetch stats overviewPOSTReturns the stats of a Riddle, project or user split into several data points over the date range (for charts). Business or Enterprise plan.
get_project_stats_breakdownGet project stats breakdownPOSTReturns a stats breakdown of every Riddle of a project, keyed by Riddle. Without dates, the last month. Not available for project API keys; on a timeout, ask for a smaller date range. Business or Enterprise.
get_riddle_stats_breakdownGet riddle stats breakdownPOSTReturns the stats of one Riddle per block and result page, with each choice's title and count, plus device, OS, region and domain counts. Business or Enterprise plan. Without dates, all-time stats.
get_user_stats_breakdownGet user stats breakdownPOSTReturns a stats breakdown of every Riddle of the user and their projects, keyed by Riddle; the slowest breakdown. Without dates, the last month. Not available for project API keys. Business or Enterprise.

Item, 4 operations

create_question_bank_itemCreate question bank itemPOSTAdds a question (item) to a question bank's draft; it reaches Riddles only after publish_question_bank. Returns the item with the value IDs assigned.
delete_question_bank_itemDelete question bank itemDELETERemoves an item from a question bank's draft; Riddles stop drawing it after publish_question_bank. Returns whether the bank now has unpublished changes.
list_question_bank_itemsList question bank itemsGETLists the items (questions) of a question bank, filtered by search, blockType, category or a difficulty range; all at once unless page is sent.
update_question_bank_itemUpdate question bank itemPUTReplaces a question bank item: send all four fields again, because a column left out is removed. The blockType must stay the same. Read the current item with list_question_bank_items first.

Question bank, 3 operations

create_question_bankCreate question bankPOSTCreates an empty question bank of type Quiz or Poll (the type cannot change later) and returns it with its id. Add questions with create_question_bank_item, then publish_question_bank.
delete_question_bankDelete question bankDELETEPermanently deletes a question bank and all its items. Refused with QUESTION_BANK_INTERDEPENDENCY while any Riddle (even an unpublished draft) still references it.
get_question_bankGet question bankGETReads one question bank: title, type, tags, published and draft item counts, whether it has unpublished changes, its categories and the Riddles that use it.

Riddle builder, 3 operations

build_riddleBuild riddlePOSTCreates a Riddle of any type (Quiz, Poll, Personality, Form, Predictor, Minigame, Story, Leaderboard, Placeholder) from a build configuration. publish true takes it live at once; queue true builds it in the background. Business or Enterprise.
edit_riddle_buildEdit riddle buildPUTEdits a Riddle that was built through the API or generated by the Riddle AI: send only what changes; blocks and items are addressed by the id get_riddle_build_config returns. With publish true the edit goes live. Business or Enterprise.
get_riddle_build_configGet riddle build configGETReads any Riddle back as a build configuration (build), with the id of every block and item, nextBlockId for new blocks, and warnings for content the configuration cannot express. Business or Enterprise plan.

Poll, 2 operations

generate_poll_from_topicGenerate poll from topicPOSTStarts generating a poll about a topic with the Riddle AI and returns its UUID at once; poll get_ai_generation_status until isFinished. Uses one monthly AI generation (get_ai_usage).
generate_poll_from_urlGenerate poll from urlPOSTStarts generating a poll from the content of one web page with the Riddle AI and returns its UUID at once; poll get_ai_generation_status until isFinished. Uses one monthly AI generation (get_ai_usage).

Preset, 2 operations

get_riddle_presetGet riddle presetGETReads the effective preset (design) settings of a Riddle; properties the Riddle does not set itself are filled from its project's preset.
list_builder_presetsList builder presetsGETLists the preset and palette IDs and names of a project, for the preset settings of a build configuration. Business or Enterprise plan.

Project, 2 operations

get_projectGet projectGETReads one project (id, name, cover image).
get_project_looker_studio_linkGet project looker studio linkGETReturns a Looker Studio link that creates an overview report for all Riddles of a project (Enterprise plan only).

Publish, 2 operations

publish_question_bankPublish question bankPOSTPublishes a question bank: copies every item's draft over its published state, so Riddles that draw from the bank get the new questions.
publish_riddlePublish riddlePOSTPublishes a Riddle so it is reachable at its public URL and embed code; the answer is the Riddle plus validationWarnings. A refused publish names every reason in validationErrors.

Quiz, 2 operations

generate_quiz_from_topicGenerate quiz from topicPOSTStarts generating a quiz about a topic with the Riddle AI and returns its UUID at once; poll get_ai_generation_status until isFinished. Uses one monthly AI generation (get_ai_usage).
generate_quiz_from_urlGenerate quiz from urlPOSTStarts generating a quiz from the content of one web page with the Riddle AI and returns its UUID at once; poll get_ai_generation_status until isFinished. Uses one monthly AI generation (get_ai_usage).

Rename, 2 operations

rename_question_bankRename question bankPUTChanges the title of a question bank (at most 255 characters).
rename_riddleRename riddlePOSTChanges the title of a Riddle.

Tag, 2 operations

add_question_bank_tagAdd question bank tagPOSTTags a question bank: send tagName to create a new tag, or tagId to apply an existing one. Returns the bank with its tags.
remove_question_bank_tagRemove question bank tagDELETERemoves a tag from a question bank and returns the bank with its remaining tags.

Account, 1 operation

get_account_looker_studio_linkGet account looker studio linkGETReturns a Looker Studio link that creates an overview report for the whole account: every project the opening user may view plus their personal project (Enterprise plan only).

Batch, 1 operation

build_riddles_batchBuild riddles batchPOSTStarts building 1 to 100 Riddles in the background from one request and returns their UUIDs at once (the Riddles stay empty until built); with publish true every one goes live. Business or Enterprise plan.

Block type column, 1 operation

list_question_bank_block_typesList question bank block typesGETLists the block types a Quiz or Poll question bank supports, with each type's columns and how many values each column needs (0 optional, 1 at least one).

Bulk, 1 operation

generate_quiz_from_urlsGenerate quiz from urlsPOSTStarts generating one quiz from the combined content of several web pages and returns its UUID at once; poll get_ai_generation_status until isFinished. Uses one monthly AI generation (get_ai_usage).

Default, 1 operation

list_default_palettesList default palettesGETLists Riddle's default colour palettes.

Discard change, 1 operation

discard_question_bank_changesDiscard question bank changesPOSTResets every item of a question bank to its published state; items that were never published are removed.

Duplicate, 1 operation

duplicate_question_bankDuplicate question bankPOSTCopies a question bank (yours or a public template) and all its items into a new bank you own.

Embed code, 1 operation

get_riddle_embed_codeGet riddle embed codeGETReturns the HTML embed code of a published Riddle as a string in data, ready to place on a web page. Also works with old Riddle 1.0 IDs.

Font family, 1 operation

list_font_familiesList font familiesGETLists the font family names a build configuration can use (button and share result page blocks). Business or Enterprise plan.

Looker studio link, 1 operation

get_riddle_looker_studio_linkGet riddle looker studio linkGETReturns a Looker Studio link that creates a ready-made report for one Riddle in one click (Enterprise plan only).

Note, 1 operation

update_question_bank_notesUpdate question bank notesPUTReplaces the free-form notes of a question bank with the string sent.

Personal, 1 operation

get_personal_looker_studio_linkGet personal looker studio linkGETReturns a Looker Studio link that creates an overview report for the personal project of the opening user (Enterprise plan only).

Personality, 1 operation

generate_personality_test_from_topicGenerate personality test from topicPOSTStarts generating a personality test about a topic with the Riddle AI and returns its UUID at once; poll get_ai_generation_status until isFinished. Uses one monthly AI generation (get_ai_usage).

Qr code, 1 operation

get_riddle_qr_codeGet riddle qr codeGETReturns a QR code image for a published Riddle, as a base64 data URL in data.qrCode, for print material.

Riddle item, 1 operation

get_question_bank_block_inventoryGet question bank block inventoryGETFor a QuestionBank block of a Riddle, counts the published items each of its criteria (block type and category) currently matches, to check a bank holds enough questions before publishing.

Status, 1 operation

get_ai_generation_statusGet ai generation statusGETReads where a Riddle AI generation stands: status pending (wait retryAfterSeconds and call again), completed (ready to use) or failed (error says why). isFinished is true once it completed or failed.

Template list, 1 operation

list_question_bank_templatesList question bank templatesGETLists Riddle's public template question banks, with their categories; duplicate_question_bank copies one into your account.

Unpublish, 1 operation

unpublish_riddleUnpublish riddlePOSTTakes a published Riddle offline: its public URL is no longer reachable and embeds stop showing it.

Usage, 1 operation

get_ai_usageGet ai usageGETReturns how many Riddle AI generations the API key's owner has used (current) out of the allowance (max). On annual billing the allowance may be reported multiplied by 12.

Validate, 1 operation

validate_build_configsValidate build configsPOSTDry-runs 1 to 20 build configurations exactly as build_riddle or edit_riddle_build would check them, without creating or changing anything; read valid and each item's errors, not the status code. Business or Enterprise plan.

Use Riddle from Claude Code, Cursor or Codex

Connect Riddle in LiveContext, create an API key in Settings, then add the LiveContext MCP server to your client. Its Riddle operations become tools the client can call, next to every other integration you connected.

Claude Code

claude mcp add --transport http livecontext https://livecontext.ai/mcp --header "X-API-Key: YOUR_API_KEY"

Codex (~/.codex/config.toml)

[mcp_servers.livecontext]
url = "https://livecontext.ai/mcp"

[mcp_servers.livecontext.http_headers]
"X-API-Key" = "YOUR_API_KEY"

Cursor, Claude Desktop and other JSON configs

{
  "mcpServers": {
    "livecontext": {
      "type": "http",
      "url": "https://livecontext.ai/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Set up the MCP server step by step

How to connect Riddle

Create your workspace
Sign up free. Nothing to install.
Connect Riddle once
Add your Riddle connection in Settings. Every tool from this integration reuses it, and secrets are encrypted at rest and visible only to you.
Describe the job in chat
The workflow builds itself in front of you and picks the endpoints it needs. Drag the steps yourself on the canvas whenever you would rather be explicit.