openapi: 3.0.1
info:
  title: Jay Guard API
  version: v0
servers:
- url: https://app.jayguard.com
  description: Generated server URL
tags:
- name: Audit Events
  description: Экспорт событий аудита.
- name: User masking
  description: Маскирование и демаскирование сущностей в тексте.
- name: Proxy requests
  description: Проксирование запросов с маскированием сущностей.
paths:
  /api/dataguard/public/user-masking/unmask:
    post:
      tags:
      - User masking
      summary: Демаскирование сущностей
      description: "Получение текста с оригинальными, немаскированными значениями\
        \ по идентификатору маскировки."
      operationId: unmask
      parameters:
      - name: X-DATA-GUARD-API-KEY
        in: header
        description: Ключ доступа к Jay Guard. Можно получить в интерфейсе.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUnmaskRequest'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserUnmaskResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Описание ошибки.
                  message:
                    type: string
                    description: Более подробная информация об ошибке.
              example:
                error: Invalid request parameters
                message: The maskedText field is missing
      security:
      - data-guard-api-key: []
  /api/dataguard/public/user-masking/mask:
    post:
      tags:
      - User masking
      summary: Маскирование сущностей
      description: Получение текста с маскированными сущностями.
      operationId: mask
      parameters:
      - name: X-DATA-GUARD-API-KEY
        in: header
        description: Ключ доступа к Jay Guard. Можно получить в интерфейсе.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserMaskRequest'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserMaskResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Описание ошибки.
                  message:
                    type: string
                    description: Более подробная информация об ошибке.
              example:
                error: dataguard.common.invalid_access_token
                message: X-DATA-GUARD-API-KEY is expired or invalid
      security:
      - data-guard-api-key: []
  /api/dataguard/public/audit/list:
    post:
      tags:
      - Audit Events
      summary: Экспорт событий аудита
      description: Экспорт событий аудита по заданным параметрам.
      operationId: getAuditLogs
      parameters:
      - name: Authorization
        in: header
        description: "АPI-токен для аутентификации. Формат: `Bearer {токен}`."
        required: true
        schema:
          type: string
          description: "АPI-токен для аутентификации. Формат: `Bearer {токен}`."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditLogsRequest'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventsResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Описание ошибки.
                  message:
                    type: string
                    description: Более подробная информация об ошибке.
              example:
                error: Invalid request parameters
                details: API Access token is not found or have wrong type
      security:
      - bearerAuth: []
  /api/dataguard/public/audit/details:
    post:
      tags:
      - Audit Events
      summary: Экспорт детальной информации по событиям аудита
      description: Экспорт детальной информации событий аудита по их идентификаторам.
      operationId: getAuditEventDetails
      parameters:
      - name: Authorization
        in: header
        description: "АPI-токен для аутентификации. Формат: `Bearer {токен}`."
        required: true
        schema:
          type: string
          description: "АPI-токен для аутентификации. Формат: `Bearer {токен}`."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditEventDetailsRequest'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventDetailsResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Описание ошибки.
                  message:
                    type: string
                    description: Более подробная информация об ошибке.
              example:
                error: Invalid request parameters
                details: API Access token is not found or have wrong type
      security:
      - bearerAuth: []
  /api/dataguard/public/{serviceName}/{proxyPath}:
    post:
      tags:
      - Proxy requests
      summary: Проксирование запросов
      description: "Проксирование запросов с маскированием сущностей. Подробнее о\
        \ том, как использовать этот метод, форматах запроса и ответа читайте в [д\
        окументации](https://help.jaycopilot.com/jayguard/api/proxy-requests)."
      operationId: proxy
      parameters:
      - name: serviceName
        in: path
        description: "Внутреннее название сервиса, на который будет отправлен запр\
          ос после его маскирования."
        required: true
        schema:
          type: string
          enum:
          - gigachat
          - mlp
          - openai
          - yandexGpt
      - name: proxyPath
        in: path
        description: "Путь для проксирования запроса. Например, `/v1/chat/completions`."
        required: true
        schema:
          type: string
      - name: X-DATA-GUARD-API-KEY
        in: header
        description: Ключ доступа к Jay Guard. Можно получить в интерфейсе.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxySuccessResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyErrorResponse'
      security:
      - data-guard-api-key: []
components:
  schemas:
    UserUnmaskRequest:
      required:
      - maskedText
      - maskingId
      type: object
      properties:
        maskedText:
          type: string
          description: Текст с маскированными сущностями.
          example: <jg:person_1> родился <jg:date_2> года в <jg:location_3>. Сейчас
            он работает менеджером в международной IT-компании.
        maskingId:
          type: string
          description: "Идентификатор маскировки. Приходит в ответ на запрос [POST\
            \ /api/dataguard/public/user-masking/mask](#operation/mask)."
          format: uuid
      description: Запрос с текстом с маскированными сущностями и идентификатор маскировки
    UserUnmaskResponse:
      required:
      - text
      type: object
      properties:
        text:
          type: string
          description: Исходный текст с демаскированными сущностями.
          example: Игнат Иванович Сикорский родился 1.05.1991 года в Алапаевске. Сейчас
            он работает менеджером в международной IT-компании.
      description: Ответ с демаскированием
    UserMaskRequest:
      required:
      - text
      type: object
      properties:
        text:
          type: string
          description: "Текст, в котором сущности нужно заменить на плейсхолдеры.\
            \ Список искомых сущностей указывается в фильтре, который привязан к к\
            лючу доступа. Настроить фильтр и привязать его к ключу можно в интерфе\
            йсе Jay Guard."
          example: Игнат Иванович Сикорский родился 1.05.1991 года в Алапаевске. Сейчас
            он работает менеджером в международной IT-компании.
      description: "Запрос с текстом, в котором сущности нужно заменить на плейсхо\
        лдеры."
    UserMaskResponse:
      required:
      - maskedText
      type: object
      properties:
        maskedText:
          type: string
          description: "Текст из запроса, где все найденные сущности заменены на п\
            лейсхолдеры. Если сущности не были найдены, в ответе придет исходный т\
            екст."
          example: <jg:person_1> родился <jg:date_2> года в <jg:location_3>. Сейчас
            он работает менеджером в международной IT-компании.
        maskingId:
          type: string
          description: "Идентификатор маскировки, по которому можно будет демаскир\
            овать сущности с помощью метода [POST /api/dataguard/public/user-masking/unmask](#operation/unmask).\
            \ Если сущности не были найдены, в ответе придет `null`."
          format: uuid
        action:
          type: string
          description: "Действие, которое должно применяться  к запросу с текстом\
            , где есть найденные сущности. Возвращается самое приоритетное. Приори\
            тетность действий (от меньшего к большему): `allow`, `redact`, `deny`.\
            \ Действия настраиваются в интерфейсе Jay Guard."
          enum:
          - allow
          - redact
          - deny
        reasons:
          type: array
          description: "Сущности, которые были найдены в тексте."
          example:
          - person
          - date
          - location
          items:
            type: string
            description: "Сущности, которые были найдены в тексте."
            example: "[\"person\",\"date\",\"location\"]"
      description: Ответ с маскированием
    AuditLogsRequest:
      type: object
      properties:
        createdFrom:
          type: string
          description: |-
            Дата и время начала периода,
             за который нужно прислать события аудита.
          format: date-time
        createdTo:
          type: string
          description: |-
            Дата и время окончания периода,
             за который нужно прислать события аудита.
          format: date-time
        application:
          type: string
          description: |-
            Идентификатор приложения Jay Copilot,
             для которого нужно прислать события аудита.
             Чтобы получить идентификаторы, используйте метод:
             [GET /api/appsAdapter/templates](https://help.jaycopilot.com/copilot-app-api/#tag/App-templates).
        apiKeys:
          uniqueItems: true
          type: array
          description: "Ключи доступа, для которых нужно прислать события аудита."
          items:
            type: string
            description: "Ключи доступа, для которых нужно прислать события аудита\
              ."
        limit:
          type: integer
          description: "Количество событий аудита, которое нужно прислать."
          format: int32
        offset:
          type: integer
          description: Смещение от начала списка событий аудита.
          format: int32
      description: Запрос на получение событий аудита.
    AuditEventLog:
      required:
      - eventId
      type: object
      properties:
        eventId:
          type: integer
          description: Идентификатор события аудита.
          format: int64
        requestId:
          type: string
          description: Идентификатор запроса.
        createdAt:
          type: string
          description: Дата и время запроса.
          format: date-time
        userId:
          type: string
          description: Идентификатор пользователя.
        email:
          type: string
          description: Email пользователя.
        appliedRules:
          type: array
          description: "Сущности из правил, которые были обнаружены в запросе. Есл\
            и сущность была обнаружена в контексте запроса пользователя (предшеств\
            ующем диалоге), то информация о ней также будет отображаться в `appliedRules`."
          items:
            type: string
            description: "Сущности из правил, которые были обнаружены в запросе. Е\
              сли сущность была обнаружена в контексте запроса пользователя (предш\
              ествующем диалоге), то информация о ней также будет отображаться в `appliedRules`."
        action:
          type: string
          description: "Действие, которое было применено к запросу с данными. Регу\
            лируется настроенными правилами в интерфейсе Jay Guard. Если фильтр со\
            держит правила с разными действиями, то отображается наиболее приорите\
            тное. Приоритетность действий (от меньшего к большему): `allow`, `redact`,\
            \ `deny`."
          enum:
          - allow
          - redact
          - deny
        filter:
          $ref: '#/components/schemas/FilterSimpleDto'
        application:
          type: string
          description: "Идентификатор приложения Jay Copilot, в котором был отправ\
            лен запрос."
        message:
          type: string
          description: Текст запроса.
      description: Событие аудита
    AuditEventsResponse:
      required:
      - auditEvents
      type: object
      properties:
        auditEvents:
          type: array
          description: Список событий аудита.
          items:
            $ref: '#/components/schemas/AuditEventLog'
      description: Ответ с событиями аудита.
    FilterSimpleDto:
      type: object
      properties:
        id:
          type: integer
          description: Идентификатор фильтра.
          format: int64
        name:
          type: string
          description: Название фильтра.
      description: "Фильтр, который был применен к запросу."
    AuditEventDetailsRequest:
      required:
      - eventIds
      type: object
      properties:
        eventIds:
          uniqueItems: true
          type: array
          description: "Идентификаторы событий аудита, для которых нужна детальная\
            \ информация. Идентификаторы можно получить с помощью метода [POST /api/dataguard/public/audit/list](#operation/getAuditEventDetails)."
          example:
          - 123
          - 456
          - 789
          items:
            type: integer
            description: "Идентификаторы событий аудита, для которых нужна детальн\
              ая информация. Идентификаторы можно получить с помощью метода [POST\
              \ /api/dataguard/public/audit/list](#operation/getAuditEventDetails)."
            format: int64
      description: Запрос на получение детальной информации по событиям аудита.
    AuditEventDetailsResponse:
      required:
      - auditDetails
      type: object
      properties:
        auditDetails:
          type: array
          description: Список событий аудита.
          items:
            $ref: '#/components/schemas/AuditLogDetails'
      description: Ответ с детальной информацией по событиям аудита.
    AuditEventExtractedEntityDetails:
      required:
      - searchMethodId
      - value
      type: object
      properties:
        searchMethodId:
          type: string
          description: "Идентификатор правила, по которому была обнаружена сущност\
            ь."
          example: person-rus-ner
        value:
          type: string
          description: Значение обнаруженной сущности.
          example: Игнат Иванович Сикорский
      description: "Информация о сущности, извлеченной из исходного сообщения"
    AuditLogDetails:
      required:
      - eventId
      type: object
      properties:
        eventId:
          type: integer
          description: Идентификатор события аудита.
          format: int64
          example: 123
        content:
          type: string
          description: "Сообщение с сущностями, к которым были применены правила ф\
            ильтрации."
          example: Игнат Иванович Сикорский родился 1.05.1991 года в Алапаевске. Сейчас
            он работает менеджером в международной IT-компании.
        details:
          type: array
          description: "Список сущностей, извлеченных из исходного сообщения."
          items:
            $ref: '#/components/schemas/AuditEventExtractedEntityDetails'
      description: Событие аудита.
    ProxySuccessResponse:
      type: object
      properties:
        response:
          type: object
          description: "Ответ от сервера, на который был проксирован запрос."
    ProxyErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: "Код ошибки от сервера, на который был проксирован запрос."
        message:
          type: string
          description: Более подробная информация об ошибке.
  securitySchemes:
    bearerAuth:
      type: http
      description: "АPI-токен для аутентификации. Формат: `Bearer {токен}`."
      scheme: bearer
    data-guard-api-key:
      type: apiKey
      description: Ключ доступа к Jay Guard. Можно получить в интерфейсе.
      name: X-DATA-GUARD-API-KEY
      in: header
