# kosename.me — REST API

> Read-only JSON API über die kuratierte Wissensbasis deutscher Kosenamen. CC BY 4.0.

## Endpunkte

- `GET https://www.kosename.me/api/names` — alle Einträge (Filter: `category`, `mood`; Paging: `limit`, `offset`).
- `GET https://www.kosename.me/api/names/{slug}` — einzelner Eintrag (Vollformat).
- `GET https://www.kosename.me/api/categories` — alle Kategorien.
- `GET https://www.kosename.me/api/categories/{slug}` — eine Kategorie mit zugeordneten Einträgen.
- `GET https://www.kosename.me/api/search?q={query}` — Volltextsuche mit Score.
- `POST https://www.kosename.me/ask` — NLWeb /ask Endpunkt (JSON oder SSE).
- `POST https://www.kosename.me/mcp` — Model Context Protocol (Streamable HTTP, JSON-RPC 2.0).
- `GET https://www.kosename.me/api/status` — Service-Status + Counts.

## Spec

- OpenAPI 3.1: https://www.kosename.me/openapi.json
- API Catalog (RFC 9727): https://www.kosename.me/.well-known/api-catalog
- OAuth Protected Resource (RFC 9728): https://www.kosename.me/.well-known/oauth-protected-resource
- Web Bot Auth Directory: https://www.kosename.me/.well-known/http-message-signatures-directory

## Auth & Limits

- Auth: keine (public read-only).
- Rate-Limit: 60 req/min/IP. Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After`.
- Höhere Quoten: ai@kosename.me.