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 з відповіді, вебхуки приходять.
  • Завантаження файлів пакета контенту, текстів і відео - тільки для власника завдання.

Пов'язані статті

Ця стаття була корисною?