Search API Documentation

Overview

The Foe Foundry search API provides both enhanced keyword search and semantic search capabilities for finding monsters in the database.

Endpoints

Enhanced Search (Existing)

Endpoint: POST /api/v1/search/monsters/enhanced

Traditional keyword-based search with facet filtering.

Request Body:

{
  "query": "fire dragon",
  "limit": 10,
  "target_cr": 5.0,
  "min_cr": 1.0,
  "max_cr": 10.0,
  "creature_types": ["dragon", "elemental"]
}

Semantic Search (New)

Endpoint: POST /api/v1/search/monsters/semantic

AI-powered search that understands natural language queries and automatically extracts facets.

Request Body:

{
  "query": "I need a low-level fire dragon for my mountain adventure",
  "limit": 10,
  "model": "gpt-4o-mini"
}

Response: Same format as enhanced search, returns MonsterSearchResult.

Semantic Search Features

Intent Recognition

The semantic search can recognize different search intents:

  • monster: User wants to find a specific monster
  • power: User wants to find abilities/powers
  • catalog: User is asking what monsters exist

Automatic Facet Extraction

The system automatically parses:

  • Creature Types: dragon, humanoid, undead, etc.
  • Challenge Rating: "low level", "CR 5", "high level monsters"
  • Environments: mountain, forest, swamp, underground, etc.
  • Keywords: descriptive terms like "fire", "ancient", "corrupted"

Example Queries

Natural Language Queries

"fire dragons in mountains"
"low level undead for beginners" 
"what ice monsters are available?"
"powerful spellcasters CR 10+"
"forest creatures for my druid campaign"

Structured Queries

"CR 5-8 humanoid spellcasters"
"underground aberrations" 
"legendary dragons"
"constructs with fire damage"

Environment Mapping

The system recognizes these environment aliases:

  • forest/woods → Feywood, TangledForest
  • desert → ParchedSands, BlastedBadlands
  • mountains → LoftyMountains
  • swamp/marsh → UnrelentingMarsh
  • underground/caves → UnderlandRealm
  • city/town → UrbanTownship
  • sea/ocean → RestlessSea
  • hell/hellish → FieryHellscape
  • frozen/ice/arctic → FrozenWastes
  • haunted/cursed → HauntedLands

Fallback Behavior

When the OpenAI API is unavailable, semantic search falls back to:

  1. Basic facet parsing using existing keyword detection
  2. Simple keyword extraction
  3. Regular enhanced search functionality

This ensures the API remains functional even without AI services.

Usage Examples

Python

import requests

# Semantic search
response = requests.post(
    "http://localhost:8080/api/v1/search/monsters/semantic",
    json={
        "query": "fire dragons in mountains for level 5 party",
        "limit": 5
    }
)

monsters = response.json()["monsters"]

JavaScript

const searchMonsters = async (query) => {
  const response = await fetch('/api/v1/search/monsters/semantic', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
      query: query,
      limit: 10 
    })
  });

  const results = await response.json();
  return results.monsters;
};

cURL

curl -X POST -H "Content-Type: application/json" \
  -d '{"query": "ice giants in frozen wasteland", "limit": 5}' \
  http://localhost:8080/api/v1/search/monsters/semantic

Configuration

OpenAI Model Selection

The semantic search supports different OpenAI models:

  • gpt-4o-mini (default) - Fast and cost-effective
  • gpt-4o - More capable but slower
  • gpt-3.5-turbo - Legacy model support

Environment Variables

Required for full semantic search functionality:

export OPENAI_API_KEY="your-api-key-here"

Without this key, the system falls back to keyword-based parsing.