rewio-ru Folders API

openapi: 3.2.0
info:
  title: Review Aggregator Folders API
  description: 'Единый REST API для отзывов: сервис собирает отзывы с площадок (Яндекс Карты, 2ГИС, Google, Островок, ДокДок и др.), приводит их к общей модели и отдаёт с фильтрами и аналитикой.


    📚 **Гайды, quickstart и полный справочник – на портале разработчика: https://docs.rewio.ru**


    #### Как начать

    1. Создайте **объект** – единицу бизнеса, отзывы по которой собираем.

    2. Добавьте в него **ссылки** на страницы объекта на нужных площадках.

    3. Запрашивайте **отзывы** и **аналитику** – данные обновляются дважды в сутки.


    #### Что вы получаете по каждому отзыву

    - **Текст**, **автор**, **оценка** – приведена к единой шкале 1–5 независимо от площадки

    - **Ответ организации** – текст и дата

    - **Изображения и видео** – превью и полноразмерные ссылки


    #### Работа с отзывами

    На тарифе «Полный»:

    - **Ответы** – публикация, замена и удаление ответа от лица организации (на пробном доступе – 3 на площадку)

    - **Жалобы** – подача жалобы на отзыв через форму площадки и её итог (на пробном доступе – 3 на площадку)

    - **Дополнительный сбор** – новые отзывы по объекту вне расписания, раз в сутки (на пробном доступе – 5 сборов)


    #### Соглашения

    - **Базовый URL:** `https://api.rewio.ru`. Актуальная версия – `/v3`.

    - **Авторизация:** заголовок `X-API-Key: ` в каждом запросе. Области ключа: `read_only` / `full`.

    - **Формат:** JSON на вход и выход.

    - **Даты:** UTC, ISO 8601 без таймзоны (`2026-02-25T09:28:07`). Время площадки (`review_date`, `reply_date`) приводится к UTC везде, где это возможно; в противном случае – как на площадке.

    - **Оценки:** нормализованы к единой шкале 1–5 независимо от площадки; исходное значение площадки сохраняется отдельно (`rating_original`).

    - **Списки:** ключ элементов всегда `data`. Постраничные ответы – `{data, total, limit, offset, has_next}` (параметры `limit` 1–1000 и `offset`); полные списки – только `{data}`.

    - **Ошибки:** единый формат `{"detail": "...", "code": "..."}` с машиночитаемым `code`. Отдельно стоит `402`: доступ приостановлен (закончился пробный период или оплата) либо площадка не входит в тариф – повтор запроса не поможет.

    - **Ограничение частоты:** при слишком частых запросах – `429`; повторите с задержкой.


    #### Проба

    В блоке авторизации уже подставлен тестовый ключ (только чтение) – можно сразу выполнить любой GET-запрос.


    **Тестовый ключ (только чтение):** `hrev_FaDGMKJEDDeCR5BCBgEg0aEjMogI7O7hOzE53YY4T1M`

    **Тестовый объект:** Отель Националь, **object_id = 20**


    Бесплатный тестовый доступ на создание 30 объектов.

    **Подключение и доступ:** 📧 info@rewio.ru · ✈️ @const_rewio'
  version: 3.0.0
servers:
- url: https://api.rewio.ru
  description: Production
tags:
- name: Folders
  description: Папки объектов. Позволяют запросить отзывы сразу по нескольким объектам одним параметром `folder_id` – см. `GET /v3/reviews` и `GET /v3/analytics`.
paths:
  /v3/folders:
    post:
      tags:
      - Folders
      summary: Создать папку
      description: 'Создать папку и, если нужно, сразу положить в неё объекты.


        `object_ids` – состав новой папки, присылается

        целиком. Недоступные идентификаторы не приводят к ошибке и возвращаются в

        `ignored_object_ids`.'
      operationId: create_folder_v3_v3_folders_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderCreateV3'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderWriteV3'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Folders
      summary: Все папки с подпапками и объектами
      description: 'Дерево папок целиком: папки верхнего уровня в `data`, вложенные – в

        `subfolders` каждой. Состав объектов приходит вместе с деревом.'
      operationId: list_folders_v3_v3_folders_get
      security:
      - APIKeyHeader: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnAll_FolderV3_'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/folders/{folder_id}:
    get:
      tags:
      - Folders
      summary: Папка со всем, что в ней лежит
      description: 'Одна папка: её объекты и её подпапки со своим составом.'
      operationId: get_folder_v3_v3_folders__folder_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: integer
          description: Идентификатор папки.
          title: Folder Id
        description: Идентификатор папки.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderV3'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - Folders
      summary: Изменить папку
      description: 'Изменить название, родителя или состав папки.


        Переданный `object_ids` заменяет состав целиком; не переданный – оставляет

        как был.'
      operationId: update_folder_v3_v3_folders__folder_id__patch
      security:
      - APIKeyHeader: []
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: integer
          description: Идентификатор папки.
          title: Folder Id
        description: Идентификатор папки.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderUpdateV3'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderWriteV3'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Folders
      summary: Удалить папку
      description: Удалить папку. Объекты в ней не удаляются.
      operationId: delete_folder_v3_v3_folders__folder_id__delete
      security:
      - APIKeyHeader: []
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: integer
          description: Идентификатор папки.
          title: Folder Id
        description: Идентификатор папки.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderDeleteResponseV3'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/folders/{folder_id}/refresh:
    get:
      tags:
      - Folders
      summary: 'Дополнительный сбор по папке: состояние'
      description: 'Состояние дополнительного сбора по каждому объекту папки и её подпапок – поля как у

        `GET /v3/objects/{object_id}/refresh`.'
      operationId: get_folder_refresh_v3_v3_folders__folder_id__refresh_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: integer
          description: Идентификатор папки.
          title: Folder Id
        description: Идентификатор папки.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnAll_ObjectRefreshV3_'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - Folders
      summary: Дополнительный сбор по папке
      description: 'Дополнительный сбор новых отзывов по всем объектам папки и её подпапок.


        Каждый объект – по правилам `POST /v3/objects/{object_id}/refresh`: раз в

        сутки, один повтор площадок, с которых собрать не удалось, тариф «Полный». Запускается

        всё, что можно прямо сейчас, остальные объекты пропускаются без ошибки.

        В пробном периоде каждый запущенный объект тратит один из 5 сборов;

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


        Ответ `202` – состояние каждого объекта и `started_object_ids`. Если не

        запущен ни один объект – отказ с причиной, как у объекта:

        `402 refresh_requires_upgrade`, `402 refresh_trial_exhausted`,

        `409 refresh_in_progress`, `409 refresh_nothing_to_scrape`,

        `429 refresh_limited`.'
      operationId: refresh_folder_v3_v3_folders__folder_id__refresh_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: integer
          description: Идентификатор папки.
          title: Folder Id
        description: Идентификатор папки.
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderRefreshV3'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ObjectRefreshV3:
      properties:
        object_id:
          type: integer
          title: Object Id
          description: Объект.
        is_allowed:
          type: boolean
          title: Is Allowed
          description: Запустит ли `POST` сбор прямо сейчас.
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
          description: 'Почему нельзя – тот же код, что вернёт `POST`: `refresh_requires_upgrade`, `refresh_trial_exhausted`, `refresh_in_progress`, `refresh_limited`, `refresh_nothing_to_scrape`. `null`, если можно.'
        mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Mode
          description: 'Что сделает `POST`: `full` – соберёт все включённые ссылки объекта, `retry` – только не собравшиеся в эти сутки. `null`, если нельзя.'
        is_running:
          type: boolean
          title: Is Running
          description: Идёт ли дополнительный сбор.
        is_retried:
          type: boolean
          title: Is Retried
          description: Повтор этих суток уже использован.
        refreshed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Refreshed At
          description: Начало текущих суток объекта – последний сбор всех ссылок, UTC.
        next_available_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Next Available At
          description: Когда снова будет доступен сбор всех ссылок, UTC. `null` – уже доступен.
        retry_link_ids:
          items:
            type: integer
          type: array
          title: Retry Link Ids
          description: Ссылки, не собравшиеся в эти сутки, которым положен один повтор.
        trial_left:
          anyOf:
          - type: integer
          - type: 'null'
          title: Trial Left
          description: Сколько дополнительных сборов осталось в пробном периоде (всего 5). `null` – не пробный период.
        links:
          items:
            $ref: '#/components/schemas/RefreshLinkV3'
          type: array
          title: Links
          description: Итог дополнительных сборов этих суток по ссылкам; повтор перекрывает первый сбор по своим ссылкам. Пусто вне суток объекта.
      type: object
      required:
      - object_id
      - is_allowed
      - is_running
      - is_retried
      title: ObjectRefreshV3
      description: 'Дополнительный сбор отзывов по объекту: можно ли сейчас, а если нельзя – почему и когда снова.'
      example:
        is_allowed: true
        is_retried: false
        is_running: false
        links:
        - link_id: 11
          status: success
        - link_id: 12
          status: failed
        mode: retry
        next_available_at: '2026-10-30T09:11:00Z'
        object_id: 101
        refreshed_at: '2026-10-29T09:12:00Z'
        retry_link_ids:
        - 12
    FolderRefreshV3:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ObjectRefreshV3'
          type: array
          title: Data
          description: Состояние каждого объекта папки и её подпапок.
        started_object_ids:
          items:
            type: integer
          type: array
          title: Started Object Ids
          description: Объекты, по которым сбор запущен этим запросом.
      type: object
      required:
      - data
      - started_object_ids
      title: FolderRefreshV3
      description: Итог нажатия «Обновить» у папки.
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
        code:
          type: string
          title: Code
      type: object
      required:
      - detail
      - code
      title: ErrorResponse
      description: Standard error response returned by all exception handlers.
    ReturnAll_FolderV3_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/FolderV3'
          type: array
          title: Data
          description: Все элементы (пагинации нет).
      type: object
      required:
      - data
      title: ReturnAll[FolderV3]
    ReturnAll_ObjectRefreshV3_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ObjectRefreshV3'
          type: array
          title: Data
          description: Все элементы (пагинации нет).
      type: object
      required:
      - data
      title: ReturnAll[ObjectRefreshV3]
    FolderUpdateV3:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          title: Name
          description: Новое название папки.
        parent_folder_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Parent Folder Id
          description: Новый родитель папки.
        object_ids:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Object Ids
          description: Новый состав папки – полная замена прежнего. Недоступные идентификаторы возвращаются в `ignored_object_ids`.
      type: object
      title: FolderUpdateV3
      description: Тело изменения папки – передавайте только изменяемые поля.
    FolderCreateV3:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: Название папки.
        parent_folder_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Parent Folder Id
          description: Родительская папка. Глубина ограничена двумя уровнями.
        object_ids:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Object Ids
          description: Состав папки. Недоступные идентификаторы возвращаются в `ignored_object_ids`.
      type: object
      required:
      - name
      title: FolderCreateV3
      description: Тело создания папки.
    FolderWriteV3:
      properties:
        id:
          type: integer
          title: Id
          description: Идентификатор папки.
        user_id:
          type: integer
          title: User Id
          description: Идентификатор аккаунта – владельца папки.
        name:
          type: string
          title: Name
          description: Название папки.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Момент создания папки (UTC, ISO 8601).
        parent_folder_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Parent Folder Id
          description: Родительская папка; `null` у папки верхнего уровня.
        objects:
          items:
            $ref: '#/components/schemas/FolderObjectV3'
          type: array
          title: Objects
          description: Собственный состав папки – объекты с названиями.
          default: []
        subfolders:
          items:
            $ref: '#/components/schemas/FolderV3'
          type: array
          title: Subfolders
          description: Подпапки со своим составом.
          default: []
        review_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Review Count
          description: 'Сколько отзывов в ленте папки (`GET /v3/reviews?folder_id=`): объекты папки и её подпапок, отзыв общей для двух объектов ссылки считается один раз.'
        is_demo:
          type: boolean
          title: Is Demo
          description: Папка примеров, которую кабинет кладёт новому клиенту.
          default: false
        ignored_object_ids:
          items:
            type: integer
          type: array
          title: Ignored Object Ids
          description: 'Идентификаторы из присланного `object_ids`, которые в состав не попали: чужие, удалённые или несуществующие объекты. Запрос при этом выполняется – остальные объекты кладутся в папку.'
      type: object
      required:
      - id
      - user_id
      - name
      - created_at
      title: FolderWriteV3
      description: Ответ на создание и изменение – та же папка плюс список пропущенного.
    FolderObjectV3:
      properties:
        id:
          type: integer
          title: Id
          description: Идентификатор объекта.
        name:
          type: string
          title: Name
          description: Название объекта.
      type: object
      required:
      - id
      - name
      title: FolderObjectV3
      description: Объект в составе папки – идентификатор и название, чтобы не ходить за ними отдельно.
    FolderDeleteResponseV3:
      properties:
        id:
          type: integer
          title: Id
          description: Идентификатор удалённой папки.
        name:
          type: string
          title: Name
          description: Название удалённой папки.
      type: object
      required:
      - id
      - name
      title: FolderDeleteResponseV3
      description: Ответ на удаление папки.
    RefreshLinkV3:
      properties:
        link_id:
          type: integer
          title: Link Id
          description: Ссылка объекта.
        status:
          type: string
          title: Status
          description: '`running` – собирается, `success` – собрана, `failed` – не собралась.'
      type: object
      required:
      - link_id
      - status
      title: RefreshLinkV3
      description: Итог дополнительных сборов этих суток по одной ссылке.
    FolderV3:
      properties:
        id:
          type: integer
          title: Id
          description: Идентификатор папки.
        user_id:
          type: integer
          title: User Id
          description: Идентификатор аккаунта – владельца папки.
        name:
          type: string
          title: Name
          description: Название папки.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Момент создания папки (UTC, ISO 8601).
        parent_folder_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Parent Folder Id
          description: Родительская папка; `null` у папки верхнего уровня.
        objects:
          items:
            $ref: '#/components/schemas/FolderObjectV3'
          type: array
          title: Objects
          description: Собственный состав папки – объекты с названиями.
          default: []
        subfolders:
          items:
            $ref: '#/components/schemas/FolderV3'
          type: array
          title: Subfolders
          description: Подпапки со своим составом.
          default: []
        review_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Review Count
          description: 'Сколько отзывов в ленте папки (`GET /v3/reviews?folder_id=`): объекты папки и её подпапок, отзыв общей для двух объектов ссылки считается один раз.'
        is_demo:
          type: boolean
          title: Is Demo
          description: Папка примеров, которую кабинет кладёт новому клиенту.
          default: false
      type: object
      required:
      - id
      - user_id
      - name
      - created_at
      title: FolderV3
      description: Папка со своим составом и подпапками.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    APIKeyCookie:
      type: apiKey
      in: cookie
      name: rewio_session