{
  "openapi": "3.1.0",
  "info": {
    "title": "Fleximbols Public Symbol API",
    "version": "1.0.0",
    "description": "Universal public API for searching, disambiguating, localizing (78 languages), and dynamically transforming 28,000+ AAC and educational symbols.",
    "contact": {
      "name": "Sensory App House",
      "url": "https://sensoryapphouse.com"
    }
  },
  "servers": [
    {
      "url": "https://fleximbols.pages.dev",
      "description": "Cloudflare Pages Production Edge"
    }
  ],
  "paths": {
    "/api/v1/search": {
      "get": {
        "summary": "Search symbols",
        "description": "Search symbols by keyword across 78 languages with category, style, gender, and adult filtering.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search keyword",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "description": "Language code (e.g. en, es, fr, ar, de, zhc, hi)",
            "schema": {
              "type": "string",
              "default": "en"
            }
          },
          {
            "name": "style",
            "in": "query",
            "description": "Symbol style filter",
            "schema": {
              "type": "string",
              "default": "all"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by exact category name",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "gender",
            "in": "query",
            "description": "Gender filter: all, male, female",
            "schema": {
              "type": "string",
              "default": "all"
            }
          },
          {
            "name": "adult",
            "in": "query",
            "description": "Include 18+ / anatomy symbols",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "plurals",
            "in": "query",
            "description": "Include plurals and conjugated tenses",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "alphabets",
            "in": "query",
            "description": "Include alphabet letter symbols",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (max 100)",
            "schema": {
              "type": "integer",
              "default": 24
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful search results",
            "content": {
              "application/json": {}
            }
          },
          "429": {
            "description": "Rate limit exceeded (60 req/min)"
          }
        }
      }
    },
    "/api/v1/disambiguate": {
      "get": {
        "summary": "Disambiguate polysemic AAC concept",
        "description": "Resolves English homonyms (e.g. board, bat, scale, trunk) across categories into domain-accurate localized descriptions.",
        "parameters": [
          {
            "name": "word",
            "in": "query",
            "required": true,
            "description": "Word to disambiguate",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "description": "Target language code",
            "schema": {
              "type": "string",
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Disambiguated senses list"
          },
          "400": {
            "description": "Missing required word parameter"
          }
        }
      }
    },
    "/api/v1/categories": {
      "get": {
        "summary": "List category taxonomy",
        "description": "Returns all categories with symbol counts and localized names in the requested language.",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "description": "Target language code",
            "schema": {
              "type": "string",
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Category taxonomy list"
          }
        }
      }
    },
    "/api/v1/languages": {
      "get": {
        "summary": "List 78 supported languages",
        "description": "Returns all 78 supported languages with native names, English names, flag emojis, and text direction (LTR/RTL).",
        "responses": {
          "200": {
            "description": "Languages list"
          }
        }
      }
    },
    "/api/v1/svg/{style}/{category}/{symbol}": {
      "get": {
        "summary": "Dynamically render transformed SVG",
        "description": "Returns an on-the-fly transformed SVG with National Dress, skin tone, hair color, border, CVI mode, mirror, and clothes recoloring.",
        "parameters": [
          {
            "name": "style",
            "in": "path",
            "required": true,
            "description": "Style key (stick, fluent, toon, anime, simplified, inclusive, kawaii, 3d, lineart)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "path",
            "required": true,
            "description": "Category folder name",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Symbol SVG filename",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "culture",
            "in": "query",
            "description": "National dress culture (60 styles: scottish, arab, bavarian, mexican, etc.)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "skin",
            "in": "query",
            "description": "Skin complexion: light, tan, olive, brown, dark",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hair",
            "in": "query",
            "description": "Hair color: black, brown, darkbrown, blonde, ginger, grey, white, random",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "border",
            "in": "query",
            "description": "Outline thickness: none, thin, medium, thick",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "colour",
            "in": "query",
            "description": "Color palette mode: bold, muted",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cvi",
            "in": "query",
            "description": "Cortical Visual Impairment high-contrast mode: 1 or true",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mirror",
            "in": "query",
            "description": "Mirror flip: 1 or true",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "clothes",
            "in": "query",
            "description": "Clothes recoloring hex (e.g. %232563eb)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transformed SVG image",
            "content": {
              "image/svg+xml": {}
            }
          },
          "404": {
            "description": "Symbol not found"
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "summary": "Library overview and stats",
        "description": "Returns symbol counts, styles, category count, and version metadata.",
        "responses": {
          "200": {
            "description": "Library statistics"
          }
        }
      }
    }
  }
}