Versions et évolutions de l'API

Version

La version majeure figure dans le chemin : /api/v1. Au sein de v1, nous ne cassons pas les intégrations existantes. La version actuelle du contrat est info.version dans /openapi.json ; elle augmente à chaque modification.

Ce qui peut changer sans préavis

Ces changements sont compatibles, et votre client doit savoir les gérer :

• nouvelles opérations et nouveaux outils ;
• nouveaux champs de requête facultatifs ;
• nouveaux champs de réponse ;
• nouvelles valeurs dans les énumérations de réponse (statuts, codes), nouveaux codes d'erreur dans title, nouveaux types d'événements webhook ;
• modifications du texte de detail ;
• relèvement des limites.

Écrire un client

• Ignorez les champs de réponse inconnus.
• Traitez une valeur d'énumération, un code d'erreur ou un type d'événement inconnu comme « autre », et non comme un échec.
• Basez vos branchements sur status, title et code, pas sur le texte de detail.
• Ne comptez ni sur l'ordre des champs ni sur la longueur des identifiants.
• Fiez-vous au state de la tâche, pas au status brut de l'outil.

Ce qui compte comme rupture

Supprimer ou renommer une opération, un champ, un scope ou un événement ; un nouveau champ de requête obligatoire ; changer le type ou le sens d'un champ ; changer le code de statut pour un même cas ; restreindre les valeurs autorisées. Nous ne faisons pas de tels changements dans v1 sans préavis : l'opération est d'abord marquée deprecated dans /openapi.json et dans ce journal des modifications, et continue de fonctionner pendant au moins 6 mois. La correction d'une vulnérabilité fait exception.

Une correction qui rend une réponse conforme à cette documentation n'est pas un changement cassant.

Journal des modifications

2026-11-09 - version 1.21

Ajouté :

• Mode Prefer: respond-async pour POST /site/create : un 202 avec une tâche de requête aussitôt ; GET /site/create/jobs/{id} (gratuit) contient dans result l’ancienne réponse 200. Événements site.completed / site.failed. Sans l’en-tête, rien ne change.
• SDK 1.11.0 : site.create accepte l’option respondAsync.

2026-11-08 - version 1.20

Ajouté :

• Mode Prefer: respond-async pour POST /draft/extract : les fichiers sont envoyés et un 202 avec une tâche de requête arrive aussitôt ; GET /draft/extract/jobs/{id} (gratuit) contient dans result l’ancienne réponse 200. Événements draft.completed / draft.failed. Sans l’en-tête, rien ne change.
• SDK 1.10.0 : draft.extract accepte l’option respondAsync.

2026-11-08 - version 1.19

Ajouté :

• L’événement review.action_required : la vérification de rapport a lu le document et attend POST /valuation/review/jobs/{id}/confirm. Il arrive une fois par vérification, avec son id, y compris lancée avec Prefer: respond-async. Auparavant, seul le sondage l’indiquait.

2026-11-06 - version 1.18

Ajouté :

• Prefer: respond-async pour POST /floorplan/create et POST /valuation/review : les fichiers sont acceptés, puis un 202 immédiat avec une tâche de requête (jobId du type areq_…) et les en-têtes Location, Retry-After et Preference-Applied. Statut : sur le même chemin, GET /floorplan/create/jobs/{id} et GET /valuation/review/jobs/{id} (gratuit) ; result contient le même corps 202 que sans l'en-tête (une vérification de rapport nécessite toujours confirm). Sans l'en-tête, rien ne change.
• Une tâche de requête interrompue par un redémarrage du service se termine en failed avec code: interrupted : rien n'est facturé et l'Idempotency-Key est libérée - renvoyez la même requête avec la même clé.
• SDK 1.9.0 : floorplan.create et valuation.review acceptent l'option respondAsync ; après interrupted, le client renvoie de lui-même le même formulaire avec la même clé, deux fois au maximum.

2026-11-05 - version 1.17

Ajouté :

• Prefer: respond-async pour POST /valuation/express et POST /valuation/rent : un 202 immédiat avec une tâche et les en-têtes Location, Retry-After et Preference-Applied. Statut : GET /valuation/express/jobs/{id} et GET /valuation/rent/jobs/{id} (gratuit) ; result contient le même corps que le 200 synchrone, error le même problème. Sans l'en-tête, les appels restent synchrones.
• Événements webhook express.completed, express.failed, rent.completed, rent.failed.
• SDK 1.8.0 : l'Idempotency-Key est créée automatiquement ; après une coupure, un délai dépassé, 502, 504, 524 et 409 idempotency_conflict, l'appel est répété avec la même clé, pendant au plus retryWindowMs (10 minutes) ; l'option respondAsync et la méthode jobs.result.

Modifié :

• Après 524 ou 504, l'Idempotency-Key n'est plus libérée : le travail a pu se terminer et être facturé. Une répétition avec la même clé renvoie le résultat final sans seconde facturation, et reçoit 409 tant que le premier appel est encore en cours.

2026-10-03 - version 1.16

Modifié :

• 429 porte un code : minute_limit ou daily_limit (la limite journalière de la clé, réinitialisée à 00:00 UTC).
• Un objet écrit avec une clé d'agence appartient à l'agence ; les webhooks object.* et lead.* des objets et leads de l'agence parviennent aussi aux endpoints de l'agence.
• Photos des objets : jusqu'à 50 pour chaque type, comme dans l'espace personnel.
• SDK 1.7.2 : un fragment de flux vide ne coupe plus un événement de chat en deux.

Corrigé :

• PUT /objects/{kind}/{id} conserve l'état de modération, isSold et la publication de l'annonce ; auparavant il les réinitialisait (une simple modification dépubliait une annonce en ligne).
• GET /objects ne liste plus les objets des propriétaires suspendus ; une fiche masquée aux visiteurs n'est pas non plus affichée par identifiant.
• PATCH /leads/{id} : l'expéditeur d'un lead sans contrat peut en changer le statut, comme dans l'espace personnel ; la modification et l'archivage sont inscrits dans l'historique du lead.

2026-10-03 - version 1.15

Modifié :

• PATCH /leads/{id} (statut) et DELETE /leads/{id} suivent les règles de l'espace personnel : finalisation, encaissement de la commission, contrat ou accord actif - 422 avec le motif dans code. ?expand=history ne contient plus de métadonnées techniques (jetons, identifiants d'autres utilisateurs).
• La limite journalière gratuite du chat répond code: free_daily_limit avec Retry-After jusqu'à 00:00 UTC.
• GET /works : previewUrl, link et object.photoUrl sont des chemins /files/... pour GET /artifacts/{path} ; nextCursor vaut null sur la dernière page.
• Écriture de leads : les champs inconnus sont ignorés (et non refusés) ; les longueurs imposées par le service figurent dans la spécification ; pool: true remet le lead au pool de la plateforme.
• SDK 1.7.1 : jobs.wait attend la fin d'un 429 ; chat.stream gère un CRLF coupé entre deux fragments ; artifact() accepte signal.

Corrigé :

• Aperçu musical : un Range au-delà de la fin donne 416 (il était répondu en 404) ; une défaillance du service de fichiers donne 502, et non 404.
• Un fichier de plus de 15 MB dans POST /uploads donne 413. Une annonce strictPhotos refusée indique les photos en échec (code: photo_fetch_failed).
• Un refus du pack de contenu indique form.media.photos. Bac à sable : la vérification prend le premier fichier quel que soit son nom ; les chaînes de loyer et les clés du service photo ne sont pas refusées.

2026-10-03 - version 1.14

Modifié :

• Une répétition de l'estimation express avec la même Idempotency-Key est désormais entièrement gratuite : l'appel API n'est pas non plus facturé.
• GET /works : un cursor qui n'est pas nextCursor donne 400 (auparavant la liste recommençait silencieusement).
• POST /webhooks/{id}/test : un eventType absent de la liste donne 400 (auparavant un test générique était envoyé).
• Swipe Match : reasonCode n'accepte que les motifs listés, comme le service l'a toujours exigé ; le kind d'un lead peut valoir pool.
• SDK 1.7.0 : jobs.wait résiste à une interrogation perdue ; artifact() accepte range ; chat.stream lit les flux CRLF et produit un appel par événement.

Corrigé :

• Aperçu musical : bytes=-N renvoie les N derniers octets, un Range au-delà de la fin donne 416.
• Un délai de connexion dépassé avant l'envoi de la requête libère l'Idempotency-Key.
• Bac à sable : photos vidéo sous n'importe quel nom de champ lu par le service, nombres de loyer envoyés sous forme de chaînes, PNG de flyer à la taille indiquée.

2026-10-03 - version 1.13

Ajouté :

• GET /works renvoie ce que l'espace personnel affiche pour chaque résultat : street, streetNumber, previewUrl, link, repeatIndex, error et l'annonce (object).
• GET /chat/sessions documente ses paramètres : limit, cursor, q, projectId, archivedOnly, sort.
• Problem.title dans la spécification liste range_not_satisfiable ; la liste des webhooks porte requestId.
• SDK 1.6.1 : chat.listSessions accepte les paramètres de liste.

Modifié :

• La spécification indique les limites déjà appliquées en production : scriptText de l'avatar jusqu'à 1200 caractères, formats du flyer jusqu'à 3 et layouts jusqu'à 5, longueurs des champs contacts du flyer, seed photo jusqu'à 2147483647, et aucune clé inconnue dans data photo.
• Estimation express : la passerelle ne refuse qu'une requête sans aucune surface et sans type de bien ; c'est le service qui décide si landPlotArea compte (un terrain indiqué dans propertyType ou apartmentType compte aussi).

Corrigé :

• Le bac à sable refuse les photos comme la production (JPEG, PNG ou WebP jusqu'à 25 MB - JOB_CREATE_FAILED ; un masque hors nettoyage - MASK_NOT_SUPPORTED) et accepte ce que la production tronque ou remplace (titre de la vidéo, volume, carte de fin et options de phrase de clôture, langue de la page d'atterrissage, plus de 20 photos de contenu, furnished du loyer sous forme de mot). Une tâche de rapport n'affiche plus pending après running.
• Une redirection de téléchargement refusée l'indique au lieu d'un délai dépassé ; un suffixe Range plus long que le fichier renvoie le fichier entier.
• SDK 1.6.1 : verifyWebhookSignature fonctionne sous Node 18.

2026-10-03 - version 1.12

Ajouté :

• 416 range_not_satisfiable sous forme de problème RFC 9457 (il arrivait avec un corps vide).
• priceMinor au lancement de l'amélioration de photos : ce que l'appel coûte, tel que l'affiche l'espace personnel.
• SDK 1.6.0 : works accepte from/to, chat.history accepte limit/cursor, chat.sendMessage accepte style.

Modifié :

• GET /match/leads : limit supérieur à 50 ou page supérieur à 1000 répondent 400 (ils n'ont jamais été tronqués). POST /match/leads/{id}/events : une Idempotency-Key d'un autre format donne 400 au lieu d'être ignorée silencieusement.
• Un champ refusé par le flyer donne 400 validation en nommant le champ (auparavant 422).
• Un appel dont le paiement est encore en cours de réservation sous la même Idempotency-Key donne 409 idempotency_conflict (auparavant 422).
• Estimation express : landPlotArea compte comme surface uniquement pour land, comme dans le service.
• Un délai dépassé, une connexion réinitialisée ou un socket fermé en cours de réponse laissent l'Idempotency-Key occupée ; seule une requête qui n'a jamais atteint le service la libère.
• SDK 1.6.0 : un téléversement n'est jamais répété après 503 ; l'écouteur d'abandon est retiré après chaque pause.

Corrigé :

• Les refus du PDF et de la page d'atterrissage indiquent leur motif : 402 avec INSUFFICIENT_FUNDS ou QUOTA_EXCEEDED (auparavant 422 sans code).
• Le bac à sable refuse exactement ce que refuse la production : type et taille des fichiers téléversés ; textes tronqués au lieu d'être refusés ; length, aspect et language vidéo inconnus reviennent à la valeur par défaut ; les codes du flyer sont insensibles à la casse ; un brouillon sans type. La simulation de fonds insuffisants répond INSUFFICIENT_FUNDS, le code envoyé par la production.
• limit et page sont ramenés dans la plage par la passerelle elle-même (GET /chat/history?limit=500 répondait 400 ; limit=0 donnait 20 au lieu de 1).

2026-10-03 - version 1.11

Ajouté :

• Les résultats des tâches portent les champs affichés par l'espace personnel : pack de contenu, texte et vidéo - progress, masterProfile (le canevas de récit sur lequel les textes et la narration ont été construits) et error pour une tâche échouée ; photo - metadata.error ; plan - rooms[].stable, rooms[].placement, sourceFileId.
• Les navigateurs (CORS) peuvent lire les en-têtes RateLimit-*, Retry-After, Grem-Sandbox, X-Request-Id et Content-Range.

Modifié :

• Webhooks : une clé de test crée et gère uniquement des endpoints de bac à sable ; ils ne reçoivent que les événements des tâches du bac à sable, et les endpoints de production ne les reçoivent jamais.
• limit et page hors plage y sont ramenés au lieu de 400 ; kind dans GET /objects est insensible à la casse ; rooms peut être fractionnaire.
• L'Idempotency-Key est liée à la clé API, à la méthode et au chemin réel (POST /objects/property et POST /objects/rental sont des opérations différentes). Après un délai dépassé, les créations d'annonces et de leads retiennent la clé pendant 15 minutes, comme les outils ; une requête qui n'a jamais atteint le service la libère.
• text/generate : customDirection est tronqué à 500 caractères.
• SDK 1.5.1 : un 503 sur une écriture n'est retenté qu'avec une Idempotency-Key ; un Retry-After supérieur à 30 secondes n'est pas attendu ; maxRetries vaut au plus 10 ; votre AbortSignal annule la pause ; les identifiants de message fonctionnent sous Node 18.

Corrigé :

• Le bac à sable fonctionne comme la production : vérification des champs multipart, champs du rapport par catégorie, valeurs de chauffage des maisons, apartmentType commercial et ensembles résidentiels ; fichiers uniquement pour les tâches terminées, au chemin propre à l'outil et avec des identifiants d'artefact connus ; Grem-Sandbox aussi sur les réponses faites avant la vérification de la clé ; Grem-Simulate est insensible à la casse.
• Sans clé, des paramètres de requête invalides répondent d'abord 401.
• Une clé d'agence limitée à un agent ne lit plus les tâches lancées avec la clé de l'agence entière.
• Les endpoints de webhook enregistrés auparavant sur un autre port continuent de recevoir les livraisons.
• Un Range impossible à satisfaire répond 416 au lieu de 404 ; un document de vérification de rapport jusqu'à 40 MB est accepté.

2026-10-03 - version 1.10

Ajouté :

• Le code d'erreur conflict (409) : la ressource est dans un état qui ne permet pas l'action (Erreurs).
• Champs de phrase de clôture vidéo dans POST /video/create : ctaMode, ctaIntent, ctaText, ctaMarket ; les options de GET /video/endings portent intent et text.
• GET /works : les filtres from et to.
• SDK 1.5.0 : l'option maxRetries - 429 et 503 sont retentés après Retry-After.

Modifié :

• Les paramètres de requête sont vérifiés : un paramètre connu avec une valeur invalide donne 400 validation en nommant le champ.
• Webhooks : https sur le port 443 uniquement, pas d'identifiants dans l'URL ; la 11e adresse donne 422 ; les webhooks d'agence se gèrent uniquement avec la clé de l'agence entière.
• L'Idempotency-Key est liée à la clé API et à l'opération ; après un délai dépassé d'un outil, la clé reste réservée pendant 15 minutes.
• Les refus financiers (quota, dette, usage équitable, solde) donnent 402 insufficient_funds avec code.
• Une clé d'agence limitée à un agent ne voit que ses propres tâches et fichiers.
• Les téléchargements de fichiers comptent dans la limite de débit.

Corrigé :

• Chaque erreur, y compris un corps trop volumineux ou mal formé, arrive en RFC 9457 application/problem+json ; un corps au-delà de la limite donne 413 payload_too_large.
• Le champ vidéo ending n'était jamais lu ; utilisez ctaIntent ou ctaText.
• SDK : simulate avec une clé de production lève une exception au lieu d'exécuter l'appel.

2026-10-03 - versions 1.8-1.9

Ajouté :

• Annonces comparables : estimate.analogs dans l'estimation express, analogs dans le rapport complet, comps dans l'estimation du loyer - les mêmes que dans l'espace personnel et le PDF.
• Les champs des tâches terminées sont décrits en entier : chiffres du rapport sous leurs vrais noms (potPrice, priceRangeLow, priceRangeHigh, …), vérification, plan, photo, flyer, brouillon.
• SDK 1.4.0 : le type Analog.

Modifié :

• Les réponses des outils ne contiennent que les champs documentés ; les champs internes qui passaient auparavant ne sont plus renvoyés.
• Un outil que GET /tools/status signale comme indisponible répond 503 service_unavailable avant toute facturation (auparavant, cela ne valait que pour le pack de contenu, les textes et la vidéo).
• La réponse de confirmation de la vérification d'évaluation ne contient que les champs de la tâche (jobId, state, status) ; le champ obsolète _id n'y est plus renvoyé.

Corrigé :

• Vidéo d'avatar : artifacts liste les identifiants nécessaires pour l'URL de téléchargement.
• Les checkIn/checkOut des locations sont documentés comme des heures de la journée.

2026-10-02 - version 1.7

Ajouté :

• Bac à sable : les clés de test (gsk_test) simulent les outils sans facturation ; l'en-tête Grem-Simulate choisit le résultat.
• estimate.confidenceScore dans l'estimation express.

Modifié :

• Les appels qui lancent un outil attendent jusqu'à 5 minutes au lieu de 60 secondes.
• L'estimation express répétée avec la même Idempotency-Key renvoie le résultat final sans seconde facturation, y compris après un délai dépassé.

Corrigé :

• estimate.confidence de l'estimation express valait toujours null.
• Les réponses du plan ne contiennent plus de champs internes.
• GET /objects sans kind, ainsi que les refus pour les annonces et les leads, expliquent désormais le motif dans detail.

2026-10-02 - version 1.6

Modifié :

• Chaque réponse de tâche porte le même champ jobId. Les noms propres à chaque outil id, _id, contentGenJobId sont toujours renvoyés et obsolètes.
• SDK 1.2.0 : Job.jobId est toujours présent.

2026-10-02 - versions 1.2-1.5

Ajouté :

• GET /voices, GET /avatar/avatars, GET /video/music, GET /video/endings - identifiants pour les outils (Données de référence).
• GET /tools/status - disponibilité des outils ; GET /works - historique des travaux.
• POST /flyer/create - flyer personnel, scope tools:flyer.
• POST /valuation/review/jobs/{id}/confirm - confirmation des données de vérification de rapport.
• Le champ state dans chaque réponse de tâche.
• Dans les erreurs - les champs code et errors, les codes forbidden, payload_too_large, service_unavailable.
• Dans la description de l'API - schémas complets de requête et de réponse pour chaque outil, contrat complet d'écriture des annonces par type, classe de facturation de chaque opération (x-grem-billing), liste des scopes et des événements.
• Les paramètres scope (annonces) et pool (leads) sont documentés.

Modifié :

• Un refus pour données manquantes (par exemple des textes sans description ni ville) donne désormais 422 business_rule avec un motif et un code. Auparavant c'était 502 provider_error.
• Un refus lié aux droits sur une ressource donne désormais 403 forbidden avec un motif. Auparavant c'était 500.
• La livraison webhook de test pour les outils a la même forme qu'une vraie : { jobId, status, state }.

Corrigé :

• Les clés d'agence fonctionnent avec tous les outils, le chat et les téléchargements de fichiers.
• Vérification de rapport et plan : le statut de la tâche est disponible via l'identifiant de la réponse, les webhooks arrivent.
• Téléchargement des fichiers du pack de contenu, des textes et de la vidéo - uniquement pour le propriétaire de la tâche.

Voir aussi

• Erreurs
• Tâches et résultats