{
  "openapi": "3.1.0",
  "info": {
    "title": "mysurname.org API",
    "version": "1.0.0",
    "description": "Modern surname meaning/origin lookups, grounded in public-domain 19th/early-20th-century etymological dictionaries. Free to use; no auth required."
  },
  "servers": [{ "url": "/api" }],
  "paths": {
    "/surname": {
      "get": {
        "summary": "Look up a single surname",
        "parameters": [
          { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Smith" }
        ],
        "responses": {
          "200": { "description": "Surname record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurnameRecord" } } } },
          "404": { "description": "Not found" }
        }
      }
    },
    "/search": {
      "get": {
        "summary": "Search surnames by prefix/substring",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 } }
        ],
        "responses": { "200": { "description": "Search results" } }
      }
    },
    "/random": {
      "get": { "summary": "Get a random surname record", "responses": { "200": { "description": "Surname record" } } }
    }
  },
  "components": {
    "schemas": {
      "SurnameRecord": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "surname": { "type": "string" },
          "display_form": { "type": "string" },
          "pronunciation": { "type": "string" },
          "summary": { "type": "string" },
          "origin_type": { "type": "string" },
          "languages_of_origin": { "type": "array", "items": { "type": "string" } },
          "etymology": { "type": "string" },
          "history": { "type": "string" },
          "variant_spellings": { "type": "array", "items": { "type": "string" } },
          "regions_associated": { "type": "array", "items": { "type": "string" } },
          "fun_fact": { "type": "string" },
          "confidence": { "type": "string", "enum": ["sourced", "pattern_inferred", "mixed"] },
          "sources": { "type": "array", "items": { "type": "object" } },
          "rank_us2010": { "type": ["integer", "null"] },
          "count_us2010": { "type": ["integer", "null"] },
          "license_note": { "type": "string" }
        }
      }
    }
  }
}