Versiones y cambios de la API

Versión

La versión mayor está en la ruta: /api/v1. Dentro de v1 no rompemos las integraciones existentes. La versión actual del contrato es info.version en /openapi.json; aumenta con cada cambio.

Qué puede cambiar sin aviso

Estos cambios son compatibles, y su cliente debe soportarlos:

• operaciones y herramientas nuevas;
• campos de solicitud nuevos opcionales;
• campos de respuesta nuevos;
• valores nuevos en las enumeraciones de las respuestas (estados, códigos), códigos de error nuevos en title, tipos nuevos de eventos de webhook;
• cambios en el texto de detail;
• límites más altos.

Cómo escribir el cliente

• Ignore los campos de respuesta desconocidos.
• Trate un valor de enumeración, un código de error o un tipo de evento desconocido como «otro», no como un fallo.
• Ramifique según status, title y code, no según el texto de detail.
• No dependa del orden de los campos ni de la longitud de los ids.
• Básese en el estado del trabajo state, no en el status propio de la herramienta.

Qué se considera incompatible

Eliminar o renombrar una operación, un campo, un ámbito o un evento; un campo de solicitud obligatorio nuevo; cambiar el tipo o el significado de un campo; cambiar el código de estado para el mismo caso; restringir los valores permitidos. No hacemos estos cambios en v1 sin aviso: la operación se marca primero como deprecated en /openapi.json y en este registro, y sigue funcionando al menos 6 meses. La excepción es cerrar una vulnerabilidad.

Una corrección que hace que una respuesta coincida con esta documentación no es un cambio incompatible.

Registro de cambios

2026-10-03 - versión 1.16

Cambiado:

• 429 lleva code: minute_limit o daily_limit (el límite diario de la clave, se reinicia a las 00:00 UTC).
• Un inmueble escrito con una clave de agencia pertenece a la agencia; los webhooks object.* y lead.* de inmuebles y leads de la agencia llegan también a sus direcciones.
• Fotos del inmueble: hasta 50 para cualquier tipo, como en el panel.
• SDK 1.7.2: un fragmento vacío del flujo ya no parte un evento del chat.

Corregido:

• PUT /objects/{kind}/{id} conserva el estado de moderación, isSold y la publicación del inmueble; antes los reiniciaba (una edición simple despublicaba un anuncio activo).
• GET /objects ya no lista inmuebles de propietarios suspendidos; una ficha oculta a los invitados tampoco se entrega por id.
• PATCH /leads/{id}: el remitente de un lead sin contrato puede cambiar su estado, como en el panel; el cambio y el archivado se registran en el historial del lead.

2026-10-03 - versión 1.15

Cambiado:

• PATCH /leads/{id} (estado) y DELETE /leads/{id} siguen las reglas del panel: finalización, cobro de comisión, contrato o acuerdo vigente: 422 con el motivo en code. ?expand=history ya no lleva metadatos internos (tokens, ids de otros usuarios).
• El límite diario del chat gratuito responde code: free_daily_limit con Retry-After hasta las 00:00 UTC.
• GET /works: previewUrl, link y object.photoUrl son rutas /files/... para GET /artifacts/{path}; en la última página nextCursor es null.
• Alta de lead: los campos desconocidos se descartan (no se rechazan); la especificación recoge las longitudes que comprueba el servicio; pool: true entrega el lead al pool de la plataforma.
• SDK 1.7.1: jobs.wait espera un 429; chat.stream maneja un CRLF partido entre fragmentos; artifact() acepta signal.

Corregido:

• Vista previa de música: un Range más allá del final es 416 (respondía 404); un fallo del servicio de archivos es 502, no 404.
• Un archivo de más de 15 MB en POST /uploads es 413. Un rechazo de strictPhotos indica las fotos que fallaron (code: photo_fetch_failed).
• El rechazo de un paquete de contenido indica form.media.photos. Sandbox: la revisión toma el primer archivo con cualquier nombre; las cadenas del alquiler y las claves internas de foto no se rechazan.

2026-10-03 - versión 1.14

Cambiado:

• Repetir la valoración exprés con el mismo Idempotency-Key ahora es totalmente gratis: tampoco se cobra la llamada a la API.
• GET /works: un cursor que no es nextCursor es 400 (la lista volvía a empezar en silencio).
• POST /webhooks/{id}/test: un eventType que no está en la lista es 400 (se enviaba una prueba genérica).
• Swipe Match: reasonCode solo acepta los motivos de la lista, como el servicio siempre exigió; el kind del lead puede ser pool.
• SDK 1.7.0: jobs.wait resiste una consulta fallida; artifact() acepta range; chat.stream lee flujos con CRLF y llama una vez por evento.

Corregido:

• Vista previa de música: bytes=-N devuelve los últimos N bytes; un Range más allá del final es 416.
• Un tiempo de conexión agotado antes de enviar la solicitud libera el Idempotency-Key.
• Sandbox: fotos de vídeo con cualquier nombre de campo que lea el servicio, números del alquiler como cadenas, PNG del flyer del tamaño indicado.

2026-10-03 - versión 1.13

Añadido:

• GET /works devuelve lo que el panel muestra de cada resultado: street, streetNumber, previewUrl, link, repeatIndex, error y el inmueble (object).
• GET /chat/sessions documenta sus parámetros: limit, cursor, q, projectId, archivedOnly, sort.
• Problem.title en la especificación incluye range_not_satisfiable; la lista de webhooks lleva requestId.
• SDK 1.6.1: chat.listSessions acepta los parámetros de la lista.

Cambiado:

• La especificación indica límites que producción ya aplicaba: scriptText del avatar hasta 1200 caracteres, formats del flyer hasta 3 y layouts hasta 5, longitudes de los campos de contacts del flyer, seed de la foto hasta 2147483647 y ninguna clave desconocida en data de la foto.
• Valoración exprés: el gateway solo rechaza una solicitud sin ninguna superficie ni tipo de inmueble; si landPlotArea cuenta lo decide el servicio (también cuenta un terreno indicado en propertyType o apartmentType).

Corregido:

• El sandbox rechaza las fotos como producción (JPEG, PNG o WebP de hasta 25 MB: JOB_CREATE_FAILED; una máscara fuera de cleanup: MASK_NOT_SUPPORTED) y acepta lo que producción recorta o sustituye (título, volumen, cierre y opciones de la frase final del vídeo, idioma de la página de aterrizaje, más de 20 fotos de contenido, furnished como palabra en el alquiler). Un trabajo de informe ya no muestra pending después de running.
• Una redirección de descarga rechazada se indica como tal y no como tiempo agotado; un sufijo de Range más largo que el archivo devuelve el archivo entero.
• SDK 1.6.1: verifyWebhookSignature funciona en Node 18.

2026-10-03 - versión 1.12

Añadido:

• 416 range_not_satisfiable como problema RFC 9457 (llegaba con el cuerpo vacío).
• priceMinor al iniciar la mejora de fotos: lo que se cobra por la llamada, como lo muestra el panel.
• SDK 1.6.0: works acepta from/to, chat.history acepta limit/cursor y chat.sendMessage acepta style.

Cambiado:

• GET /match/leads: limit mayor de 50 o page mayor de 1000 responden 400 (nunca se recortaban). POST /match/leads/{id}/events: un Idempotency-Key con otro formato es 400 en lugar de descartarse en silencio.
• Un campo que rechaza el flyer es 400 validation con el nombre del campo (era 422).
• Una llamada cuyo pago aún se está reservando con el mismo Idempotency-Key es 409 idempotency_conflict (era 422).
• Valoración exprés: landPlotArea cuenta como superficie solo para land, como en el servicio.
• Un tiempo agotado, una conexión reiniciada o un socket cerrado a mitad de la respuesta dejan ocupado el Idempotency-Key; solo lo libera una solicitud que nunca llegó al servicio.
• SDK 1.6.0: una subida nunca se repite tras un 503; el oyente de cancelación se retira tras cada pausa.

Corregido:

• Los rechazos de PDF y de la página de aterrizaje llevan su motivo: 402 con INSUFFICIENT_FUNDS o QUOTA_EXCEEDED (era 422 sin code).
• El sandbox rechaza exactamente lo que rechaza producción: tipo y tamaño de los archivos subidos; los textos se recortan en lugar de rechazarse; length, aspect y language de vídeo desconocidos toman el valor por defecto; los códigos del flyer no distinguen mayúsculas; un borrador sin type. La simulación de saldo insuficiente responde INSUFFICIENT_FUNDS, el código que envía producción.
• limit y page los recorta el propio gateway (GET /chat/history?limit=500 respondía 400; limit=0 daba 20 en vez de 1).

2026-10-03 - versión 1.11

Añadido:

• Los resultados de los trabajos llevan los campos que muestra el panel: paquete de contenido, textos y vídeo, progress, masterProfile (el guion base sobre el que se crearon los textos y la locución) y error en un trabajo fallido; fotos, metadata.error; plano, rooms[].stable, rooms[].placement, sourceFileId.
• Los navegadores (CORS) pueden leer las cabeceras RateLimit-*, Retry-After, Grem-Sandbox, X-Request-Id y Content-Range.

Cambiado:

• Webhooks: una clave de prueba crea y gestiona solo direcciones del sandbox; estas reciben solo eventos de trabajos del sandbox, y las direcciones reales nunca los reciben.
• limit y page fuera del rango se ajustan a él en lugar de 400; kind en GET /objects no distingue mayúsculas; rooms admite decimales.
• Idempotency-Key pertenece a la clave de API, al método y a la ruta real (POST /objects/property y POST /objects/rental son operaciones distintas). Tras un tiempo de espera agotado, la creación de inmuebles y de leads retiene la clave 15 minutos, como las herramientas; una solicitud que nunca llegó al servicio la libera.
• text/generate: customDirection se recorta a 500 caracteres.
• SDK 1.5.1: un 503 en una escritura se repite solo con Idempotency-Key; un Retry-After de más de 30 segundos no se espera; maxRetries es como máximo 10; su AbortSignal cancela la pausa; los ids de mensaje funcionan en Node 18.

Corregido:

• El sandbox funciona como producción: comprobación de los campos multipart, de los campos del informe por categoría, de los valores de calefacción de una casa, de apartmentType comerciales y de complejos; archivos solo de trabajos terminados, en la ruta de su herramienta y con ids de artefacto conocidos; Grem-Sandbox también en las respuestas dadas antes de comprobar la clave; Grem-Simulate no distingue mayúsculas.
• Sin clave, los parámetros de consulta no válidos responden primero 401.
• Una clave de agencia vinculada a un agente ya no lee los trabajos lanzados con la clave de toda la agencia.
• Las direcciones de webhook guardadas antes con otro puerto siguen recibiendo entregas.
• Un Range imposible responde 416 en lugar de 404; se acepta un documento para la revisión de informe de hasta 40 MB.

2026-10-03 - versión 1.10

Añadido:

• El código de error conflict (409): el recurso está en un estado que no permite la acción (Errores).
• Campos de la frase final del vídeo en POST /video/create: ctaMode, ctaIntent, ctaText, ctaMarket; las opciones de GET /video/endings llevan intent y text.
• GET /works: los filtros from y to.
• SDK 1.5.0: la opción maxRetries; 429 y 503 se repiten tras Retry-After.

Cambiado:

• Los parámetros de consulta se comprueban: un parámetro conocido con un valor no válido es 400 validation indicando el campo.
• Webhooks: solo https en el puerto 443, sin credenciales en la URL; la 11.ª dirección es 422; los webhooks de la agencia solo se gestionan con la clave de toda la agencia.
• Idempotency-Key pertenece a la clave de API y a la operación; tras un tiempo de espera agotado de una herramienta, la clave queda reservada 15 minutos.
• Los rechazos por dinero (cuota, deuda, uso razonable, saldo) son 402 insufficient_funds con code.
• Una clave de agente de una agencia solo ve sus propios trabajos y archivos.
• Las descargas de archivos cuentan para el límite de frecuencia.

Corregido:

• Todo error, también un cuerpo demasiado grande o mal formado, llega como RFC 9457 application/problem+json; un cuerpo por encima del límite es 413 payload_too_large.
• El campo de vídeo ending nunca se leía; use ctaIntent o ctaText.
• SDK: simulate con una clave real lanza un error en vez de ejecutar la llamada.

2026-10-03 - versiones 1.8-1.9

Añadido:

• Comparables: estimate.analogs en la valoración exprés, analogs en el informe completo, comps en la estimación de alquiler - lo mismo que en el panel y en el PDF.
• Los campos de los trabajos terminados se describen por completo: cifras del informe con sus nombres reales (potPrice, priceRangeLow, priceRangeHigh, …), revisión, plano, foto, flyer, borrador.
• SDK 1.4.0: el tipo Analog.

Cambiado:

• Las respuestas de las herramientas solo llevan campos documentados; los campos internos que se colaban ya no se devuelven.
• Una herramienta que GET /tools/status marca como no disponible responde 503 service_unavailable antes de cobrar nada (antes solo el paquete de contenido, los textos y el vídeo).
• La confirmación de la revisión de informe solo lleva campos del trabajo (jobId, state, status); ya no incluye el _id obsoleto.

Corregido:

• Vídeo con avatar: artifacts contiene los id necesarios para la URL de descarga.
• checkIn/checkOut de alquileres se documentan como hora del día.

2026-10-02: versión 1.7

Añadido:

• Sandbox: las claves de prueba (gsk_test) simulan las herramientas sin cobrar; el encabezado Grem-Simulate elige el resultado.
• estimate.confidenceScore en la valoración exprés.

Cambiado:

• Las llamadas que lanzan una herramienta esperan hasta 5 minutos en lugar de 60 segundos.
• La valoración exprés repetida con el mismo Idempotency-Key devuelve el resultado terminado sin un segundo cobro, también tras un tiempo de espera agotado.

Corregido:

• estimate.confidence de la valoración exprés era siempre null.
• Las respuestas del plano ya no llevan campos internos.
• GET /objects sin kind y los rechazos de inmuebles y leads ahora explican el motivo en detail.

2026-10-02: versión 1.6

Cambiado:

• Cada respuesta de un trabajo lleva el mismo campo jobId. Los nombres anteriores id, _id, contentGenJobId se siguen devolviendo y están obsoletos.
• SDK 1.2.0: Job.jobId siempre está presente.

2026-10-02: versiones 1.2 a 1.5

Añadido:

• GET /voices, GET /avatar/avatars, GET /video/music, GET /video/endings: ids para las herramientas (Datos de referencia).
• GET /tools/status: disponibilidad de las herramientas; GET /works: historial de trabajos.
• POST /flyer/create: folleto personal, ámbito tools:flyer.
• POST /valuation/review/jobs/{id}/confirm: confirmación de los datos de una revisión de informe.
• El campo state en cada respuesta de trabajo.
• En los errores, los campos code y errors, los códigos forbidden, payload_too_large, service_unavailable.
• En la descripción de la API, esquemas completos de solicitud y respuesta para cada herramienta, el contrato completo de escritura de inmuebles por tipo, la clase de cobro de cada operación (x-grem-billing), la lista de ámbitos y de eventos.
• Documentados los parámetros scope (inmuebles) y pool (leads).

Cambiado:

• Un rechazo por falta de datos (por ejemplo, textos sin descripción ni ciudad) es ahora 422 business_rule con motivo y código. Antes era 502 provider_error.
• Un rechazo por permisos sobre un recurso es ahora 403 forbidden con motivo. Antes era 500.
• La entrega de prueba de un webhook para herramientas tiene la misma forma que una real: { jobId, status, state }.

Corregido:

• Las claves de agencia funcionan con todas las herramientas, el chat y la descarga de archivos.
• Revisión de informe y plano: el estado del trabajo está disponible con el id de la respuesta, y los webhooks llegan.
• La descarga de archivos del paquete de contenido, de textos y de vídeo solo está disponible para el propietario del trabajo.

Artículos relacionados

• Errores
• Trabajos y resultados