Riddle API documentation
This page holds the complete specification of the Riddle REST API: list and embed your Riddles, retrieve stats and leads, build and edit Riddles with the Builder API, generate Riddles with AI, and manage reusable Question Banks. All endpoints are served under https://www.riddle.com/creator/api/v3/ and authenticate with an API key sent as a Bearer token.
New to the API? Read the getting started guide first – it covers authentication, the response format, and rate limiting in detail.
Frequently asked questions
How do I authenticate against the Riddle API?
Create or copy an API key on the API keys page in the Riddle Creator and send it as a Bearer token in the Authorization header of every request: Authorization: Bearer [your API key].
What is the base URL of the Riddle API?
All endpoints are served under https://www.riddle.com/creator/api/v3/. The specification above lists every available endpoint with example requests and responses.
What are the API rate limits?
The Riddle API is rate limited to 100 requests per minute and 2000 requests per hour, shared across all API keys of your Riddle account. If you exceed the limit, the API returns HTTP 429 with the error code API_RATE_LIMIT_EXCEEDED until the window resets. If you need higher limits, contact us via the support chat or via email.
Which subscription plan do I need to use the API?
The Stats API, the leads endpoint, and the Builder API require a Business or Enterprise plan. The Generative AI API is available with monthly call limits that depend on your plan. If you are unsure whether your plan covers an endpoint, ask us via the support chat.
What format do API responses have?
Every response is JSON. Successful requests return { "success": true, "code": 200, "data": … }, where the type of data depends on the endpoint. Errors return success: false with an HTTP code, a machine-readable error code, a human-readable message, and – for invalid input – a validationErrors array describing each invalid property.
Is there an SDK or an MCP server for the Riddle API?
Yes. If you use PHP, our PHP SDK handles authentication and boilerplate for you. You can also connect your Riddle account to AI assistants like Claude, Cursor, or ChatGPT via the Riddle MCP server to build and analyze Riddles in natural language.
Can I create and edit Riddles programmatically?
Yes. The Builder API creates and edits Quizzes, Polls, Personality quizzes, and other Riddle types from defined build configurations, and the Generative AI API generates complete Riddles from a topic or URL.