Riddles API

The Riddles API provides access to the Jarvis riddle database, including riddle retrieval, answer validation, answer reveals, searching and riddle statistics.

Base Endpoint
/api/riddles/[action]/[object]
Part Description
action The operation being requested.
object Optional value used by the chosen action.
Available Endpoints
Endpoint Description
/api/riddles List active riddles.
/api/riddles/random Returns a random riddle.
/api/riddles/id/{id} Returns a riddle by ID.
/api/riddles/reveal/{id} Returns both the riddle and answer.
/api/riddles/answer/{id} Returns only the answer.
/api/riddles/check/{id} Checks a submitted answer.
/api/riddles/search/{query} Search riddles.
/api/riddles/random-answer Returns a random riddle with answer.
/api/riddles/count Riddle database statistics.
Query Parameters
Parameter Example Description
limit 25 Maximum results returned.
answer footsteps Answer supplied to the check endpoint.
active true Filter active riddles.
Important: Most endpoints intentionally hide the answer to prevent users accidentally seeing solutions. Use the answer or reveal endpoints when the answer is required.
Random Riddle Examples
GET /api/riddles/random
GET /api/riddles/random?active=true
Example Response: 
{
    "id": 42,
    "riddle": "The more you take, the more you leave behind. What am I?"
}
Riddle Lookup Examples
GET /api/riddles/id/42
GET /api/riddles/id/100
Example Response: 
{
    "id": 42,
    "riddle": "The more you take, the more you leave behind. What am I?"
}
Answer Lookup Examples
GET /api/riddles/answer/42
Example Response: 
{
    "id": 42,
    "answer": "Footsteps"
}
Reveal Examples
GET /api/riddles/reveal/42
GET /api/riddles/reveal/10
Example Response: 
{
    "id": 42,
    "riddle": "The more you take, the more you leave behind. What am I?",
    "answer": "Footsteps"
}
Answer Validation Examples
GET /api/riddles/check/42?answer=footsteps
GET /api/riddles/check/42?answer=shadow
Correct Answer Example: 
{
    "correct": true,
    "answer": "Footsteps"
}
Incorrect Answer Example: 
{
    "correct": false,
    "answer": "Footsteps"
}
Search Examples
GET /api/riddles/search/time
GET /api/riddles/search/water
GET /api/riddles/search/shadow
Example Response: 
[
    {
        "id": 18,
        "riddle": "What runs but never walks?"
    },
    {
        "id": 76,
        "riddle": "What gets wetter the more it dries?"
    }
]
Random Reveal Examples
GET /api/riddles/random-answer
Example Response: 
{
    "id": 77,
    "riddle": "What has keys but can't open locks?",
    "answer": "A Piano"
}
Example Statistics
GET /api/riddles/count
Example Response: 
{
    "total": 1524,
    "active": 1490,
    "inactive": 34
}
Common Discord Bot Use Cases
Feature Recommended Endpoint
Daily riddle /api/riddles/random
Riddle slash command /api/riddles/random
Reveal answer button /api/riddles/answer/{id}
Answer verification /api/riddles/check/{id}
Riddle browser /api/riddles
Admin review tools /api/riddles/reveal/{id}
Example Riddle Workflow
  1. Retrieve a random riddle:
GET /api/riddles/random
  1. User submits their answer:
GET /api/riddles/check/42?answer=footsteps
  1. If needed, reveal the answer:
GET /api/riddles/answer/42

This workflow makes the API ideal for Discord commands, web games, trivia events and automated challenge systems.

Authentication & Rate Limits

All Jarvis APIs require a valid API token. Tokens are issued through the Jarvis Developer Portal and are associated with an account plan which determines access levels and request limits.

Authentication

Every request must include a valid API token. Requests made without a token or with an invalid token will be rejected.

Authorization Header (Recommended)
Authorization: YOUR_API_TOKEN
X-API-Token Header
X-API-Token: YOUR_API_TOKEN
Query String
GET /api/flags/random?token=YOUR_API_TOKEN
For security reasons, the Authorization header method is strongly recommended. Avoid exposing API tokens in URLs where possible.
Example Requests
cURL
curl \
-H "Authorization: YOUR_API_TOKEN" \
https://jarvisbot.uk/api/flags/random
JavaScript (Fetch)
fetch("https://jarvisbot.uk/api/jokes/random", {
    headers: {
        "Authorization": "YOUR_API_TOKEN"
    }
})
.then(r => r.json())
.then(console.log);
PHP
$response = file_get_contents(
    "https://jarvisbot.uk/api/questions/random",
    false,
    stream_context_create([
        'http' => [
            'header' => [
                'Authorization: YOUR_API_TOKEN'
            ]
        ]
    ])
);

$data = json_decode($response, true);
Account Plans
Plan Daily Requests API Access
Free 100 Requests Basic APIs
Premium 10,000 Requests All APIs
Enterprise Unlimited All APIs + Priority Support
Rate Limiting

API usage is automatically monitored based on your account type. Once your limit is reached, requests will be temporarily blocked until your allowance resets.

Plan Limit Window
Free 100 Requests 24 Hours
Premium 10,000 Requests 24 Hours
Enterprise Unlimited No Restriction
Authentication Error Response
{
    "success": false,
    "error": "invalidToken",
    "msg": "API token required"
}
Invalid Token Response
{
    "success": false,
    "error": "invalidToken",
    "msg": "Invalid API token"
}
Rate Limit Response
{
    "success": false,
    "error": "rateLimit",
    "msg": "API limit exceeded",
    "plan": "free",
    "limit": 100
}
Best Practices
  • Store API tokens securely and never expose them publicly.
  • Use the Authorization header whenever possible.
  • Cache responses where appropriate to reduce API calls.
  • Monitor your daily usage to avoid rate limiting.
  • Upgrade your account if your application requires higher throughput.
Supported APIs
  • Flags API
  • Dictionary API
  • Questions API
  • Riddles API
  • Jokes API
  • Pickup Lines API
  • Truth Or Dare API
  • Harry Potter Spells API
  • Future Jarvis APIs
Need additional capacity or custom limits? Contact the Jarvis team to discuss Premium and Enterprise API access.