openapi: 3.0.3
info:
  title: Metrius API
  version: "1.0.0"
  description: Публичный API Метриуса для работы с каналами, метриками, контентом, подписчиками, трафиком, комментариями, мониторингом и лимитами.
servers:
  - url: https://metrius.pro/api/v1
security:
  - bearerAuth: []
tags:
  - name: Каналы
    description: Получение доступных каналов и добавление Telegram-канала в workspace.
  - name: Метрики
    description: Сводные показатели и временные ряды по каналу.
  - name: Подписчики
    description: Детализация роста и оттока аудитории.
  - name: Контент
    description: Посты, рубрики и аналитика контента.
  - name: Комментарии
    description: Комментарии к постам канала.
  - name: Трафик
    description: Источники, ссылки и кампании, которые приводят аудиторию.
  - name: Мониторинг
    description: Аномалии и события, на которые стоит обратить внимание.
  - name: Лимиты
    description: Текущие лимиты API-ключа и история запросов.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Передавайте API-ключ в заголовке Authorization в формате `Bearer <api_key>`.
  parameters:
    ChannelUsername:
      name: username
      in: path
      required: true
      schema: { type: string }
      description: Username канала без символа @. Его можно взять из ответа метода `GET /channels`.
      example: channel_username
    From:
      name: from
      in: query
      required: false
      schema: { type: string, format: date }
      description: Начало периода в формате YYYY-MM-DD. Если не передать, API использует период по умолчанию для метода.
      example: "2026-07-01"
    To:
      name: to
      in: query
      required: false
      schema: { type: string, format: date }
      description: Конец периода в формате YYYY-MM-DD. Если не передать, API использует период по умолчанию для метода.
      example: "2026-07-07"
    Page:
      name: page
      in: query
      required: false
      schema: { type: integer, minimum: 1, default: 1 }
      description: Номер страницы для постраничной выдачи.
    PerPage:
      name: per_page
      in: query
      required: false
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      description: Количество объектов на странице.
  schemas:
    Error:
      type: object
      properties:
        message: { type: string }
    ChannelCreateRequest:
      type: object
      required: [link]
      properties:
        provider:
          type: string
          enum: [telegram]
          default: telegram
          description: Платформа канала. Сейчас поддерживается Telegram.
        link:
          type: string
          description: Ссылка на Telegram-канал или его username.
          example: https://t.me/channel_username
        prepare_bot:
          type: boolean
          default: true
          description: Запустить первичный сбор данных после добавления канала.
paths:
  /channels:
    get:
      tags: [Каналы]
      summary: Список доступных каналов
      description: Возвращает каналы, доступные workspace API-ключа. В ответе приходят идентификатор, username, название, платформа, статус подключения и текущие базовые показатели. Используйте username из ответа в остальных методах API.
      responses:
        "200":
          description: Список каналов, доступных текущему API-ключу.
    post:
      tags: [Каналы]
      summary: Добавить Telegram-канал
      description: Создает или находит Telegram-канал по ссылке, привязывает его к workspace API-ключа и при необходимости запускает первичный сбор данных. Возвращает карточку канала и статус операции.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ChannelCreateRequest" }
            example:
              provider: telegram
              link: https://t.me/channel_username
              prepare_bot: true
      responses:
        "201":
          description: Канал создан и привязан к workspace.
        "200":
          description: Канал найден и привязан к workspace или уже был доступен.
        "409":
          description: Канал уже подключен другим владельцем.
        "422":
          description: Некорректная ссылка или username канала.
  /channels/{username}:
    get:
      tags: [Каналы]
      summary: Карточка канала
      description: >
        Возвращает подробную информацию по одному каналу: идентификаторы, username,
        название, описание, аватар, платформу, статус, дату добавления и доступные базовые поля.
      parameters: [ { $ref: "#/components/parameters/ChannelUsername" } ]
      responses:
        "200":
          description: Карточка канала.
  /channels/{username}/rubrics_dict:
    get:
      tags: [Контент]
      summary: Словарь рубрик
      description: Возвращает справочник рубрик и тематик, найденных в контенте канала. Нужен, чтобы строить фильтры и понимать, какие категории постов доступны для аналитики.
      parameters: [ { $ref: "#/components/parameters/ChannelUsername" } ]
      responses:
        "200":
          description: Список рубрик и связанных значений по каналу.
  /channels/{username}/overview:
    get:
      tags: [Метрики]
      summary: Сводные метрики канала
      description: >
        Возвращает агрегированные показатели канала за период: подписчики, просмотры,
        вовлеченность, публикации, реакции и другие ключевые метрики. Подходит для дашборда
        или быстрой проверки динамики.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - { $ref: "#/components/parameters/From" }
        - { $ref: "#/components/parameters/To" }
      responses:
        "200":
          description: Сводные метрики за выбранный период.
  /channels/{username}/metrics/timeseries:
    get:
      tags: [Метрики]
      summary: Временные ряды метрик
      description: Возвращает динамику ключевых метрик по дням за выбранный период. Используйте метод для графиков роста аудитории, просмотров, публикаций и вовлеченности.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - { $ref: "#/components/parameters/From" }
        - { $ref: "#/components/parameters/To" }
      responses:
        "200":
          description: Временные ряды метрик по каналу.
  /channels/{username}/subscribers:
    get:
      tags: [Подписчики]
      summary: Рост и отток подписчиков
      description: Возвращает детализацию событий подписки и отписки за период. Можно фильтровать по типу события, искать по пользователям и отдельно смотреть premium-аудиторию, если такие данные доступны.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - { $ref: "#/components/parameters/From" }
        - { $ref: "#/components/parameters/To" }
        - { $ref: "#/components/parameters/Page" }
        - { $ref: "#/components/parameters/PerPage" }
        - name: action
          in: query
          description: Тип события аудитории.
          schema: { type: string, enum: [join, leave] }
        - name: premium_only
          in: query
          description: Вернуть только события по premium-пользователям.
          schema: { type: boolean }
        - name: q
          in: query
          description: Поиск по доступным полям пользователя или события.
          schema: { type: string }
      responses:
        "200":
          description: Постраничный список событий подписки и отписки.
  /channels/{username}/content:
    get:
      tags: [Контент]
      summary: Сводка по контенту
      description: >
        Возвращает контентную аналитику за период: распределение постов, динамику публикаций,
        реакции, просмотры, вовлеченность и группировки по выбранному интервалу.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - { $ref: "#/components/parameters/From" }
        - { $ref: "#/components/parameters/To" }
        - name: bucket
          in: query
          description: Интервал группировки данных.
          schema: { type: string, enum: [day, week, month], default: day }
      responses:
        "200":
          description: Сводная аналитика контента за период.
  /channels/{username}/content/summary:
    get:
      tags: [Контент]
      summary: Последний экспресс-анализ
      description: >
        Возвращает последний готовый AI-анализ канала: краткие выводы, наблюдения по контенту,
        проблемные места, рекомендации и ограничения данных. Метод не запускает новый анализ,
        а отдает уже сохраненный результат.
      parameters: [ { $ref: "#/components/parameters/ChannelUsername" } ]
      responses:
        "200":
          description: Последний сохраненный экспресс-анализ канала.
  /channels/{username}/content/posts:
    get:
      tags: [Контент]
      summary: Посты канала
      description: Возвращает посты канала за период с пагинацией, сортировкой и фильтрами. В ответе приходят дата публикации, текстовые и медиа-признаки, просмотры, реакции, вовлеченность, подписки и отписки после поста, если данные доступны.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - { $ref: "#/components/parameters/From" }
        - { $ref: "#/components/parameters/To" }
        - { $ref: "#/components/parameters/Page" }
        - { $ref: "#/components/parameters/PerPage" }
        - name: sort
          in: query
          description: Поле сортировки постов.
          schema: { type: string, enum: [posted_at, views, reactions, er, subs_24h, unsubs_24h] }
        - name: dir
          in: query
          description: Направление сортировки.
          schema: { type: string, enum: [asc, desc], default: desc }
        - name: type
          in: query
          description: Тип контента в посте.
          schema: { type: string, enum: [text, image, gallery, video, round, voice, audio, file, poll, quiz] }
      responses:
        "200":
          description: Постраничный список постов канала.
  /channels/{username}/content/post/{post_id}:
    get:
      tags: [Контент]
      summary: Детализация поста
      description: >
        Возвращает подробную карточку конкретного поста: текст, дату публикации, тип контента,
        показатели просмотров и реакций, метрики вовлеченности, связанные комментарии и доступные
        аналитические признаки.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - name: post_id
          in: path
          required: true
          description: ID поста из списка `GET /channels/{username}/content/posts`.
          schema: { type: integer }
      responses:
        "200":
          description: Подробная карточка поста.
  /channels/{username}/comments:
    get:
      tags: [Комментарии]
      summary: Комментарии канала
      description: Возвращает комментарии к постам канала за период. Можно получить общую ленту комментариев или ограничить результат конкретным `post_id`.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - { $ref: "#/components/parameters/From" }
        - { $ref: "#/components/parameters/To" }
        - { $ref: "#/components/parameters/Page" }
        - { $ref: "#/components/parameters/PerPage" }
        - name: post_id
          in: query
          description: Вернуть комментарии только к конкретному посту.
          schema: { type: integer }
      responses:
        "200":
          description: Постраничный список комментариев.
  /channels/{username}/traffic:
    get:
      tags: [Трафик]
      summary: Сводка по трафику
      description: >
        Возвращает агрегированную аналитику трафика за период: источники, переходы,
        кампании и доступные показатели эффективности привлечения аудитории.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - { $ref: "#/components/parameters/From" }
        - { $ref: "#/components/parameters/To" }
      responses:
        "200":
          description: Сводные данные по трафику канала.
  /channels/{username}/traffic/links:
    get:
      tags: [Трафик]
      summary: Трафиковые ссылки
      description: Возвращает список ссылок, которые используются для отслеживания трафика канала, вместе с доступными счетчиками и атрибутами.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - name: limit
          in: query
          description: Максимальное количество ссылок в ответе.
          schema: { type: integer, minimum: 1, maximum: 500, default: 100 }
      responses:
        "200":
          description: Список трафиковых ссылок.
  /channels/{username}/traffic/campaigns:
    get:
      tags: [Трафик]
      summary: Трафиковые кампании
      description: Возвращает кампании привлечения аудитории и связанные показатели. Метод нужен для оценки эффективности промо, посевов и других источников роста.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - name: limit
          in: query
          description: Максимальное количество кампаний в ответе.
          schema: { type: integer, minimum: 1, maximum: 500, default: 100 }
      responses:
        "200":
          description: Список трафиковых кампаний.
  /channels/{username}/monitoring:
    get:
      tags: [Мониторинг]
      summary: Мониторинг аномалий
      description: >
        Возвращает события мониторинга за период: резкие изменения аудитории, просмотров,
        активности и другие отклонения. Параметр sensitivity управляет чувствительностью
        обнаружения аномалий.
      parameters:
        - { $ref: "#/components/parameters/ChannelUsername" }
        - { $ref: "#/components/parameters/From" }
        - { $ref: "#/components/parameters/To" }
        - name: sensitivity
          in: query
          description: Чувствительность поиска аномалий. Чем меньше значение, тем больше событий может вернуться.
          schema: { type: number, enum: [1.0, 1.5, 2.0, 3.0], default: 1.0 }
      responses:
        "200":
          description: Список событий мониторинга и метаданные анализа.
  /limits:
    get:
      tags: [Лимиты]
      summary: Текущие лимиты API
      description: >
        Возвращает информацию по текущему API-ключу: доступные права, лимит запросов,
        использованное количество и остаток лимита. Метод нужен, чтобы клиент мог заранее
        контролировать расход API.
      responses:
        "200":
          description: Текущие лимиты и остаток запросов.
  /limits/history:
    get:
      tags: [Лимиты]
      summary: История API-запросов
      description: >
        Возвращает историю запросов, выполненных текущим API-ключом: метод, путь, статус ответа,
        время выполнения и дату запроса. Нужна для аудита интеграции и диагностики ошибок.
      parameters:
        - { $ref: "#/components/parameters/Page" }
        - { $ref: "#/components/parameters/PerPage" }
      responses:
        "200":
          description: Постраничная история API-запросов текущего ключа.
