Versionen und API-Änderungen

Zuletzt aktualisiert: 2026-10-0311 Min. Lesezeit

Version

Die Hauptversion steht im Pfad: /api/v1. Innerhalb von v1 brechen wir bestehende Integrationen nicht. Die aktuelle Vertragsversion ist info.version in /openapi.json; sie steigt mit jeder Änderung.

Was sich ohne Ankündigung ändern darf

Diese Änderungen sind kompatibel, und Ihr Client sollte mit ihnen umgehen können:

neue Operationen und Werkzeuge;
neue optionale Anfragefelder;
neue Antwortfelder;
neue Werte in Aufzählungen der Antworten (Status, Codes), neue Fehlercodes in title, neue Webhook-Ereignistypen;
Änderungen am Text von detail;
höhere Limits.

Einen Client schreiben

Ignorieren Sie unbekannte Antwortfelder.
Behandeln Sie einen unbekannten Aufzählungswert, Fehlercode oder Ereignistyp als «sonstiges», nicht als Fehler.
Verzweigen Sie nach status, title und code, nicht nach dem Text von detail.
Verlassen Sie sich nicht auf die Reihenfolge der Felder oder die Länge von IDs.
Verlassen Sie sich auf den Auftragszustand state, nicht auf den rohen status des Werkzeugs.

Was als brechend gilt

Entfernen oder Umbenennen einer Operation, eines Felds, eines Bereichs oder eines Ereignisses; ein neues Pflichtfeld in der Anfrage; eine Änderung von Typ oder Bedeutung eines Felds; ein anderer Statuscode für denselben Fall; eine Einschränkung der erlaubten Werte. Solche Änderungen nehmen wir in v1 nicht ohne Ankündigung vor: Die Operation wird zuerst in /openapi.json und in diesem Protokoll als deprecated markiert und funktioniert mindestens 6 Monate weiter. Ausnahme ist das Schließen einer Sicherheitslücke.

Eine Korrektur, die eine Antwort mit dieser Dokumentation in Einklang bringt, ist keine brechende Änderung.

Änderungsprotokoll

2026-10-03 - Version 1.16

Geändert:

429 enthält code: minute_limit oder daily_limit (das Tageslimit des Schlüssels, zurückgesetzt um 00:00 UTC).
Ein mit einem Agenturschlüssel geschriebenes Objekt gehört der Agentur; object.*- und lead.*-Webhooks von Agenturobjekten und -Leads erreichen auch die Adressen der Agentur.
Objektfotos: bis zu 50 für jede Art, wie im Kabinett.
SDK 1.7.2: ein leerer Stream-Teil teilt kein Chat-Ereignis mehr.

Behoben:

PUT /objects/{kind}/{id} behält Moderationsstatus, isSold und Veröffentlichung des Objekts; früher setzte es sie zurück (eine einfache Bearbeitung nahm ein live geschaltetes Objekt offline).
GET /objects listet keine Objekte gesperrter Eigentümer mehr; eine vor Gästen verborgene Karte wird auch per ID nicht geliefert.
PATCH /leads/{id}: der Absender eines Leads ohne Vertrag darf dessen Status ändern, wie im Kabinett; Änderung und Archivierung werden in der Historie des Leads vermerkt.

2026-10-03 - Version 1.15

Geändert:

PATCH /leads/{id} (Status) und DELETE /leads/{id} folgen den Regeln des Kabinetts: Finalisierung, Provisionseinzug, aktiver Vertrag oder Vereinbarung - 422 mit dem Grund in code. ?expand=history enthält keine Dienstmetadaten mehr (Tokens, IDs anderer Nutzer).
Das Tageslimit des kostenlosen Chats antwortet code: free_daily_limit mit Retry-After bis 00:00 UTC.
GET /works: previewUrl, link und object.photoUrl sind /files/...-Pfade für GET /artifacts/{path}; auf der letzten Seite ist nextCursor null.
Lead anlegen: unbekannte Felder werden verworfen (nicht abgelehnt); die vom Dienst geprüften Längen stehen in der Spezifikation; pool: true übergibt den Lead an den Plattform-Pool.
SDK 1.7.1: jobs.wait wartet ein 429 ab; chat.stream verarbeitet ein zwischen Teilen getrenntes CRLF; artifact() nimmt signal an.

Behoben:

Musikvorschau: ein Range hinter dem Dateiende ist 416 (es kam 404); ein ausgefallener Dateidienst ist 502, nicht 404.
Eine Datei über 15 MB in POST /uploads ist 413. Eine abgelehnte strictPhotos-Anzeige nennt die nicht geladenen Fotos (code: photo_fetch_failed).
Die Ablehnung eines Content-Pakets nennt form.media.photos. Sandbox: die Gutachtenprüfung nimmt die erste Datei mit beliebigem Namen; Mietwerte als Zeichenketten und Foto-Dienstschlüssel werden nicht abgelehnt.

2026-10-03 - Version 1.14

Geändert:

Eine Wiederholung der Express-Bewertung mit demselben Idempotency-Key ist jetzt ganz kostenlos: auch der API-Aufruf wird nicht berechnet.
GET /works: ein cursor, der kein nextCursor ist, ist 400 (die Liste begann stillschweigend von vorn).
POST /webhooks/{id}/test: ein eventType, der nicht in der Liste steht, ist 400 (es wurde ein allgemeiner Test gesendet).
Swipe Match: reasonCode nimmt nur die aufgeführten Gründe an, wie der Dienst es immer verlangte; kind eines Leads kann pool sein.
SDK 1.7.0: jobs.wait übersteht eine fehlgeschlagene Abfrage; artifact() nimmt range; chat.stream liest CRLF-Streams und ruft einmal pro Ereignis auf.

Behoben:

Musikvorschau: bytes=-N liefert die letzten N Bytes, ein Range hinter dem Dateiende ist 416.
Ein Verbindungs-Timeout vor dem Senden der Anfrage gibt den Idempotency-Key frei.
Sandbox: Videofotos unter jedem Feldnamen, den der Dienst liest, Mietzahlen als Zeichenketten, Flyer-PNGs in der angegebenen Größe.

2026-10-03 - Version 1.13

Hinzugefügt:

GET /works liefert, was das Kabinett zu jedem Ergebnis zeigt: street, streetNumber, previewUrl, link, repeatIndex, error und das Objekt (object).
GET /chat/sessions beschreibt seine Parameter: limit, cursor, q, projectId, archivedOnly, sort.
Problem.title in der Spezifikation enthält range_not_satisfiable; die Webhook-Liste trägt requestId.
SDK 1.6.1: chat.listSessions nimmt die Listenparameter an.

Geändert:

Die Spezifikation nennt Grenzen, die der Betrieb schon anwandte: Avatar-scriptText bis 1200 Zeichen, Flyer-formats bis 3 und layouts bis 5, Feldlängen von Flyer-contacts, Foto-seed bis 2147483647 und keine unbekannten Schlüssel in Foto-data.
Express-Bewertung: Das Gateway lehnt nur eine Anfrage ganz ohne Fläche und ohne Objekttyp ab; ob landPlotArea zählt, entscheidet der Dienst (auch ein in propertyType oder apartmentType genanntes Grundstück zählt).

Behoben:

Die Sandbox lehnt Fotos wie der Betrieb ab (JPEG, PNG oder WebP bis 25 MB - JOB_CREATE_FAILED; eine Maske außerhalb von cleanup - MASK_NOT_SUPPORTED) und nimmt an, was der Betrieb kürzt oder ersetzt (Videotitel, Lautstärke, Abspann und Optionen der Schlussphrase, Sprache der Landingpage, mehr als 20 Content-Fotos, Miete furnished als Wort). Ein Gutachten-Auftrag zeigt nach running nicht mehr pending.
Eine abgelehnte Download-Weiterleitung wird als solche gemeldet statt als Zeitüberschreitung; ein Range-Suffix länger als die Datei liefert die ganze Datei.
SDK 1.6.1: verifyWebhookSignature funktioniert unter Node 18.

2026-10-03 - Version 1.12

Hinzugefügt:

416 range_not_satisfiable als RFC-9457-Problem (kam mit leerem Body).
priceMinor beim Start der Fotoverbesserung: was der Aufruf kostet, wie im Kabinett.
SDK 1.6.0: works nimmt from/to, chat.history nimmt limit/cursor, chat.sendMessage nimmt style.

Geändert:

GET /match/leads: limit über 50 oder page über 1000 antworten 400 (sie wurden nie gekürzt). POST /match/leads/{id}/events: ein Idempotency-Key in anderem Format ist 400, statt still verworfen zu werden.
Ein vom Flyer abgelehntes Feld ist 400 validation mit dem Feldnamen (war 422).
Ein Aufruf, dessen Zahlung unter demselben Idempotency-Key noch reserviert wird, ist 409 idempotency_conflict (war 422).
Express-Bewertung: landPlotArea zählt wie im Dienst nur bei land als Fläche.
Eine Zeitüberschreitung, eine zurückgesetzte Verbindung oder ein mitten in der Antwort geschlossener Socket lassen den Idempotency-Key belegt; frei wird er nur bei einer Anfrage, die den Dienst nie erreicht hat.
SDK 1.6.0: ein Upload wird nach 503 nie wiederholt; der Abbruch-Listener wird nach jeder Pause entfernt.

Behoben:

Ablehnungen von PDF und Landingpage nennen ihren Grund: 402 mit INSUFFICIENT_FUNDS oder QUOTA_EXCEEDED (war 422 ohne code).
Die Sandbox lehnt genau das ab, was der Betrieb ablehnt: Typ und Größe hochgeladener Dateien; Texte werden gekürzt statt abgelehnt; unbekannte Video-Werte length, aspect und language fallen auf den Standard zurück; Flyer-Codes ohne Beachtung der Groß-/Kleinschreibung; ein Entwurf ohne type. Die Simulation fehlenden Guthabens antwortet mit INSUFFICIENT_FUNDS, dem Code des Betriebs.
limit und page kürzt das Gateway selbst (GET /chat/history?limit=500 antwortete 400; limit=0 ergab 20 statt 1).

2026-10-03 - Version 1.11

Hinzugefügt:

Auftragsergebnisse enthalten die Felder, die das Kabinett zeigt: Content-Paket, Texte und Video - progress, masterProfile (der Handlungsrahmen, auf dem Texte und Sprecherstimme aufbauen) und error bei einem fehlgeschlagenen Auftrag; Foto - metadata.error; Grundriss - rooms[].stable, rooms[].placement, sourceFileId.
Browser (CORS) können die Header RateLimit-*, Retry-After, Grem-Sandbox, X-Request-Id und Content-Range lesen.

Geändert:

Webhooks: Ein Testschlüssel legt nur Sandbox-Adressen an und verwaltet nur diese; sie erhalten nur Ereignisse von Sandbox-Aufträgen, Live-Adressen erhalten sie nie.
limit und page außerhalb des Bereichs werden in ihn gesetzt statt 400; kind in GET /objects ist unabhängig von Groß-/Kleinschreibung; rooms darf eine Bruchzahl sein.
Idempotency-Key gehört zum API-Schlüssel, zur Methode und zum tatsächlichen Pfad (POST /objects/property und POST /objects/rental sind verschiedene Operationen). Nach einer Zeitüberschreitung halten Objekt- und Lead-Erstellung den Schlüssel 15 Minuten, wie Werkzeuge; eine Anfrage, die den Dienst nie erreicht hat, gibt ihn frei.
text/generate: customDirection wird auf 500 Zeichen gekürzt.
SDK 1.5.1: 503 bei Schreibzugriffen wird nur mit Idempotency-Key wiederholt; ein Retry-After über 30 Sekunden wird nicht abgewartet; maxRetries höchstens 10; Ihr AbortSignal bricht die Pause ab; Nachrichten-IDs funktionieren in Node 18.

Behoben:

Die Sandbox arbeitet wie der Betrieb: Prüfung von multipart-Feldern, Berichtsfeldern je Kategorie, Heizungswerten eines Hauses, gewerblichen apartmentType und Wohnkomplexen; Dateien nur für abgeschlossene Aufträge, unter dem Pfad des eigenen Werkzeugs und mit bekannten Artefakt-IDs; Grem-Sandbox auch bei Antworten vor der Schlüsselprüfung; Grem-Simulate unabhängig von Groß-/Kleinschreibung.
Ohne Schlüssel ergeben ungültige Query-Parameter zuerst 401.
Ein einem Agenten zugeordneter Agenturschlüssel liest keine Aufträge mehr, die mit dem agenturweiten Schlüssel gestartet wurden.
Früher mit einem anderen Port gespeicherte Webhook-Adressen erhalten weiterhin Zustellungen.
Ein nicht erfüllbarer Range ergibt 416 statt 404; ein Dokument für die Berichtsprüfung wird bis 40 MB angenommen.

2026-10-03 - Version 1.10

Hinzugefügt:

Der Fehlercode conflict (409): Die Ressource ist in einem Zustand, der die Aktion nicht erlaubt (Fehler).
Felder für den Schlusssatz des Videos in POST /video/create: ctaMode, ctaIntent, ctaText, ctaMarket; die Optionen von GET /video/endings enthalten intent und text.
GET /works: die Filter from und to.
SDK 1.5.0: die Option maxRetries - 429 und 503 werden nach Retry-After wiederholt.

Geändert:

Abfrageparameter werden geprüft: Ein bekannter Parameter mit ungültigem Wert ergibt 400 validation mit dem Feldnamen.
Webhooks: nur https auf Port 443, keine Zugangsdaten in der URL; die 11. Adresse ergibt 422; Agentur-Webhooks verwaltet nur der agenturweite Schlüssel.
Idempotency-Key gehört zum API-Schlüssel und zur Operation; nach einer Zeitüberschreitung eines Werkzeugs bleibt der Schlüssel 15 Minuten reserviert.
Geldbezogene Ablehnungen (Kontingent, Schuld, Fair Use, Guthaben) sind 402 insufficient_funds mit code.
Ein Agentenschlüssel einer Agentur sieht nur seine eigenen Aufträge und Dateien.
Datei-Downloads zählen zum Rate-Limit.

Behoben:

Jeder Fehler, auch ein zu großer oder fehlerhafter Body, kommt als RFC 9457 application/problem+json; ein Body über dem Limit ergibt 413 payload_too_large.
Das Video-Feld ending wurde nie gelesen; verwenden Sie ctaIntent oder ctaText.
SDK: simulate mit einem Live-Schlüssel wirft einen Fehler, statt den Aufruf auszuführen.

2026-10-03 - Versionen 1.8-1.9

Hinzugefügt:

Vergleichsobjekte: estimate.analogs in der Expressbewertung, analogs im vollständigen Bericht, comps in der Mietschätzung - dasselbe wie im Kabinett und im PDF.
Felder fertiger Jobs sind vollständig beschrieben: Berichtszahlen unter ihren echten Namen (potPrice, priceRangeLow, priceRangeHigh, …), Gutachtenprüfung, Grundriss, Foto, Flyer, Entwurf.
SDK 1.4.0: der Typ Analog.

Geändert:

Werkzeugantworten enthalten nur beschriebene Felder; interne Felder, die früher durchrutschten, werden nicht mehr zurückgegeben.
Ein Werkzeug, das GET /tools/status als nicht verfügbar meldet, antwortet 503 service_unavailable, bevor etwas berechnet wird (bisher nur Content-Paket, Texte und Video).
Die Bestätigung der Gutachtenprüfung enthält nur Job-Felder (jobId, state, status); das veraltete _id entfällt dort.

Behoben:

Avatar-Video: artifacts enthält die IDs für die Download-URL.
checkIn/checkOut bei Mietobjekten sind als Tagesstunde beschrieben.

2026-10-02 - Version 1.7

Hinzugefügt:

Sandbox: Testschlüssel (gsk_test) simulieren Werkzeuge ohne Berechnung; der Header Grem-Simulate wählt das Ergebnis.
estimate.confidenceScore in der Express-Bewertung.

Geändert:

Aufrufe, die ein Werkzeug starten, warten bis zu 5 Minuten statt 60 Sekunden.
Die mit demselben Idempotency-Key wiederholte Express-Bewertung liefert das fertige Ergebnis ohne zweite Berechnung, auch nach einer Zeitüberschreitung.

Behoben:

estimate.confidence der Express-Bewertung war immer null.
Grundriss-Antworten enthalten keine internen Felder mehr.
GET /objects ohne kind sowie Ablehnungen bei Objekten und Leads nennen jetzt den Grund in detail.

2026-10-02 - Version 1.6

Geändert:

Jede Auftragsantwort enthält dasselbe Feld jobId. Die bisherigen Namen id, _id, contentGenJobId werden weiter geliefert und sind veraltet.
SDK 1.2.0: Job.jobId ist immer vorhanden.

2026-10-02 - Versionen 1.2 bis 1.5

Hinzugefügt:

GET /voices, GET /avatar/avatars, GET /video/music, GET /video/endings - IDs für die Werkzeuge (Referenzdaten).
GET /tools/status - Verfügbarkeit der Werkzeuge; GET /works - Arbeitsverlauf.
POST /flyer/create - persönlicher Flyer, Bereich tools:flyer.
POST /valuation/review/jobs/{id}/confirm - Bestätigung der Daten einer Berichtsprüfung.
Das Feld state in jeder Auftragsantwort.
In Fehlern - die Felder code und errors, die Codes forbidden, payload_too_large, service_unavailable.
In der API-Beschreibung - vollständige Anfrage- und Antwortschemata für jedes Werkzeug, der vollständige Schreibvertrag für Objekte je Typ, die Abrechnungsklasse jeder Operation (x-grem-billing), die Liste der Bereiche und Ereignisse.
Die Parameter scope (Objekte) und pool (Leads) sind dokumentiert.

Geändert:

Eine Ablehnung wegen fehlender Daten (zum Beispiel Texte ohne Beschreibung oder Stadt) ist jetzt 422 business_rule mit Grund und Code. Früher war es 502 provider_error.
Eine Ablehnung wegen fehlender Rechte an einer Ressource ist jetzt 403 forbidden mit Grund. Früher war es 500.
Die Test-Zustellung eines Webhooks für Werkzeuge hat dieselbe Form wie eine echte: { jobId, status, state }.

Behoben:

Agenturschlüssel funktionieren mit allen Werkzeugen, dem Chat und Datei-Downloads.
Berichtsprüfung und Grundriss: Der Auftragsstatus ist über die ID aus der Antwort abrufbar, Webhooks kommen an.
Download von Dateien aus Content-Paket, Texten und Video - nur für den Eigentümer des Auftrags.