Zum Inhalt springen
kosename.me

Entwickler & Agenten

Bau auf kosename.me

Eine kuratierte deutschsprachige Wissensbasis zu Kosenamen — verfügbar als REST-API, MCP-Server, NLWeb-/ask-Endpunkt und über OpenAPI 3.1.

  • No Auth · public read-only
  • 60 req/min/IP
  • CC BY 4.0 · Attribution required
  • CORS *

REST API

JSON-Endpunkte mit CORS, ETag und Rate-Limit-Headern.

  • GET /api/names Alle Einträge listen (Filter: category, mood).
  • GET /api/names/{slug} Voller Eintrag — meaning, origin, usage, examples, FAQ.
  • GET /api/categories Kategorien-Taxonomie.
  • GET /api/categories/{slug} Eine Kategorie mit zugeordneten Einträgen.
  • GET /api/search?q={query} Volltextsuche mit Score.
  • POST /ask NLWeb /ask Natural-Language Endpoint (JSON oder SSE).
  • POST /mcp Model Context Protocol (Streamable HTTP, JSON-RPC 2.0).
  • GET /api/status Service-Status + Counts.

Beispiel: Eintrag holen

bash 
curl -s https://www.kosename.me/api/names/schatzi | jq
200 OK · application/json 
{
  "slug": "schatzi",
  "title": "Schatzi",
  "meaning": "Schatzi ist die Verniedlichung von „Schatz" – der Kosename-Klassiker…",
  "pronunciation": "Schat-zi",
  "ipa": "[ˈʃats.i]",
  "categories": ["partner", "klassisch"],
  "moods": ["partner", "vertraut"],
  "examples": ["Komm her, Schatzi.", "Schatzi, lass uns gehen."],
  "url": "https://www.kosename.me/name/schatzi",
  "license": "CC BY 4.0",
  "lastReviewed": "2026-05-06"
}

Beispiel: Suche

bash 
curl -s "https://www.kosename.me/api/search?q=maus&limit=3" | jq '.items'

Beispiel: Filter nach Kategorie

bash 
curl -s "https://www.kosename.me/api/names?category=tiere&limit=10" \
  | jq '.items[].title'

MCP-Server

Streamable-HTTP-Transport, JSON-RPC 2.0. Server-Card unter /.well-known/mcp/server-card.json.

Tools

  • list_names Alle Einträge listen, optional Filter (category, mood, limit).
  • get_name Vollformat zu einem Slug.
  • list_categories Kategorien-Taxonomie.
  • search Volltextsuche mit Score.

Claude Desktop / Cursor Konfiguration

~/.config/claude/claude_desktop_config.json 
{
  "mcpServers": {
    "kosename-me": {
      "transport": {
        "type": "http",
        "url": "https://www.kosename.me/mcp"
      }
    }
  }
}

Probe — tools/list

bash 
curl -s https://www.kosename.me/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Probe — tools/call get_name

bash 
curl -s https://www.kosename.me/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_name",
      "arguments": { "slug": "schatzi" }
    }
  }'

NLWeb /ask

Microsoft-NLWeb-konformer Endpunkt. JSON-Antwort mit _meta-Envelope, oder SSE-Stream via Header Prefer: streaming=true.

Single-shot Anfrage

bash 
curl -s https://www.kosename.me/ask \
  -H 'Content-Type: application/json' \
  -d '{"query":"Was bedeutet Schatzi?"}'

Streaming (SSE)

bash 
curl -N https://www.kosename.me/ask \
  -H 'Content-Type: application/json' \
  -H 'Prefer: streaming=true' \
  -d '{"query":"tierische Kosenamen für meine Freundin"}'

Antwort-Schema

application/json 
{
  "_meta": {
    "response_type": "nlweb.result",
    "version": "0.4",
    "site": "kosename.me",
    "query": "Was bedeutet Schatzi?",
    "result_count": 3,
    "license": "CC BY 4.0"
  },
  "result": [
    {
      "@type": "Article",
      "name": "Schatzi",
      "url": "https://www.kosename.me/name/schatzi",
      "description": "Schatzi ist die Verniedlichung von „Schatz"…",
      "score": 1.0,
      "citation": "kosename.me — https://www.kosename.me/name/schatzi"
    }
  ]
}

OpenAPI 3.1 & Function Calling

Komplette Spec unter /openapi.json. Direkter Import in ChatGPT Custom GPT Actions, OpenAI Function Calling, Claude tool_use oder Postman.

  • Eindeutige Operation-IDs: listNames, getName, listCategories, searchNames, nlwebAsk, mcpInvoke, getStatus.
  • Strukturierte Schemas: NameSummary, Name, Category, SearchResults, AskResponse, Error.
  • API-Katalog (RFC 9727): /.well-known/api-catalog.

ChatGPT Custom GPT Action — Quick Import

  1. Im GPT Builder → Configure → Actions → Import URL.
  2. URL eintragen: https://www.kosename.me/openapi.json
  3. Authentication: None.
  4. Privacy Policy: https://www.kosename.me/datenschutz

Signed Bots (RFC 9421 · Web Bot Auth)

Schlüssel-Directory unter /.well-known/http-message-signatures-directory.

Für höheres Volumen oder vertrauenswürdige Bot-Identität: einen Ed25519-Public-Key (JWK-Form) an ai@kosename.me schicken — mit kurzer Beschreibung des Use-Cases. Anschließend signiert ihr Requests gemäß RFC 9421; wir verifizieren am Edge.

Webhooks

Beta

Subscription per Mail an ai@kosename.me.

Events

  • entry.publishedNeuer Eintrag online.
  • entry.updatedEintrag inhaltlich geändert (lastReviewed aktualisiert).
  • category.updatedTaxonomie-Änderung.

Payload

POST https://your-endpoint 
X-Kosename-Signature: t=1716203400,v1=…
Content-Type: application/json

{
  "id": "evt_01HQ…",
  "type": "entry.updated",
  "created": "2026-05-20T14:30:00Z",
  "data": {
    "slug": "schatzi",
    "url": "https://www.kosename.me/name/schatzi",
    "lastReviewed": "2026-05-20",
    "changes": ["meaning", "faq[0].answer"]
  }
}

Signatur: HMAC-SHA-256 über {t}.{payload}, Geheimnis wird beim Onboarding vergeben.

Rate-Limits & Response-Header

60 Requests pro Minute pro IP. Headers auf jeder Antwort.

  • X-RateLimit-LimitPer-IP-Minutenbudget (60).
  • X-RateLimit-RemainingVerbleibende Requests im aktuellen Fenster.
  • X-RateLimit-ResetSekunden bis zum nächsten Reset.
  • Retry-AfterBei 429 — Wartezeit bis Retry.

Error Codes

Alle Fehler werden als strukturiertes JSON ausgeliefert.

HTTPcodeBeschreibung
400 bad_request Fehlender oder ungültiger Parameter.
404 not_found Slug oder Resource nicht vorhanden.
429 rate_limited 60 req/min Limit überschritten. Retry-After beachten.
500 internal_error Bug — bitte an security@kosename.me melden.

Beispiel: 404

application/json 
{
  "error": {
    "code": "not_found",
    "message": "No entry for slug \"foo\".",
    "hint": "Try /api/search?q=… or list at /api/names.",
    "docs": "https://www.kosename.me/developers#errors"
  }
}

Discovery

Maschinenlesbare Beschreibungen unter /.well-known/.