API Documentation

API Overview

Our API provides access to three core generators:

  • Adventure Hooks - Generate adventure hooks for campaigns
  • NPCs - Generate fully detailed non-player characters
  • Maps - Generate dungeon maps with various themes

Base URL

https://adventureforge.replit.app/api/v1

Authentication

Currently, the API is open for public use without authentication. Rate limiting may be implemented in the future.

Endpoints

Adventure Hooks

Endpoint

POST /api/v1/hooks

Request Parameters

Parameter Type Required Description
setting string No The campaign setting (e.g., baldurs_gate, menzoberranzan, spelljammer)
seed integer No A seed for reproducible generation
params object No Optional parameters to customize the hook (campaign_title, alignment, level_range, etc.)

Example Request

curl -X POST "https://adventureforge.replit.app/api/v1/hooks" \
-H "Content-Type: application/json" \
-d '{
    "setting": "baldurs_gate",
    "seed": 12345,
    "params": {
        "campaign_title": "The Forgotten Path",
        "alignment": "neutral",
        "level_range": "1-4"
    }
}'

Example Response

{
    "campaign_title": "The Forgotten Path",
    "setting_name": "Baldur's Gate",
    "alignment": "neutral",
    "level_range": "1-4",
    "hook_text": "A secret society in Baldur's Gate is searching for lost artifacts...",
    "extended_hook": "The adventure begins when the players discover...",
    "seed": 12345,
    ...
}

NPCs

Endpoint

POST /api/v1/npcs

Request Parameters

Parameter Type Required Description
species string No The species of the NPC (e.g., Human, Elf, Dwarf)
gender string No The gender of the NPC (male, female, indeterminate)
seed integer No A seed for reproducible generation

Example Request

curl -X POST "https://adventureforge.replit.app/api/v1/npcs" \
-H "Content-Type: application/json" \
-d '{
    "species": "Elf",
    "gender": "female",
    "seed": 12345
}'

Example Response

{
    "name": "Aelaara Moonshadow",
    "species": "Elf",
    "gender": "female",
    "personality": "Confident and calculating",
    "quirk": "Always carries a small wooden token carved with ancient runes",
    "flaw": "Holds grudges for centuries",
    "origin": "Forest enclave",
    "profession": "Arcane historian",
    "motivation": "Seeks forgotten knowledge",
    "backstory": "Born under the full moon in a hidden elven sanctuary...",
    "seed": 12345,
    ...
}

Maps

Endpoint

POST /api/v1/maps

Request Parameters

Parameter Type Required Description
width integer No Width of the map (default: 20)
height integer No Height of the map (default: 20)
theme string No Map theme (dungeon, cave, temple, etc.)
seed integer No A seed for reproducible generation
params object No Advanced parameters (min_rooms, max_rooms, min_room_size, max_room_size, corridor_density, feature_density)

Example Request

curl -X POST "https://adventureforge.replit.app/api/v1/maps" \
-H "Content-Type: application/json" \
-d '{
    "width": 20,
    "height": 20,
    "theme": "dungeon",
    "seed": 12345,
    "params": {
        "min_rooms": 5,
        "max_rooms": 10,
        "min_room_size": 3,
        "max_room_size": 8,
        "corridor_density": 0.7,
        "feature_density": 1.0
    }
}'

Example Response

{
    "width": 20,
    "height": 20,
    "theme": "dungeon",
    "seed": 12345,
    "grid": [...],
    "rooms": [...],
    "special_rooms": {...},
    "features": [...]
}

ASCII Map Endpoint

For text-based applications, you can also generate an ASCII representation of the map:

POST /api/v1/maps/ascii

This endpoint accepts the same parameters as the regular map endpoint but returns an ASCII representation of the map.

Example ASCII Response

{
    "width": 20,
    "height": 20,
    "theme": "dungeon",
    "seed": 12345,
    "ascii_map": "####################\n#....#.....#......#\n#....#.....#......#\n#....#.....#......#\n####.#####.########\n#....#.............#\n#....#.............#\n#....#.............#\n####.#####.########\n#.......#.........#\n#.......#.........#\n#.......#.........#\n####################"
}

Error Handling

The API returns standard HTTP status codes:

  • 200 OK - Request was successful
  • 400 Bad Request - Invalid parameters
  • 404 Not Found - Endpoint not found
  • 500 Internal Server Error - Server error occurred

Error responses include a JSON object with an error message:

{
    "error": "Invalid parameter: theme must be one of dungeon, cave, temple"
}

Rate Limiting

To ensure fair usage and system stability, the API implements the following rate limits:

  • Adventure Hooks API: 30 requests per hour
  • NPCs API: 30 requests per hour
  • Maps API: 20 requests per hour
  • ASCII Maps API: 20 requests per hour

Additionally, there is a global limit of:

  • 100 requests per day
  • 30 requests per hour
  • 5 requests per minute

If you exceed these limits, you'll receive a 429 (Too Many Requests) response with information about when you can resume making requests.

Example Clients

We've created a simple Python API client to help you get started with the API. You can download the Python client here.

This example client provides methods for each API endpoint and demonstrates basic usage. Here's a quick example of how to use it:

import api_client

# Generate an adventure hook with a custom seed
hook = api_client.generate_hook(setting="baldurs_gate", seed=12345)

# Generate an NPC with specific species and gender
npc = api_client.generate_npc(species="Elf", gender="female")

# Generate a dungeon map
map_data = api_client.generate_map(width=30, height=30, theme="cave")

# Generate an ASCII representation of a map
ascii_map = api_client.generate_ascii_map(theme="temple")

For browser-based applications, we've also created a JavaScript client. You can download the JavaScript client here.

This client uses modern JavaScript with async/await for clean, Promise-based API calls. Here's an example:

// Generate an adventure hook
generateHook().then(hook => {
    console.log("Generated Hook:", hook.hook_text);
});

// Generate an NPC with specific parameters
generateNPC("Elf", "female").then(npc => {
    console.log("NPC Name:", npc.name);
    console.log("NPC Backstory:", npc.backstory);
});

// Generate a map with a custom seed
generateMap(30, 30, "cave", 12345).then(map => {
    console.log("Map Size:", map.width + "x" + map.height);
    console.log("Number of Rooms:", map.rooms.length);
});

For a modern JavaScript application, you might use it like this:

async function createCampaign() {
    try {
        // Generate a hook
        const hook = await generateHook("baldurs_gate");
        document.getElementById("campaign-title").textContent = hook.campaign_title;
        document.getElementById("hook-text").textContent = hook.hook_text;
        
        // Generate NPCs for the campaign
        const villain = await generateNPC("Tiefling", "male");
        const ally = await generateNPC("Human", "female");
        
        displayNPC(villain, "villain-container");
        displayNPC(ally, "ally-container");
        
        // Generate a dungeon map
        const map = await generateMap(30, 30, "dungeon");
        renderMap(map, "dungeon-map-container");
    } catch (error) {
        console.error("Error creating campaign:", error);
    }
}
Remember to update the BASE_URL in the examples to match your environment.

Contact

If you have questions about the API, please contact @seidmich on X (Twitter).