Spell Book API

The Spells API provides access to the Jarvis Harry Potter spell database, including spell information, spell types, spell casting examples and random spell generation.

Base Endpoint
/api/spells/[action]/[object]
Part Description
action The operation to perform.
object Optional value used by the selected action.
Available Endpoints
Endpoint Description
/api/spells List spells.
/api/spells/random Returns a random spell.
/api/spells/id/{id} Lookup a spell by internal ID.
/api/spells/name/{name} Lookup a spell by name.
/api/spells/search/{query} Search spell names, descriptions and notes.
/api/spells/type/{type} List spells by type.
/api/spells/types List available spell types.
/api/spells/cast Cast a random spell and return a sentence.
/api/spells/cast/{name} Cast a specific spell.
/api/spells/sentence/{id} Get example sentences for a spell.
/api/spells/random-sentence Return a random spell sentence.
/api/spells/count Spell database statistics.
Query Parameters
Parameter Example Description
limit 25 Maximum results returned.
type Charm Filter spells by spell type.
active true Return only active spells.
nsfw true Include NSFW spell sentences.
Spell Lookup Examples
GET /api/spells/id/1
GET /api/spells/name/Accio
GET /api/spells/name/Expelliarmus
GET /api/spells/name/Lumos
Spell Search Examples
GET /api/spells/search/patronus
GET /api/spells/search/fire
GET /api/spells/search/healing
Spell Type Examples
GET /api/spells/type/Charm
GET /api/spells/type/Curse
GET /api/spells/type/Jinx
GET /api/spells/type/Hex
GET /api/spells/types
Random Spell Examples
GET /api/spells/random
GET /api/spells/random?type=Charm
GET /api/spells/random?type=Curse
Casting Spells

The cast endpoint combines spell information with a randomly selected example sentence from the sentence database. 

GET /api/spells/cast
GET /api/spells/cast/Accio
GET /api/spells/cast/Expelliarmus
GET /api/spells/cast/Lumos
Example Response: 
{
    "id": 1,
    "name": "Accio",
    "type": "Charm",
    "description": "Summons an object.",
    "sentence": "Accio biscuits! The snacks flew across the room."
}
Spell Sentence Examples
GET /api/spells/sentence/1
GET /api/spells/sentence/1?nsfw=true
Example Response: 
[
    {
        "id": 42,
        "spell_book_id": 1,
        "sentence": "Accio keys! The keys shot into Harry's hand.",
        "nsfw": false
    }
]
Random Sentence Examples
GET /api/spells/random-sentence
GET /api/spells/random-sentence?nsfw=true
Example Response: 
{
    "id": 78,
    "spell_book_id": 5,
    "name": "Expelliarmus",
    "type": "Charm",
    "sentence": "The wand flew from the wizard's hand.",
    "nsfw": false
}
Example Spell Response
{
    "id": 1,
    "name": "Accio",
    "type": "Charm",
    "pronunciation": "AK-ee-oh",
    "description": "Summons an object.",
    "etymology": "Derived from Latin meaning 'I summon'.",
    "notes": "Frequently used by Harry Potter.",
    "active": true,
    "created_at": "2026-11-04T00:00:00+00:00",
    "updated_at": "2026-11-04T00:00:00+00:00"
}
Example Types Response
[
    {
        "type": "Charm",
        "spell_count": 84
    },
    {
        "type": "Curse",
        "spell_count": 23
    },
    {
        "type": "Jinx",
        "spell_count": 41
    },
    {
        "type": "Hex",
        "spell_count": 17
    }
]
Example Statistics Response
{
    "spells": 187,
    "active_spells": 184,
    "spell_types": 12,
    "sentences": 542,
    "sfw_sentences": 498,
    "nsfw_sentences": 44
}
Common Use Cases
Use Case Endpoint
Random Harry Potter spell command /api/spells/random
Cast a spell command /api/spells/cast
Lookup spell information /api/spells/name/{spell}
Spell encyclopedia /api/spells
Spell quote generator /api/spells/random-sentence
Harry Potter trivia games /api/spells/types

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.