{
  "openapi": "3.1.0",
  "info": {
    "title": "Animetrics API",
    "description": "Anime character, work, staff, and studio database with AI-analyzed attributes",
    "version": "0.3.0"
  },
  "servers": [
    { "url": "https://animetrics.instrial.com/api" }
  ],
  "paths": {
    "/characters": {
      "get": {
        "summary": "Search or list characters",
        "parameters": [
          { "name": "q", "in": "query", "description": "Search by name, trait, archetype, hair color, species, etc.", "schema": { "type": "string" } },
          { "name": "id", "in": "query", "description": "Get single character by internal ID", "schema": { "type": "integer" } },
          { "name": "anilist_id", "in": "query", "description": "Get character by AniList character ID", "schema": { "type": "integer" } },
          { "name": "work_id", "in": "query", "description": "List all characters in a work/franchise", "schema": { "type": "integer" } },
          { "name": "staff_id", "in": "query", "description": "List all characters voiced by a staff member", "schema": { "type": "integer" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } }
        ],
        "responses": {
          "200": { "description": "Character list or single character with facts" }
        }
      }
    },
    "/works": {
      "get": {
        "summary": "Search or list anime works (franchises)",
        "parameters": [
          { "name": "q", "in": "query", "description": "Search by title or genre", "schema": { "type": "string" } },
          { "name": "id", "in": "query", "description": "Get single work with media entries and characters", "schema": { "type": "integer" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } }
        ],
        "responses": {
          "200": { "description": "Work list or single work with characters and media" }
        }
      }
    },
    "/staff": {
      "get": {
        "summary": "Search or list staff and voice actors",
        "parameters": [
          { "name": "q", "in": "query", "description": "Search by name", "schema": { "type": "string" } },
          { "name": "id", "in": "query", "description": "Get single staff with voice acting roles and staff credits", "schema": { "type": "integer" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } }
        ],
        "responses": {
          "200": { "description": "Staff list or single staff with roles" }
        }
      }
    },
    "/search": {
      "get": {
        "summary": "Unified search across characters, works, staff, and studios",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "description": "Search query — name, trait, archetype, genre, species, etc.", "schema": { "type": "string" } },
          { "name": "type", "in": "query", "description": "Filter to specific type: characters, works, staff, or studios", "schema": { "type": "string", "enum": ["characters", "works", "staff", "studios"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 20 } }
        ],
        "responses": {
          "200": { "description": "Results grouped by type: characters, works, staff, studios" }
        }
      }
    },
    "/studios": {
      "get": {
        "summary": "Search or list anime studios",
        "parameters": [
          { "name": "q", "in": "query", "description": "Search by studio name", "schema": { "type": "string" } },
          { "name": "id", "in": "query", "description": "Get single studio with productions list", "schema": { "type": "integer" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } }
        ],
        "responses": {
          "200": { "description": "Studio list or single studio with productions" }
        }
      }
    },
    "/stats": {
      "get": {
        "summary": "Database statistics and API directory",
        "responses": {
          "200": { "description": "Counts for all entity types, enrichment stats, and API endpoint directory" }
        }
      }
    },
    "/random": {
      "get": {
        "summary": "Redirect to a random character or work",
        "parameters": [
          { "name": "type", "in": "query", "description": "'character' or 'work'", "schema": { "type": "string", "default": "character" } }
        ],
        "responses": {
          "302": { "description": "Redirect to random entity page" }
        }
      }
    }
  }
}