{
  "name": "BalochiWords Public Dictionary API",
  "version": "1.0",
  "description": "Read-only JSON API exposing the Balochi–English dictionary for search engines, AI systems, and external integrations.",
  "baseUrl": "https://balochiwords.com/api/public",
  "notes": [
    "All endpoints are read-only. No write, edit, or delete operations are exposed.",
    "Responses are JSON (application/json; charset=utf-8) with permissive CORS.",
    "Best-effort per-instance rate limit of ~60 requests/minute per IP. Known search/AI crawlers are exempted.",
    "Identified by user-agent. Caching: GET responses set Cache-Control: public, max-age=60, s-maxage=300."
  ],
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/public/search",
      "description": "Search dictionary words. Same matching semantics as the public site (case- and diacritic-insensitive; exact > prefix > contains).",
      "params": {
        "q": "Required. Query string (max 100 chars).",
        "dir": "Optional. 'en-bal' or 'bal-en'. Default: both directions.",
        "limit": "Optional. 1–100. Default 25.",
        "offset": "Optional. Default 0."
      },
      "example": "https://balochiwords.com/api/public/search?q=mountain&limit=5",
      "exampleResponse": {
        "query": "mountain",
        "direction": "both",
        "total": 2,
        "limit": 5,
        "offset": 0,
        "results": [
          {
            "id": "mountain",
            "slug": "mountain",
            "word": "mountain",
            "translations": [
              "koh",
              "kawh"
            ],
            "direction": "en-bal",
            "language": "English",
            "url": "/word/mountain"
          }
        ]
      }
    },
    {
      "method": "GET",
      "path": "/api/public/word/{slug}",
      "description": "Fetch all dictionary entries that share a slug. Mirrors the public /word/{slug} page.",
      "params": {
        "slug": "URL-safe slug (lowercase, hyphenated)."
      },
      "example": "https://balochiwords.com/api/public/word/mountain",
      "exampleResponse": {
        "slug": "mountain",
        "url": "/word/mountain",
        "entries": [
          {
            "word": "mountain",
            "translations": [
              "koh",
              "kawh"
            ],
            "direction": "en-bal",
            "language": "English",
            "translationLanguage": "Balochi"
          }
        ]
      }
    },
    {
      "method": "GET",
      "path": "/api/public/entry/{id}",
      "description": "Fetch a single curated dictionary entry by its stable UUID. Archived entries are not returned.",
      "params": {
        "id": "UUID of the dictionary_entries row."
      },
      "example": "https://balochiwords.com/api/public/entry/00000000-0000-0000-0000-000000000000"
    }
  ],
  "attribution": {
    "source": "https://balochiwords.com",
    "license": "See site terms. Please cache responses and attribute BalochiWords.com."
  }
}