Docs

Versions and API changes

Last updated: 2026-10-0312 min read

Version

The major version is in the path: /api/v1. Within v1 we do not break existing integrations. The current contract version is info.version in /openapi.json; it grows with every change.

What may change without notice

These changes are compatible, and your client should cope with them:

  • new operations and tools;
  • new optional request fields;
  • new response fields;
  • new values in response enumerations (statuses, codes), new error codes in title, new webhook event types;
  • changes to the detail text;
  • higher limits.

Writing a client

  • Ignore unknown response fields.
  • Treat an unknown enumeration value, error code or event type as "other", not as a failure.
  • Branch on status, title and code, not on the detail text.
  • Do not rely on field order or id length.
  • Rely on the job state, not on the tool's raw status.

What counts as breaking

Removing or renaming an operation, field, scope or event; a new required request field; changing a field's type or meaning; changing the status code for the same case; narrowing the allowed values. We do not make such changes in v1 without notice: the operation is first marked deprecated in /openapi.json and in this changelog, and keeps working for at least 6 months. Closing a vulnerability is the exception.

A fix that brings a response in line with this documentation is not a breaking change.

Changelog

2026-10-03 - version 1.16

Changed:

  • 429 carries code: minute_limit or daily_limit (the key's daily limit, resets at 00:00 UTC).
  • An object written with an agency key belongs to the agency; object.* and lead.* webhooks of agency objects and leads reach the agency's endpoints too.
  • Object photos: up to 50 for every kind, as in the cabinet.
  • SDK 1.7.2: an empty stream chunk no longer splits a chat event.

Fixed:

  • PUT /objects/{kind}/{id} keeps the moderation state, isSold and the publication of the listing; it used to reset them (a plain edit unpublished a live listing).
  • GET /objects no longer lists objects of suspended owners; a card hidden from guests is not shown by id either.
  • PATCH /leads/{id}: the sender of a lead without a contract may change its status, as in the cabinet; the change and the archive are written to the lead's history.

2026-10-03 - version 1.15

Changed:

  • PATCH /leads/{id} (status) and DELETE /leads/{id} follow the cabinet rules: finalization, commission collection, active contract or agreement - 422 with the reason in code. ?expand=history no longer carries service metadata (tokens, other users' ids).
  • The chat's free daily limit answers code: free_daily_limit with Retry-After until 00:00 UTC.
  • GET /works: previewUrl, link and object.photoUrl are /files/... paths for GET /artifacts/{path}; nextCursor is null on the last page.
  • Lead write: unknown fields are dropped (not refused); the lengths the service enforces are in the spec; pool: true hands the lead to the platform pool.
  • SDK 1.7.1: jobs.wait waits out a 429; chat.stream handles a CRLF split between chunks; artifact() takes signal.

Fixed:

  • Music preview: a Range past the end is 416 (it was answered as 404); a failing file service is 502, not 404.
  • A file over 15 MB in POST /uploads is 413. A refused strictPhotos listing names the photos that failed (code: photo_fetch_failed).
  • A content pack refusal names form.media.photos. Sandbox: the review takes the first file of any name; rent strings and photo service keys are not refused.

2026-10-03 - version 1.14

Changed:

  • A repeat of the express valuation with the same Idempotency-Key is now free entirely: the API call is not charged either.
  • GET /works: a cursor that is not nextCursor is 400 (it silently restarted the list).
  • POST /webhooks/{id}/test: an eventType that is not in the list is 400 (it sent a generic test).
  • Swipe Match: reasonCode takes the listed reasons only, as the service always required; lead kind may be pool.
  • SDK 1.7.0: jobs.wait survives a dropped poll; artifact() takes range; chat.stream reads CRLF streams and gives one call per event.

Fixed:

  • Music preview: bytes=-N returns the last N bytes, a Range past the end is 416.
  • A connection timeout before the request was sent releases the Idempotency-Key.
  • Sandbox: video photos under any field name the service reads, rent numbers sent as strings, flyer PNGs of the stated size.

2026-10-03 - version 1.13

Added:

  • GET /works returns what the cabinet shows for each result: street, streetNumber, previewUrl, link, repeatIndex, error and the listing (object).
  • GET /chat/sessions documents its parameters: limit, cursor, q, projectId, archivedOnly, sort.
  • Problem.title in the spec lists range_not_satisfiable; the webhook list carries requestId.
  • SDK 1.6.1: chat.listSessions takes the list parameters.

Changed:

  • The spec states limits production already enforced: avatar scriptText up to 1200 characters, flyer formats up to 3 and layouts up to 5, flyer contacts field lengths, photo seed up to 2147483647, and no unknown keys in photo data.
  • Express valuation: the gateway refuses only a request with no area at all and no property type; whether landPlotArea counts is decided by the service (land named in propertyType or apartmentType counts too).

Fixed:

  • The sandbox refuses photos the way production does (JPEG, PNG or WebP up to 25 MB - JOB_CREATE_FAILED; a mask outside cleanup - MASK_NOT_SUPPORTED) and accepts what production cuts or replaces (video title, volume, end card and closing-phrase options, landing page language, more than 20 content photos, rent furnished as a word). A report job no longer shows pending after running.
  • A refused download redirect says so instead of a timeout; a Range suffix longer than the file returns the whole file.
  • SDK 1.6.1: verifyWebhookSignature works on Node 18.

2026-10-03 - version 1.12

Added:

  • 416 range_not_satisfiable as an RFC 9457 problem (it came with an empty body).
  • priceMinor in the photo enhancement start: what the call is charged, as the cabinet shows it.
  • SDK 1.6.0: works takes from/to, chat.history takes limit/cursor, chat.sendMessage takes style.

Changed:

  • GET /match/leads: limit over 50 or page over 1000 answer 400 (they were never cut). POST /match/leads/{id}/events: an Idempotency-Key of another format is 400 instead of being dropped silently.
  • A field refused by the flyer is 400 validation naming the field (was 422).
  • A call whose payment is still being reserved under the same Idempotency-Key is 409 idempotency_conflict (was 422).
  • Express valuation: landPlotArea counts as the area only for land, as in the service.
  • A timeout, a reset connection or a socket closed mid-answer keep the Idempotency-Key taken; only a request that never reached the service releases it.
  • SDK 1.6.0: an upload is never repeated after 503; the abort listener is removed after each pause.

Fixed:

  • PDF and landing page refusals carry their reason: 402 with INSUFFICIENT_FUNDS or QUOTA_EXCEEDED (was 422 without code).
  • The sandbox refuses exactly what production refuses: file type and size of uploads; texts cut instead of refused; unknown video length, aspect and language fall back to the default; flyer codes are case-insensitive; a draft without type. The insufficient-funds simulation answers INSUFFICIENT_FUNDS, the code production sends.
  • limit and page are cut into range by the gateway itself (GET /chat/history?limit=500 answered 400; limit=0 gave 20 instead of 1).

2026-10-03 - version 1.11

Added:

  • Job results carry the fields the cabinet shows: content pack, text and video - progress, masterProfile (the story outline the texts and narration were built on) and error for a failed job; photo - metadata.error; floor plan - rooms[].stable, rooms[].placement, sourceFileId.
  • Browsers (CORS) can read the RateLimit-*, Retry-After, Grem-Sandbox, X-Request-Id and Content-Range headers.

Changed:

  • Webhooks: a test key creates and manages sandbox endpoints only; they get only sandbox job events, and live endpoints never get them.
  • limit and page outside the range are cut into it instead of 400; kind in GET /objects is case-insensitive; rooms may be fractional.
  • Idempotency-Key belongs to the API key, the method and the actual path (POST /objects/property and POST /objects/rental are different operations). After a timeout listing and lead creates hold the key for 15 minutes, like tools; a request that never reached the service releases it.
  • text/generate: customDirection is cut to 500 characters.
  • SDK 1.5.1: 503 on a write is retried only with an Idempotency-Key; a Retry-After over 30 seconds is not waited for; maxRetries is at most 10; your AbortSignal cancels the pause; message ids work on Node 18.

Fixed:

  • Sandbox works like production: checks of multipart fields, report fields per category, house heating values, commercial apartmentType and complexes; files only for finished jobs, at the tool's own path and with known artifact ids; Grem-Sandbox also on answers made before the key check; Grem-Simulate is case-insensitive.
  • Without a key, invalid query parameters answer 401 first.
  • An agent-scoped agency key no longer reads jobs started with the agency-wide key.
  • Webhook endpoints saved earlier on another port keep receiving deliveries.
  • An unsatisfiable Range answers 416 instead of 404; a report review document up to 40 MB is accepted.

2026-10-03 - version 1.10

Added:

  • The conflict error code (409): the resource is in a state that does not allow the action (Errors).
  • Video closing phrase fields in POST /video/create: ctaMode, ctaIntent, ctaText, ctaMarket; GET /video/endings options carry intent and text.
  • GET /works: the from and to filters.
  • SDK 1.5.0: the maxRetries option - 429 and 503 are retried after Retry-After.

Changed:

  • Query parameters are checked: a known parameter with an invalid value is 400 validation naming the field.
  • Webhooks: https on port 443 only, no credentials in the URL; the 11th address is 422; agency webhooks are managed with the agency-wide key only.
  • Idempotency-Key belongs to the API key and the operation; after a tool timeout the key stays reserved for 15 minutes.
  • Money refusals (quota, debt, fair use, balance) are 402 insufficient_funds with code.
  • An agent-scoped agency key sees only its own jobs and files.
  • File downloads count against the rate limit.

Fixed:

  • Every error, including a too large or malformed body, comes as RFC 9457 application/problem+json; a body over the limit is 413 payload_too_large.
  • The video ending field was never read; use ctaIntent or ctaText.
  • SDK: simulate with a live key throws instead of running the call.

2026-10-03 - versions 1.8-1.9

Added:

  • Comparable listings: estimate.analogs in the express valuation, analogs in the full report, comps in the rent estimate - the same as in the cabinet and the PDF.
  • Fields of finished jobs are described in full: report figures under their real names (potPrice, priceRangeLow, priceRangeHigh, …), review, floor plan, photo, flyer, draft.
  • SDK 1.4.0: the Analog type.

Changed:

  • Tool responses carry only documented fields; internal fields that used to slip through are no longer returned.
  • A tool that GET /tools/status reports unavailable answers 503 service_unavailable before anything is charged (before, this held only for the content pack, texts and video).
  • The appraisal review confirm response carries job fields only (jobId, state, status); the deprecated _id is no longer returned there.

Fixed:

  • Avatar video: artifacts lists the ids needed for the download URL.
  • Rental checkIn/checkOut are documented as hours of the day.

2026-10-02 - version 1.7

Added:

  • Sandbox: test keys (gsk_test) simulate tools without charging; the Grem-Simulate header picks the outcome.
  • estimate.confidenceScore in the express valuation.

Changed:

  • Calls that start a tool wait up to 5 minutes instead of 60 seconds.
  • The express valuation repeated with the same Idempotency-Key returns the finished result without a second charge, also after a timeout.

Fixed:

  • estimate.confidence of the express valuation was always null.
  • Floor plan responses no longer carry internal fields.
  • GET /objects without kind, and refusals for listings and leads, now explain the reason in detail.

2026-10-02 - version 1.6

Changed:

  • Every job response carries the same jobId field. The per-tool names id, _id, contentGenJobId are still returned and deprecated.
  • SDK 1.2.0: Job.jobId is always present.

2026-10-02 - versions 1.2-1.5

Added:

  • GET /voices, GET /avatar/avatars, GET /video/music, GET /video/endings - ids for the tools (Reference data).
  • GET /tools/status - tool availability; GET /works - work history.
  • POST /flyer/create - personal flyer, scope tools:flyer.
  • POST /valuation/review/jobs/{id}/confirm - confirming report review data.
  • The state field in every job response.
  • In errors - the code and errors fields, the codes forbidden, payload_too_large, service_unavailable.
  • In the API description - full request and response schemas for every tool, the full listing write contract per kind, each operation's billing class (x-grem-billing), the list of scopes and events.
  • The scope (listings) and pool (leads) parameters are documented.

Changed:

  • A refusal for missing data (for example texts without a description or city) is now 422 business_rule with a reason and a code. It used to be 502 provider_error.
  • A refusal for resource permissions is now 403 forbidden with a reason. It used to be 500.
  • The test webhook delivery for tools has the same shape as a real one: { jobId, status, state }.

Fixed:

  • Agency keys work with every tool, the chat and file downloads.
  • Report review and floor plan: the job status is available by the id from the response, webhooks arrive.
  • Downloading content pack, text and video files - only for the job's owner.

Was this article helpful?