Как работать с папками

Папка объединяет объекты, чтобы спрашивать данные сразу по всему набору.

Не нужно запрашивать объекты по одному и складывать результаты у себя: положите их в папку и спрашивайте данные по ней целиком.

curl "https://api.rewio.ru/v3/reviews?folder_id=7&limit=50" \
  -H "X-API-Key: hrev_ВАШ_КЛЮЧ"

curl "https://api.rewio.ru/v3/analytics?folder_id=7" \
  -H "X-API-Key: hrev_ВАШ_КЛЮЧ"

Как устроено

Папка «Сеть Север»  (folder_id: 7)
├── Объект «Гранд Отель»            → ссылки → отзывы…
├── Объект «Приморская»             → ссылки → отзывы…
└── Подпапка «Москва»  (folder_id: 12)
    ├── Объект «Тверская»           → ссылки → отзывы…
    └── Объект «Арбат»              → ссылки → отзывы…

• Максимальная глубина – два уровня. Папка → подпапка → объекты. Попытка вложить подпапку в подпапку – 400 folder_depth_exceeded.
• У подпапки один родитель, а объект может лежать в скольких угодно папках – например, и в «Сеть Север», и в «Премиум-сегмент».
• Запрос по родительской папке возвращает объединение: её собственные объекты плюс объекты всех её подпапок. Ссылка, попавшая в несколько объектов одной папки, учитывается один раз: ни отзывы, ни метрики не удваиваются.
• Папки не тарифицируются: место в лимите занимают объекты. Ограничение одно – не больше 1000 живых папок на аккаунт.

Управление папками

Пять методов. Для чтения хватит ключа read_only, для остальных нужен full.

GET /v3/folders отдаёт дерево целиком: в data – корневые папки, подпапки лежат внутри своего родителя в поле subfolders. Порядок и там, и там: по названию, при совпадении – по id; сортировка регистронезависимая.

{
  "data": [
    {
      "id": 7,
      "user_id": 42,
      "name": "Сеть Север",
      "created_at": "2026-07-28T09:14:02",
      "parent_folder_id": null,
      "objects": [{ "id": 20, "name": "Гранд Отель" }],
      "subfolders": [
        {
          "id": 12,
          "user_id": 42,
          "name": "Москва",
          "created_at": "2026-07-28T09:20:41",
          "parent_folder_id": 7,
          "objects": [{ "id": 31, "name": "Тверская" }],
          "subfolders": []
        }
      ]
    }
  ]
}

Состав у каждой папки свой: объекты подпапки в objects родителя не попадают, хотя в выдачу по его folder_id войдут. Нужна одна ветка вместо всего дерева, запросите GET /v3/folders/{folder_id}; для подпапки он вернёт её саму с пустым subfolders.

Объект, которого у вас нет (чужой, удалённый или несуществующий), остальной состав не отменяет. Он просто не попадёт в папку, а его идентификатор вернётся в ignored_object_ids.

На вход идут идентификаторы (object_ids), а в ответе состав приходит объектами с названиями (objects), чтобы нарисовать дерево, не запрашивая объекты отдельно.

Повторный POST с тем же заголовком Idempotency-Key вернёт ту же папку и не создаст вторую. Названия папок не обязаны быть уникальными, так что на таймауте клиента это единственная защита от дубля.

Удалить папку с живыми подпапками нельзя – 409 folder_not_empty: сначала удалите или перенесите их. Удалённая подпапка удалению родителя не мешает.

Что попадает в выдачу

Состав папки и то, что реально вернётся, – не одно и то же:

• Выключенный объект (is_active=false) остаётся виден в составе через GET /v3/folders, но отзывов и аналитики не даёт. Прямой запрос по такому объекту отвечает 404, а внутри папки он молча отсутствует.
• Удалённый объект исчезает и из состава, и из выдачи.
• Выключенная ссылка внутри живого объекта данных не даёт.

Если папка вернула пусто, проверьте состав через GET /v3/folders, а затем is_active у объектов и ссылок.

Адресация: ровно один из двух

object_id и folder_id взаимоисключимы на GET /v3/reviews, GET /v3/analytics и GET /v3/analytics/timeseries:

link_ids и source_ids фильтруют внутри состава папки.

В аналитике by_source схлопывает одну площадку разных объектов в одну строку с суммой, а meta показывает фактический состав, попавший в расчёт:

{
  "meta": {
    "object_id": null,
    "folder_id": 7,
    "object_ids": [20, 21, 34],
    "published_from": "2000-01-01",
    "published_to": "2026-07-28",
    "source_ids": [1, 3],
    "generated_at": "2026-07-28T09:20:11Z"
  }
}

Поле meta.object_id присутствует всегда: в папочном режиме оно приходит null, а не пропадает.