Docs

Версии и изменения API

Последнее обновление: 2026-10-0310 мин чтения

Версия

Мажорная версия - в пути: /api/v1. В рамках v1 мы не ломаем существующие интеграции. Текущая версия контракта - поле info.version в /openapi.json; она растет с каждым изменением.

Что может измениться без предупреждения

Эти изменения совместимы, и ваш клиент должен их выдерживать:

  • новые операции и инструменты;
  • новые необязательные поля в запросах;
  • новые поля в ответах;
  • новые значения в перечнях в ответах (статусы, коды), новые коды ошибок в title, новые типы событий вебхуков;
  • изменение текста в detail;
  • рост лимитов.

Как писать клиента

  • Игнорируйте неизвестные поля ответа.
  • Неизвестное значение перечня, неизвестный код ошибки или тип события обрабатывайте как «другое», а не как сбой.
  • Ветвитесь по status, title и code, а не по тексту detail.
  • Не полагайтесь на порядок полей и длину идентификаторов.
  • Ориентируйтесь на state задачи, а не на сырой status инструмента.

Что считается несовместимым

Удаление или переименование операции, поля, области доступа или события; новое обязательное поле в запросе; изменение типа поля или его смысла; изменение кода ответа для того же случая; сужение допустимых значений. Таких изменений в v1 мы не делаем без предупреждения: операция сначала помечается как устаревшая (deprecated) в /openapi.json и в этом журнале и продолжает работать не меньше 6 месяцев. Исключение - закрытие уязвимости.

Исправление, которое приводит ответ в соответствие с этой документацией, несовместимым изменением не считается.

Журнал изменений

2026-10-03 - версия 1.16

Изменено:

  • 429 содержит code: minute_limit или daily_limit (дневной лимит ключа, обновляется в 00:00 UTC).
  • Объект, записанный ключом агентства, принадлежит агентству; вебхуки object.* и lead.* для объектов и лидов агентства доходят и до адресов агентства.
  • Фото объекта: до 50 для любого вида, как в кабинете.
  • SDK 1.7.2: пустая часть потока больше не разрезает событие чата.

Исправлено:

  • PUT /objects/{kind}/{id} сохраняет состояние модерации, isSold и публикацию объекта; раньше сбрасывал их (обычная правка снимала живой объект с публикации).
  • GET /objects больше не показывает объекты заблокированных владельцев; карточка, скрытая от гостей, не отдается и по id.
  • PATCH /leads/{id}: отправитель лида без договора может менять его статус, как в кабинете; смена и архивация записываются в историю лида.

2026-10-03 - версия 1.15

Изменено:

  • PATCH /leads/{id} (статус) и DELETE /leads/{id} соблюдают правила кабинета: финализация, сбор комиссии, действующий договор или соглашение - 422 с причиной в code. ?expand=history больше не содержит служебных метаданных (токены, id других пользователей).
  • Дневной лимит бесплатного чата отвечает code: free_daily_limit с Retry-After до 00:00 UTC.
  • GET /works: previewUrl, link и object.photoUrl - пути /files/... для GET /artifacts/{path}; на последней странице nextCursor - null.
  • Запись лида: неизвестные поля отбрасываются (а не отклоняются); в спецификации длины, которые проверяет сервис; pool: true передает лид в пул платформы.
  • SDK 1.7.1: jobs.wait пережидает 429; chat.stream обрабатывает CRLF, разорванный между частями; artifact() принимает signal.

Исправлено:

  • Превью музыки: Range за концом файла - 416 (отвечало 404); сбой файлового сервиса - 502, а не 404.
  • Файл больше 15 МБ в POST /uploads - 413. Отказ strictPhotos называет фото, которые не загрузились (code: photo_fetch_failed).
  • Отказ пакета контента называет form.media.photos. Песочница: проверка отчета берет первый файл с любым именем; строки аренды и служебные ключи фото не отклоняются.

2026-10-03 - версия 1.14

Изменено:

  • Повтор экспресс-оценки с тем же Idempotency-Key теперь полностью бесплатный: вызов API тоже не списывается.
  • GET /works: cursor, который не является nextCursor, - 400 (список молча начинался сначала).
  • POST /webhooks/{id}/test: eventType, которого нет в списке, - 400 (отправлялся общий тест).
  • Swipe Match: reasonCode принимает только перечисленные причины, как сервис требовал и раньше; kind лида может быть pool.
  • SDK 1.7.0: jobs.wait переживает один неудачный запрос; artifact() принимает range; chat.stream читает потоки с CRLF и вызывается раз на событие.

Исправлено:

  • Превью музыки: bytes=-N возвращает последние N байтов, Range за концом файла - 416.
  • Тайм-аут соединения до отправки запроса освобождает Idempotency-Key.
  • Песочница: фото видео под любым именем поля, которое читает сервис, числа аренды строкой, PNG флаера заявленного размера.

2026-10-03 - версия 1.13

Добавлено:

  • GET /works возвращает то, что кабинет показывает для каждого результата: street, streetNumber, previewUrl, link, repeatIndex, error и объект (object).
  • У GET /chat/sessions описаны параметры: limit, cursor, q, projectId, archivedOnly, sort.
  • Problem.title в спецификации содержит range_not_satisfiable; список вебхуков содержит requestId.
  • SDK 1.6.1: chat.listSessions принимает параметры списка.

Изменено:

  • Спецификация называет ограничения, которые бой уже применял: scriptText аватара до 1200 символов, formats флаера до 3 и layouts до 5, длины полей contacts флаера, seed фото до 2147483647 и никаких неизвестных ключей в data фото.
  • Экспресс-оценка: шлюз отклоняет только запрос совсем без площади и без типа объекта; считается ли landPlotArea, решает сервис (участок, названный в propertyType или apartmentType, тоже считается).

Исправлено:

  • Песочница отклоняет фото так же, как бой (JPEG, PNG или WebP до 25 МБ - JOB_CREATE_FAILED; маска вне cleanup - MASK_NOT_SUPPORTED), и принимает то, что бой обрезает или заменяет (название, громкость, финальный кадр и параметры финальной фразы видео, язык сайта, больше 20 фото контента, furnished словом в аренде). Задача отчета больше не показывает pending после running.
  • Отклоненный редирект скачивания так и называется, а не таймаутом; суффикс Range длиннее файла возвращает весь файл.
  • SDK 1.6.1: verifyWebhookSignature работает в Node 18.

2026-10-03 - версия 1.12

Добавлено:

  • 416 range_not_satisfiable как проблема RFC 9457 (приходил с пустым телом).
  • priceMinor в запуске улучшения фото: сколько списано за вызов, как показывает кабинет.
  • SDK 1.6.0: works принимает from/to, chat.history - limit/cursor, chat.sendMessage - style.

Изменено:

  • GET /match/leads: limit больше 50 или page больше 1000 - 400 (их никогда не обрезали). POST /match/leads/{id}/events: Idempotency-Key другого формата - 400, а не молчаливое отбрасывание.
  • Поле, отклоненное флаером, - 400 validation с именем поля (было 422).
  • Вызов, оплата которого еще резервируется под тем же Idempotency-Key, - 409 idempotency_conflict (было 422).
  • Экспресс-оценка: landPlotArea считается площадью только для land, как в сервисе.
  • Таймаут, сброшенное соединение или сокет, закрытый посреди ответа, оставляют Idempotency-Key занятым; освобождает его только запрос, не дошедший до сервиса.
  • SDK 1.6.0: загрузка после 503 не повторяется; слушатель отмены снимается после каждой паузы.

Исправлено:

  • Отказы PDF и сайта несут причину: 402 с INSUFFICIENT_FUNDS или QUOTA_EXCEEDED (было 422 без code).
  • Песочница отклоняет ровно то, что и бой: тип и размер загруженных файлов; тексты обрезаются, а не отклоняются; неизвестные length, aspect и language видео заменяются значениями по умолчанию; коды флаера без учета регистра; черновик без type. Симуляция нехватки средств отвечает INSUFFICIENT_FUNDS - кодом, который присылает бой.
  • limit и page обрезает сам шлюз (GET /chat/history?limit=500 отвечал 400; limit=0 давал 20 вместо 1).

2026-10-03 - версия 1.11

Добавлено:

  • Результаты задач содержат поля, которые показывает кабинет: пакет контента, тексты и видео - progress, masterProfile (сюжетная основа, на которой построены тексты и озвучка) и error у задачи со сбоем; фото - metadata.error; планировка - rooms[].stable, rooms[].placement, sourceFileId.
  • Браузеры (CORS) могут читать заголовки RateLimit-*, Retry-After, Grem-Sandbox, X-Request-Id и Content-Range.

Изменено:

  • Вебхуки: тестовый ключ создает и меняет только адреса песочницы; они получают только события задач песочницы, а боевые адреса их не получают никогда.
  • limit и page вне диапазона приводятся к нему вместо 400; kind в GET /objects не зависит от регистра; rooms может быть дробным.
  • Idempotency-Key принадлежит API-ключу, методу и фактическому пути (POST /objects/property и POST /objects/rental - разные операции). После таймаута создание объекта и лида удерживает ключ 15 минут, как инструменты; запрос, не дошедший до сервиса, ключ освобождает.
  • text/generate: customDirection обрезается до 500 символов.
  • SDK 1.5.1: 503 на запись повторяется только с Idempotency-Key; Retry-After больше 30 секунд не ждется; maxRetries - не больше 10; ваш AbortSignal прерывает паузу; id сообщений работают в Node 18.

Исправлено:

  • Песочница работает как бой: проверка полей multipart, полей отчета по категориям, значений отопления дома, коммерческих apartmentType и ЖК; файлы - только у завершенных задач, по пути своего инструмента и с известными id артефактов; Grem-Sandbox и в ответах до проверки ключа; Grem-Simulate не зависит от регистра.
  • Без ключа неверные параметры запроса сначала дают 401.
  • Ключ агентства, привязанный к агенту, больше не читает задачи, запущенные общим ключом агентства.
  • Адреса вебхуков, сохраненные раньше с другим портом, продолжают получать доставки.
  • Невыполнимый Range дает 416 вместо 404; документ для проверки отчета принимается до 40 МБ.

2026-10-03 - версия 1.10

Добавлено:

  • Код ошибки conflict (409): ресурс в состоянии, которое не позволяет действие (Ошибки).
  • Поля финальной фразы видео в POST /video/create: ctaMode, ctaIntent, ctaText, ctaMarket; варианты GET /video/endings содержат intent и text.
  • GET /works: фильтры from и to.
  • SDK 1.5.0: опция maxRetries - 429 и 503 повторяются после Retry-After.

Изменено:

  • Параметры запроса проверяются: известный параметр с недопустимым значением - 400 validation с названием поля.
  • Вебхуки: только https на порту 443, без логина и пароля в URL; 11-й адрес - 422; вебхуками агентства управляет только ключ всего агентства.
  • Idempotency-Key принадлежит API-ключу и операции; после таймаута инструмента ключ остается занятым 15 минут.
  • Денежные отказы (квота, долг, добросовестное использование, баланс) - 402 insufficient_funds с code.
  • Ключ агента агентства видит только свои задачи и файлы.
  • Скачивание файлов считается в лимит частоты.

Исправлено:

  • Любая ошибка, включая слишком большое или битое тело, приходит в формате RFC 9457 application/problem+json; тело больше лимита - 413 payload_too_large.
  • Поле видео ending никогда не читалось; используйте ctaIntent или ctaText.
  • SDK: simulate с боевым ключом выбрасывает ошибку вместо запуска вызова.

2026-10-03 - версии 1.8-1.9

Добавлено:

  • Аналоги: estimate.analogs в экспресс-оценке, analogs в полном отчёте, comps в оценке аренды - то же, что в кабинете и PDF.
  • Поля готовых задач описаны полностью: цифры отчёта под настоящими именами (potPrice, priceRangeLow, priceRangeHigh, …), проверка отчёта, планировка, фото, флаер, черновик.
  • SDK 1.4.0: тип Analog.

Изменено:

  • Ответы инструментов содержат только описанные поля; внутренние поля, которые раньше проскакивали, больше не отдаются.
  • Инструмент, который GET /tools/status показывает недоступным, отвечает 503 service_unavailable до списания (раньше - только пакет контента, тексты и видео).
  • Ответ подтверждения проверки отчёта содержит только поля задачи (jobId, state, status); устаревшего _id в нём больше нет.

Исправлено:

  • Видео аватара: artifacts содержит id, нужные для ссылки на скачивание.
  • checkIn/checkOut аренды описаны как час дня.

2026-10-02 - версия 1.7

Добавлено:

  • Песочница: тестовые ключи (gsk_test) имитируют инструменты без оплаты; заголовок Grem-Simulate выбирает результат.
  • estimate.confidenceScore в экспресс-оценке.

Изменено:

  • Запуск инструмента ждёт до 5 минут вместо 60 секунд.
  • Экспресс-оценка, повторённая с тем же Idempotency-Key, возвращает готовый результат без второго списания, в том числе после таймаута.

Исправлено:

  • estimate.confidence экспресс-оценки всегда был null.
  • Ответы плана этажа больше не содержат внутренних полей.
  • GET /objects без kind и отказы по объектам и лидам теперь объясняют причину в detail.

2026-10-02 - версия 1.6

Изменено:

  • Каждый ответ задачи содержит одно и то же поле jobId. Прежние имена id, _id, contentGenJobId еще возвращаются, но устарели.
  • SDK 1.2.0: Job.jobId есть всегда.

2026-10-02 - версии 1.2-1.5

Добавлено:

  • GET /voices, GET /avatar/avatars, GET /video/music, GET /video/endings - идентификаторы для инструментов (Справочные данные).
  • GET /tools/status - доступность инструментов; GET /works - история работ.
  • POST /flyer/create - персональный флаер, область tools:flyer.
  • POST /valuation/review/jobs/{id}/confirm - подтверждение данных проверки отчета.
  • Поле state во всех ответах задач.
  • В ошибках - поля code и errors, коды forbidden, payload_too_large, service_unavailable.
  • В описании API - полные схемы запросов и ответов каждого инструмента, полный контракт записи объектов для каждого типа, класс оплаты каждой операции (x-grem-billing), список областей доступа и событий.
  • Параметры scope (объекты) и pool (лиды) описаны в справке.

Изменено:

  • Отказ из-за нехватки данных (например, тексты без описания и города) теперь 422 business_rule с причиной и кодом. Раньше приходило 502 provider_error.
  • Отказ из-за прав на ресурс теперь 403 forbidden с причиной. Раньше приходило 500.
  • Тестовая доставка вебхука для инструментов имеет ту же форму, что и боевая: { jobId, status, state }.

Исправлено:

  • Ключи агентства работают со всеми инструментами, чатом и скачиванием файлов.
  • Проверка отчета и планировка: статус задачи доступен по id из ответа, вебхуки приходят.
  • Скачивание файлов пакета контента, текстов и видео - только для владельца задачи.

Связанные статьи

Эта статья была полезной?