Speicher-API für die Wohnungssuche-Seite

Sicherheitsmodell

• Wer den Kurzlink hat, sieht die Seite. Die ID ist zufällig (12 Zeichen aus 31, kaum zu erraten) und die Seite steht nicht in Suchmaschinen (noindex). Was auf der Seite steht, ist aber für jeden lesbar, der den Link kennt, auch E-Mail und Telefonnummer, und auch über GET /sites/<id>. Schreibe nichts hinein, was nicht jeder Empfänger sehen soll.
• Bearbeiten nur mit dem Bearbeitungsschlüssel. Beim Anlegen erzeugt der Server einen Schlüssel (as_…, 40 zufällige Zeichen) und zeigt ihn genau einmal. Gespeichert wird nur sein SHA-256-Hash. Wer den Schlüssel verliert, kann die Seite nicht mehr ändern oder löschen; sie läuft dann nach der Frist ab. Der Schlüssel gehört weder in einen Link noch in die Daten der Seite.
• Kein Login nötig. Anlegen, Ändern, Fotos und Löschen funktionieren ohne Konto. Ein Konto (nur Google, keine Passwörter) ist nur nötig, wenn du mehrere Seiten verwalten oder Premium nutzen willst; siehe unten.
• Schlüssel erneuern: POST /sites/<id>/rotate-key erzeugt einen neuen; der alte gilt sofort nicht mehr.
• Absender-Limit ohne IP-Speicherung: Für die Tageslimits wird aus der IP-Adresse ein Pseudonym berechnet (SHA-256 mit geheimem Zusatz). Die Adresse selbst wird nicht gespeichert.
• Fotos: Typ wird an den ersten Bytes geprüft (JPEG, PNG, WebP, GIF, AVIF; kein SVG). Die Datei-ID ist zufällig.
• Browser und CSRF: CORS ist *, es gehen aber keine Anmeldedaten ursprungsübergreifend mit. Schreibzugriffe, die nur das Session-Cookie beglaubigt, zählen nur, wenn der Origin-Header in ALLOWED_ORIGINS steht (https://d-solve.de); sonst gilt die Anfrage als nicht angemeldet. Anfragen mit Bearbeitungsschlüssel (Authorization: Bearer as_…) brauchen keine Session und stehen KI-Agenten weiter offen.
• Datenschutz: Die Daten liegen auf einem Server von d-solve.de bei Cloudflare, werden nach Ablauf der Frist gelöscht, und wer den Link hat, sieht die Seite. Mehr in der Datenschutzerklärung.

Harte Grenzen

Die Grenzen sind Kostenbremsen. Die Werte stehen an genau einer Stelle, in workers/apartment-search-api/config.json, und der Dienst liefert sie live unter GET /api/limits (dort unter today auch der Verbrauch des Tages). Kein Aufrufer kann sie überschreiten. Ein Agent ruft sie vor dem Anlegen ab. Tageskontingente gelten je UTC-Tag.

Außerdem begrenzt der Betreiber optional die Anfragen je Absender und Minute. Auch das meldet sich mit 429 und "code":"rate". Ob Funktionen aktiv sind, steht in features (cloud, accounts, premium, bulk, urlImport).

Endpunkte

API-Basis: https://d-solve.de/apartment-search/api. Alle Antworten sind JSON mit content-type: application/json, Zeitangaben sind Unix-Sekunden. Fehler haben die Form {"error":"…","code":"…"}; code gibt es nur bei einigen. Anfragen mit Inhalt senden content-type: application/json. Auth heißt Authorization: Bearer <Schlüssel>; die Konto-Endpunkte nutzen stattdessen das Session-Cookie. OPTIONS (CORS-Vorabfrage) antwortet mit 204.

Die Seiten selbst

Eine abgelaufene oder gelöschte Seite zeigt eine kurze Hinweisseite (404). https://d-solve.de/apartment-search/ ohne ID führt zum Baukasten.

Ablauf mit curl

Der data-Teil besteht aus genau den Link-Parametern der Seite (alle Parameter): ein flaches JSON-Objekt Name → Text, unkodiert (kein %20). Mehrsprachige Texte haben das Suffix im Namen (headline.de). Leere Werte werden nicht gespeichert, data:-Adressen werden abgelehnt (Bilder hochladen). Für die Beispiele:

API=https://d-solve.de/apartment-search/api

1. Grenzen und Fristen abfragen (optional)

curl -sS "$API/limits"

2. Seite anlegen

curl -sS -X POST "$API/sites" \
  -H "content-type: application/json" \
  -d '{
    "data": {
      "langs": "de",
      "loc": "Mainz",
      "names": "Familie Beispiel",
      "headline": "Wir suchen ein Zuhause in Mainz",
      "subline": "Zwei Erwachsene und ein Kind suchen eine 3-Zimmer-Wohnung.",
      "email": "[email protected]",
      "phone": "-"
    },
    "retentionDays": 30
  }'

3. Antwort: Kurzlink und Schlüssel

{
  "id": "k7m2p9q4r6t8",
  "url": "https://d-solve.de/apartment-search/k7m2p9q4r6t8",
  "subpages": {
    "aushang": "https://d-solve.de/apartment-search/k7m2p9q4r6t8/aushang/",
    "mietunterlagen": "https://d-solve.de/apartment-search/k7m2p9q4r6t8/mietunterlagen/"
  },
  "data": { "langs": "de", "loc": "Mainz", … },
  "images": [], "imageCount": 0,
  "retentionDays": 30,
  "createdAt": 1790000000, "updatedAt": 1790000000, "expiresAt": 1792592000,
  "owned": false,
  "editKey": "as_…40 Zeichen…",
  "apiUrl": "https://d-solve.de/apartment-search/api/sites/k7m2p9q4r6t8",
  "note": "Der Bearbeitungsschlüssel wird nur dieses eine Mal angezeigt. …"
}

Den editKey jetzt sichern. Er kommt nie wieder. Für die nächsten Schritte:

ID=k7m2p9q4r6t8
KEY=as_…

4. Lesen

curl -sS "$API/sites/$ID"

Öffentlich, ohne Schlüssel. Liefert data, images, expiresAt. Der Schlüssel ist nie enthalten.

5. Ändern

curl -sS -X PUT "$API/sites/$ID" \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"data": { "langs": "de", "loc": "Mainz", "headline": "Neue Überschrift", "email": "[email protected]" }}'

data ersetzt den gesamten bisherigen Inhalt. Wer nur einen Wert ändern will, liest die Seite zuerst (Schritt 4), ändert das Objekt und schickt es vollständig zurück.

6. Foto hochladen

Drei Wege, alle mit dem Schlüssel; Anzahl und Größe begrenzt (limits.maxImagesPerSite, limits.maxImageBytes); erlaubt sind JPEG, PNG, WebP, GIF und AVIF.

# a) Rohbytes
curl -sS -X POST "$API/sites/$ID/images" \
  -H "authorization: Bearer $KEY" -H "content-type: image/jpeg" \
  --data-binary @wohnzimmer.jpg

# b) Formular mit Feld "file"
curl -sS -X POST "$API/sites/$ID/images" \
  -H "authorization: Bearer $KEY" -F "[email protected]"

# c) Der Server lädt ein öffentliches Bild selbst (für KI-Agenten)
curl -sS -X POST "$API/sites/$ID/images" \
  -H "authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"url":"https://upload.wikimedia.org/wikipedia/commons/…/bild.jpg"}'

{ "id": "…", "url": "https://d-solve.de/apartment-search/img/…jpg", "contentType": "image/jpeg", "size": 183422, "imageCount": 1, "maxImages": 20 }

7. Bild-URL in data verwenden

Die zurückgegebene url ist ein normaler Bild-Link und geht in jeden Foto-Parameter (photo, p1photo, p2photo, …; mehrere pro Kachel mit | getrennt). Die Seite ändert sich erst, wenn du die Daten schreibst:

curl -sS -X PUT "$API/sites/$ID" \
  -H "authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"data": { …alle bisherigen Werte…, "photo": "https://d-solve.de/apartment-search/img/….jpg" }}'

Fotos löschen: curl -sS -X DELETE "$API/sites/$ID/images/<imageId>" -H "authorization: Bearer $KEY". Die Bild-ID steht in der Upload-Antwort und in GET /sites/:id/images.

8. Frist abfragen und ändern

curl -sS "$API/sites/$ID" | grep -o '"expiresAt":[0-9]*'     # Unix-Sekunden, date -d @1792592000
curl -sS -X PUT "$API/sites/$ID" \
  -H "authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"retentionDays": 90}'

retentionDays muss eine der erlaubten Optionen sein (Schritt 1) und setzt die Frist neu ab jetzt. data und retentionDays lassen sich in einer Anfrage kombinieren.

9. Schlüssel prüfen und erneuern

curl -sS -X POST "$API/sites/$ID/verify"     -H "authorization: Bearer $KEY"
curl -sS -X POST "$API/sites/$ID/rotate-key" -H "authorization: Bearer $KEY"   # {"editKey":"as_…"}; der alte ist sofort ungültig

10. Löschen

curl -sS -X DELETE "$API/sites/$ID" -H "authorization: Bearer $KEY"

Löscht die Seite und alle ihre Fotos endgültig. Der Kurzlink zeigt danach eine Hinweisseite.

Fehlercodes

Für KI-Agenten

Wer Anfragen ausführen kann, kann die Seite selbst anlegen. Wer nicht, gibt dem Nutzer den fertigen curl-Befehl oder den langen Link. Alles zum Inhalt der Seite steht in der llms.txt; hier geht es nur um das Speichern. MCP-Clients nutzen statt roher HTTP-Aufrufe den MCP-Server.

Rezept

1. Fragen: Kurzlink mit Speicherung (Daten auf dem Server, Löschung nach der Frist) oder langer Link ohne Speicherung (privat, nichts gespeichert)? Nicht still für den Nutzer entscheiden.
2. Grenzen lesen: GET /api/limits. Ist features.cloud falsch oder die Anfrage scheitert, beim langen Link bleiben. Den Nutzer eine Frist aus retention.options wählen lassen (Standard retention.defaultDays).
3. Daten bauen: dieselben Parameter wie im Link als JSON, unkodiert. Fotos zunächst weglassen oder bei öffentlichen Bild-Links belassen.
4. Anlegen: POST /api/sites mit {data, retentionDays}. id, url, editKey aus der Antwort übernehmen.
5. Fotos: für jedes Foto POST /api/sites/<id>/images mit {"url":"https://…"} (Server-Import). Die zurückgegebene url als Wert für photo/p1photo … in data setzen. Dann PUT /api/sites/<id> mit den vollständigen Daten.
6. Prüfen: GET /api/sites/<id>, dann den Kurzlink öffnen oder dem Nutzer geben.
7. Dem Nutzer melden: Kurzlink, Aushang- und Mietunterlagen-Link, Bearbeitungsschlüssel und die Frist als Datum (aus expiresAt).

Regeln

• Den Bearbeitungsschlüssel dem Nutzer einmal deutlich zeigen und ihn auffordern, ihn zu speichern (Passwortmanager, Notiz). Nur damit lässt sich die Seite später ändern oder löschen. Er wird nie wieder angezeigt, und du kannst ihn nicht für den Nutzer aufbewahren.
• Den Schlüssel nie in einen Link schreiben, nicht in data, nicht in die Adresse eines Aufrufs, nicht an Dritte. Er gehört in den Authorization-Header.
• Die Frist nennen und sagen, dass die Seite danach gelöscht wird. Wer sie verlängern will, ruft PUT mit retentionDays auf.
• Bilder per {url}-Import laden, wenn du keine Dateien senden kannst. Nur Adressen verwenden, die du gefunden und geprüft hast.
• Immer vollständig schreiben: PUT mit data ersetzt alles. Erst GET, ändern, dann PUT.
• Bei 429 oder 503 auf den Link-Modus ausweichen und den langen Link liefern; dem Nutzer kurz sagen, warum.
• Bei 409 image-limit ein Foto weniger oder ein altes löschen, nicht neu versuchen.
• Der Nutzer kann später selbst weitermachen: im Baukasten unter „Vorhandene Seite laden“ mit Kurzlink und Schlüssel.

MCP-Server

Für Chat-Clients, die selbst keine HTTP-Aufrufe machen können (Claude, ChatGPT und andere MCP-Clients), gibt es dieselbe API als MCP-Server (Model Context Protocol): https://d-solve.de/apartment-search/mcp, Transport Streamable HTTP, JSON-RPC 2.0 per POST, ohne Anmeldung, ohne Sitzungen. Als Connector oder benutzerdefinierte Integration hinzufügen; die instructions des Servers verweisen auf die llms.txt.

Jedes Werkzeug ist genau einer der Endpunkte oben, durch denselben Handler, mit derselben Prüfung, denselben Grenzen und Fehlercodes. Der Bearbeitungsschlüssel ist ein Werkzeug-Argument (editKey) und wird intern zum Authorization-Header.

Ergebnisse sind JSON, als Text und als structuredContent. Ein API-Fehler wird zum Werkzeug-Ergebnis mit isError: true und den Feldern status, error und code. Ausprobieren mit curl:

curl -sS -X POST https://d-solve.de/apartment-search/mcp -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Konto, Premium und Sammel-Anlage sind keine Werkzeuge; Agenten arbeiten mit dem Bearbeitungsschlüssel. GET /apartment-search/mcp antwortet mit 405 und einer kurzen Beschreibung, die OpenAPI-Beschreibung nennt den Server unter x-mcp.

Konto, Premium und Stripe

Ein Konto ist optional und nur für Premium oder mehrere Seiten nötig. Es gibt keine Passwörter, nur die Anmeldung mit Google.

• Anmelden: GET /api/auth/providers nennt die verfügbaren Anbieter (derzeit nur Google, per accounts.providers). GET /api/auth/login?provider=google&return=<Adresse> leitet zu Google (OAuth 2.1, Authorization Code mit PKCE; der Worker ist der vertrauliche Client, kein Token erreicht den Browser). Die Rückkehr-Adresse muss auf einem erlaubten Ursprung liegen (https://d-solve.de). Nach dem Rücksprung setzt der Worker das HttpOnly-Cookie __Secure-as_session (Secure, SameSite=Lax, Path=/apartment-search; 30 Tage gleitend, höchstens 90) und leitet zu <return>#/auth/ok weiter. Die Sitzung liegt in D1 nur als SHA-256-Hash. Beenden: POST /api/auth/logout (diese) oder POST /api/auth/logout-all (alle).
• Konto und Limits: GET /api/auth/me zeigt Name, Premium-Status und die Grenzen dieses Kontos. GET /api/me/sites listet die eigenen Seiten.
• Seiten dem Konto zuordnen: Mit angemeldeter Session angelegte Seiten gehören dem Konto, der Besitzer darf dann ohne Schlüssel schreiben. Eine ohne Konto angelegte Seite wird mit POST /api/sites/<id>/claim und {"editKey":"…"} übernommen. Der Schlüssel bleibt zusätzlich gültig. Wie viele Seiten ein Konto haben darf und welche Fristen gelten, steht in /api/auth/me unter limits.
• Premium: POST /api/billing/checkout mit {"return":"…"} liefert eine Stripe-Checkout-Adresse für ein Abo (Preis aus premium.stripePriceId, monatlich oder jährlich). Danach geht es zu <return>#/konto/premium-ok, bei Abbruch zu <return>#/konto. Premium gilt bis zum Ende der bezahlten Periode plus 3 Tage Kulanz; nach Kündigung endet es. Kündigen und Zahlungsdaten ändern: POST /api/billing/portal mit {"return":"…"} liefert die Adresse des Stripe-Kundenportals. Die Freischaltung kommt per Stripe-Webhook, nicht über die Rückkehr-Adresse. Nur sichtbar, wenn premium.available in /api/limits wahr ist.
• Sammel-Anlage: POST /api/sites/bulk legt für Premium-Konten mehrere Seiten auf einmal an, sofern features.bulk aktiv ist.

Weiterführend

• OpenAPI-Beschreibung (JSON): für Werkzeuge, die Schnittstellen automatisch einlesen.
• Baukasten: online speichern per Klick, Fotos hochladen, Seiten laden.
• Dokumentation: wie die Seite funktioniert, alle Parameter, selbst hosten.
• llms.txt: die vollständige Anleitung für KI-Agenten (Parameter, Fotos, API, MCP) in einer Datei.
• MCP-Server: dieselbe API für Chat-Clients, siehe oben.
• Selbst betreiben: Der Dienst ist ein Cloudflare Worker, siehe workers/apartment-search-api/README.md im Repository.