API und MCP-Server

In English

THILO SKYE is a drone photo and film studio in Wiesbaden, Germany. This page is the API documentation and developer portal for its machine-readable surface: an MCP server (Streamable HTTP, JSON-RPC 2.0, manifest at /.well-known/mcp), an OpenAPI 3.1 specification, two static JSON lists and one endpoint that prepares a contact link. Every one of them is catalogued at /.well-known/api-catalog (RFC 9727).

There is no authentication: nothing here is private and nothing writes. The API is versioned by header, and the deprecation policy is stated below — a breaking change takes a new version number, and the old one keeps answering for at least 90 days carrying Deprecation and Sunset. The rest of this page is in German; the endpoints, examples and error codes in it are language-independent.

MCP-Server

Streamable HTTP, JSON-RPC 2.0, zustandslos — keine Session, kein SSE-Stream. Endpunkt: POST /mcp. Der Handshake steht unter /.well-known/mcp, die Protokollversion ist 2025-06-18. Es gibt keine Authentifizierung, weil alles hier öffentlich ist und nichts schreibt.

Werkzeuge

• list_use_cases — Einsatzbereiche auflisten
• list_projects — Projekte auflisten
• create_contact_link — Anfrage vorbereiten

REST

Dieselben drei Vorgänge als HTTP, beschrieben in /openapi.json (OpenAPI 3.1).

Eine Anfrage vorbereiten

create_contact_link und POST /api/kontakt-link tun dasselbe: Sie prüfen einen Entwurf und geben einen Link auf /kontakt zurück, in dem die Felder schon ausgefüllt sind.

Verschickt wird dabei nichts. Das Formular verlangt eine Datenschutz-Einwilligung, und die kann nur die anfragende Person selbst geben. Sie liest den Entwurf, ändert ihn wenn nötig, setzt den Haken und schickt ab. Gespeichert wird der Entwurf nirgends — er wird geprüft und in die Adresse des Links geschrieben, mehr nicht.

Pflichtfelder: name, email, ort, nachricht. Optional: telefon, thema. Jedes Feld fasst höchstens 5.000 Zeichen. Fehlt etwas, kommt eine 422 zurück, die benennt welches Feld — frag dann die anfragende Person, statt die Angabe zu erfinden.

Beispiele

Alles hier ist ohne Schlüssel aufrufbar, also lässt sich jedes Beispiel so wie es dasteht einmal ausführen.

Einsatzbereiche holen

curl -s https://web.thiloskye.workers.dev/api/use-cases.json

Antwort, gekürzt:

{
  "useCases": [
    {
      "id": "immobilien",
      "title": "Immobilien",
      "status": "live",
      "headline": "Großartige Aufnahmen deiner Immobilie.",
      "description": "Für Exposé, Website, Social Media und Vermarktung.",
      "url": "https://web.thiloskye.workers.dev/immobilien"
    }
  ]
}

Eine Anfrage vorbereiten

curl -s https://web.thiloskye.workers.dev/api/kontakt-link \
  -H 'content-type: application/json' \
  -d '{"name":"Anna Beispiel","email":"anna@example.com","ort":"Stadtvilla in Wiesbaden-Sonnenberg","nachricht":"Wir wollen die Lage zeigen, nicht nur das Haus.","thema":"immobilien"}'

Antwort:

{
  "url": "https://web.thiloskye.workers.dev/kontakt?name=Anna+Beispiel&…#kontakt",
  "sent": false,
  "detail": "Diese Anfrage ist NICHT verschickt. …"
}

Wenn etwas fehlt

Ohne ort und nachricht kommt eine 422, die benennt welches Feld — nicht ein Formular-Link mit erfundenem Inhalt:

HTTP/1.1 422
content-type: application/problem+json

{
  "type": "https://web.thiloskye.workers.dev/api#fehler-incomplete-draft",
  "title": "Anfrage unvollständig",
  "status": 422,
  "code": "incomplete_draft",
  "problems": [
    { "field": "ort", "problem": "fehlt" },
    { "field": "nachricht", "problem": "fehlt" }
  ],
  "required": ["name", "email", "ort", "nachricht"]
}

Über den MCP-Server

curl -s https://web.thiloskye.workers.dev/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Authentifizierung

Keine. Es gibt keine API-Keys, keine Tokens und kein OAuth — alles hier ist öffentlich und nichts schreibt. Schick keinen Authorization-Header; er wird ignoriert.

Versionierung und Abkündigung

Die aktuelle Version ist 1. Jede Antwort trägt sie im HeaderAPI-Version. Die Version steht im Header und nicht im Pfad, weil die Pfade bereits veröffentlicht sind — sie zu verschieben würde genau das brechen, wofür Versionierung da ist.

Eine brechende Änderung bekommt eine neue Versionsnummer. Die alte antwortet danachmindestens 90 Tage weiter und trägt dabei Deprecation (RFC 9745) und Sunset (RFC 8594) mit dem Abschalttermin.

Rate-Limit

POST /api/kontakt-link und /mcp sind auf 60 Anfragen pro Minute und IP begrenzt. Die statischen Listen sind es nicht — das sind Dateien. Jede Antwort trägtRateLimit-Policy und RateLimit-Limit, eine 429zusätzlich Retry-After.

Ein RateLimit-Remaining gibt es bewusst nicht: der Zähler liegt in Cloudflares Limiter und wird nicht herausgegeben. Eine erfundene Zahl wäre schlimmer als keine.

Fehler

Jeder Fehler ist ein application/problem+json nach RFC 9457 — daran ist er ohne Statuscode-Prüfung erkennbar. code ist stabil und maschinenlesbar,detail sagt was zu tun ist, und type zeigt auf den Abschnitt hier, der ihn erklärt.

• invalid_json — der Body ist kein JSON-Objekt.
• incomplete_draft — der Entwurf ist unvollständig. problems nennt jedes fehlende Feld einzeln.
• method_not_allowed — falsche Methode. Allow nennt die richtige.
• not_acceptable — das angefragte Format gibt es hier nicht.
• not_found — den Endpunkt gibt es nicht.
• rate_limited — zu viele Anfragen. Retry-After sagt wie lange.
• internal_error — unerwartet, auf unserer Seite.

Grenzen

• Keine Preise, Termine, Reichweiten oder Ausrüstungsangaben — die sind nicht veröffentlicht.
• Kein Schreibzugriff. Der Kontakt-Endpunkt baut einen Link, er sendet keine Mail.
• Keine Speicherung. Was übergeben wird, steht danach nur im zurückgegebenen Link.

Katalog

Alle Dokumente dieser Seite stehen als Linkset nach RFC 9727 unter /.well-known/api-catalog — die OpenAPI-Datei als service-desc, diese Seite als service-doc, das MCP-Manifest als service-meta und die Abkündigungspolitik als sunset. Dieselben Verweise trägt jede Antwort der Schnittstelle im Link-Header, und jede Seite der Website nennt den Katalog.

Wie diese Seite maschinenlesbar aussieht: /llms.txt. Jede Seite gibt es außerdem als Markdown — Accept: text/markdown auf derselben URL.

Fragen dazu: thilo@thiloskye.de.