{
  "openapi": "3.1.0",
  "info": {
    "title": "Slangora Public API",
    "version": "1.0.0",
    "description": "Read-only access to the Slangora slang dictionary. ~37,000 EN terms, definitions, etymology, register, region, parent/ESL explanations, and metadata. SHA-256 hashed bearer-key auth; 60 req/min + 1,000 req/day on the free tier.",
    "contact": {
      "name": "Slangora",
      "email": "hello@slangora.com",
      "url": "https://slangora.com"
    },
    "license": {
      "name": "CC BY-SA 4.0",
      "url": "https://creativecommons.org/licenses/by-sa/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://slangora.com/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "ApiKeyQuery": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "name": "X-Slangora-Key",
        "in": "header",
        "description": "API key issued at /admin/api-keys. Pass via header or query.",
        "required": true,
        "schema": {
          "type": "string",
          "example": "slng_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        }
      },
      "ApiKeyQuery": {
        "type": "apiKey",
        "name": "api_key",
        "in": "query",
        "description": "API key issued at /admin/api-keys. Pass via header or query.",
        "required": true,
        "schema": {
          "type": "string",
          "example": "slng_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        }
      }
    },
    "schemas": {
      "TermListItem": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "word": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "view_count": {
            "type": "integer"
          },
          "has_audio": {
            "type": "boolean",
            "nullable": true
          },
          "first_attestation_year": {
            "type": "integer",
            "nullable": true
          },
          "platform_origin": {
            "type": "string",
            "nullable": true
          },
          "generation_tag": {
            "type": "string",
            "nullable": true
          }
        }
      }
    }
  },
  "paths": {
    "/terms": {
      "get": {
        "summary": "List EN terms",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "language",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "fr",
                "pt",
                "de",
                "it",
                "ja",
                "zh"
              ],
              "default": "en"
            }
          },
          {
            "name": "letter",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "generation",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "silent",
                "boomer",
                "gen-x",
                "millennial",
                "gen-z",
                "gen-alpha"
              ]
            }
          },
          {
            "name": "platform",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "twitter",
                "reddit",
                "discord",
                "twitch",
                "tumblr",
                "bluesky",
                "youtube",
                "tiktok",
                "vine",
                "fourchan",
                "instagram",
                "facebook",
                "snapchat",
                "texting",
                "irc"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "top",
                "alphabetical",
                "newest"
              ],
              "default": "top"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated term list",
            "headers": {
              "X-Slangora-Tier": {
                "schema": {
                  "type": "string"
                },
                "description": "API key tier"
              },
              "X-Slangora-Daily-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "page": {
                      "type": "integer"
                    },
                    "page_size": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "total_pages": {
                      "type": "integer"
                    },
                    "terms": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TermListItem"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/term/{slug}": {
      "get": {
        "summary": "Get a single term by slug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "language",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "fr",
                "pt",
                "de",
                "it",
                "ja",
                "zh"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full term shape",
            "headers": {
              "X-Slangora-Tier": {
                "schema": {
                  "type": "string"
                },
                "description": "API key tier"
              },
              "X-Slangora-Daily-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "404": {
            "description": "Error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search": {
      "get": {
        "summary": "Search terms (ilike on slug + word)",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2
            }
          },
          {
            "name": "language",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "fr",
                "pt",
                "de",
                "it",
                "ja",
                "zh"
              ],
              "default": "en"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching terms",
            "headers": {
              "X-Slangora-Tier": {
                "schema": {
                  "type": "string"
                },
                "description": "API key tier"
              },
              "X-Slangora-Daily-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/random": {
      "get": {
        "summary": "N random terms (per-language)",
        "parameters": [
          {
            "name": "count",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 1
            }
          },
          {
            "name": "language",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "fr",
                "pt",
                "de",
                "it",
                "ja",
                "zh"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Random terms",
            "headers": {
              "X-Slangora-Tier": {
                "schema": {
                  "type": "string"
                },
                "description": "API key tier"
              },
              "X-Slangora-Daily-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/word-of-day": {
      "get": {
        "summary": "Today's word of the day",
        "responses": {
          "200": {
            "description": "WOTD",
            "headers": {
              "X-Slangora-Tier": {
                "schema": {
                  "type": "string"
                },
                "description": "API key tier"
              },
              "X-Slangora-Daily-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/trending": {
      "get": {
        "summary": "Top trending terms by view_count (per-language)",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "language",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "fr",
                "pt",
                "de",
                "it",
                "ja",
                "zh"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trending list",
            "headers": {
              "X-Slangora-Tier": {
                "schema": {
                  "type": "string"
                },
                "description": "API key tier"
              },
              "X-Slangora-Daily-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Daily-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Used": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Slangora-Minute-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  }
}