openapi: "3.0.0"
info:
  title: "Jay Copilot API"
  description: "API для работы с приложениями Jay Copilot."
  version: "1.0.0"
servers:
  - url: "https://app.jaycopilot.com"
tags:
  - name: "Files"
    description: "Загрузка, получение и удаление файлов."
  - name: "App templates"
    description: "Получение списка шаблонов приложений."
  - name: "Apps"
    description: "Работа с приложениями."
  - name: "Conversations"
    description: "Работа с диалогами и сообщениями."
paths:
  /api/appsAdapter/files:
    post:
      tags:
        - "Files"
      summary: "Загрузка файла"
      description: "Загрузка файла на сервер."
      operationId: "uploadFile"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: "object"
              properties:
                file:
                  type: "string"
                  format: "binary"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileResponse"
        "400":
          description: "Bad Request"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/files/{fileId}:
    get:
      tags:
        - "Files"
      summary: "Получение файла"
      description: "Получение файла с сервера."
      operationId: "getFile"
      parameters:
        - $ref: '#/components/parameters/fileId'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileResponse"
        "404":
          description: "Not Found"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
    delete:
      tags:
        - "Files"
      summary: "Удаление файла"
      description: "Удаление файла с сервера."
      operationId: "deleteFile"
      parameters:
        - $ref: '#/components/parameters/fileId'
      responses:
        "200":
          description: "OK"
        "400":
          description: "Bad Request"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/templates:
    get:
      tags:
        - "App templates"
      summary: "Получение списка шаблонов приложений"
      description: "Получение списка доступных пользователю шаблонов приложений."
      operationId: "getTemplates"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplatesListResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/apps:
    post:
      tags:
        - "Apps"
      summary: "Создание приложения"
      description: "Создание нового приложения"
      operationId: "createApp"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppCreateRequest"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
    get:
      tags:
        - "Apps"
      summary: "Получение списка приложений"
      description: "Получение списка приложений."
      operationId: "findApps"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppsListResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/apps/favorite:
    get:
      tags:
        - "Apps"
      summary: "Получение списка избранных приложений"
      description: "Получение списка избранных приложений."
      operationId: "findFavoriteApps"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppsListResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/apps/{appId}:
    get:
      tags:
        - "Apps"
      summary: "Получение приложения"
      description: "Получение приложения по идентификатору."
      operationId: "getApp"
      parameters:
        - $ref: '#/components/parameters/appId'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
    put:
      tags:
        - "Apps"
      summary: "Обновление приложения"
      description: "Обновление приложения."
      operationId: "updateApp"
      parameters:
        - $ref: '#/components/parameters/appId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppUpdateRequest"
      responses:
        "200":
          description: "OK"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/conversations:
    post:
      tags:
        - "Conversations"
      summary: "Создание диалога"
      description: "Создание диалога с новым или существующим приложением."
      operationId: "createConversation"
      parameters:
        - name: "async"
          in: "query"
          description: "Отправить асинхронный запрос."
          schema:
            default: false
            type: "boolean"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/ConversationCreateRequest"
                - $ref: "#/components/schemas/ConversationAndAppCreateRequest"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
    get:
      tags:
        - "Conversations"
      summary: "Получение списка диалогов"
      description: "Получение списка диалогов."
      operationId: "findConversations"
      parameters:
        - name: "hasUnreadChanges"
          in: "query"
          description: "Фильтр по непрочитанным сообщениям.\n\nУкажите `true`, чтобы получить только диалоги, где есть непрочитанные сообщения."
          schema:
            default: false
            type: "boolean"
        - name: "orderBy"
          in: "query"
          description: "Критерий сортировки диалогов.\n\nУкажите `created` для сортировки по времени создания, `updated` — по времени последнего обновления."
          schema:
            default: "updated"
            type: "string"
            enum:
              - "created"
              - "updated"
        - name: "sort"
          in: "query"
          description: "Порядок сортировки диалогов по критерию `orderBy`.\n\nУкажите `asc` для сортировки по возрастанию, `desc` — по убыванию."
          schema:
            default: "desc"
            type: "string"
            enum:
              - "asc"
              - "desc"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationsListResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/conversations/{conversationId}:
    get:
      tags:
        - "Conversations"
      summary: "Получение диалога"
      description: "Получение диалога по идентификатору."
      operationId: "getConversation"
      parameters:
        - $ref: '#/components/parameters/conversationId'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
    delete:
      tags:
        - "Conversations"
      summary: "Удаление диалога"
      description: "Удаление диалога по идентификатору."
      operationId: "deleteConversation"
      parameters:
        - $ref: '#/components/parameters/conversationId'
      responses:
        "200":
          description: "OK"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
    put:
      tags:
        - "Conversations"
      summary: "Обновление диалога"
      description: "Обновление диалога."
      operationId: "updateConversation"
      parameters:
        - $ref: '#/components/parameters/conversationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConversationUpdateRequest"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/conversations/{conversationId}/app:
    put:
      tags:
        - "Conversations"
      summary: "Обновление приложения, с которым ведется диалог"
      description: "Обновление приложения, с которым ведется диалог."
      operationId: "updateConversationApp"
      parameters:
        - $ref: '#/components/parameters/conversationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppCreateRequest"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/conversations/{conversationId}/clear:
    post:
      tags:
        - "Conversations"
      summary: "Удаление истории сообщений"
      description: "Удаление истории сообщений диалога (очистка контекста)."
      operationId: "resetConversation"
      parameters:
        - $ref: '#/components/parameters/conversationId'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/conversations/{conversationId}/history:
    get:
      tags:
        - "Conversations"
      summary: "Получение истории сообщений"
      description: "Получение истории сообщений диалога."
      operationId: "getConversationHistory"
      parameters:
        - $ref: '#/components/parameters/conversationId'
        - $ref: '#/components/parameters/pageSizeParam'
        - $ref: '#/components/parameters/beforeParam'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationHistoryResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
  /api/appsAdapter/conversations/{conversationId}/message:
    post:
      tags:
        - "Conversations"
      summary: "Отправка сообщения"
      description: "Отправка сообщения в диалог."
      operationId: "sendMessage"
      parameters:
        - $ref: '#/components/parameters/conversationId'
        - name: "async"
          in: "query"
          description: "Отправить асинхронный запрос."
          schema:
            default: false
            type: "boolean"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: "object"
              properties:
                file:
                  type: "string"
                  format: "binary"
                text:
                  type: "string"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          description: "Unauthorized"
      security:
        - ApiKeyAuth: [ ]
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
  parameters:
    appId:
      name: "appId"
      in: "path"
      description: "Идентификатор приложения."
      required: true
      schema:
        type: "string"
    conversationId:
      name: "conversationId"
      in: "path"
      description: "Идентификатор диалога."
      required: true
      schema:
        type: "string"
    fileId:
      name: "fileId"
      in: "path"
      description: "Идентификатор файла."
      required: true
      schema:
        type: "string"
    pageSizeParam:
      name: "pageSize"
      in: "query"
      description: "Количество сообщений в ответе."
      schema:
        default: 20
        type: "integer"
    beforeParam:
      name: "before"
      in: "query"
      description: "Идентификатор последнего сообщения."
      schema:
        type: "string"
        format: "uuid"
        example: "c491da05-277b-494f-a4dd-25b33d25b213"

  schemas:
    ConversationCreateRequest:
      type: "object"
      description: "Запрос на создание диалога с существующим приложением."
      properties:
        name:
          type: "string"
          description: "Имя диалога."
          example: "Имя диалога"
        app:
          type: "object"
          description: "Информация о приложении, с которым ведется диалог."
          properties:
            id:
              type: "string"
              description: "Идентификатор приложения."
              example: "Идентификатор приложения"
          required:
            - "id"
      required:
        - "app"
    ConversationAndAppCreateRequest:
      type: "object"
      description: "Запрос на создание диалога с новым приложением."
      properties:
        name:
          type: "string"
          description: "Имя диалога."
          example: "Имя диалога"
        app:
          $ref: "#/components/schemas/AppCreateRequest"
      required:
        - "app"
    ConversationUpdateRequest:
      type: "object"
      description: "Запрос на обновление диалога."
      properties:
        name:
          type: "string"
          description: "Новое имя диалога."
          example: "Новое имя диалога"
    ConversationResponse:
      type: "object"
      description: "Информация о диалоге."
      properties:
        id:
          type: "string"
          description: "Идентификатор диалога."
          example: "Идентификатор диалога"
        name:
          type: "string"
          description: "Имя диалога."
          example: "Имя диалога"
        app:
          $ref: "#/components/schemas/AppResponse"
        status:
          type: "string"
          description: "Статус диалога."
          example: "READY"
          enum:
            - "READY"
            - "BUILDING"
        createdAt:
          type: "number"
          description: "Дата и время создания диалога."
          example: 1700661509748
        updatedAt:
          type: "number"
          description: "Дата и время последнего обновления диалога."
          example: 1700661509748
        meta:
          $ref: "#/components/schemas/Meta"
        history:
          type: "array"
          description: "История сообщений диалога."
          items:
            $ref: "#/components/schemas/MessageResponse"
      required:
        - "id"
        - "app"
        - "status"
        - "history"
    ConversationsListResponse:
      type: "object"
      description: "Список диалогов."
      properties:
        conversations:
          type: "array"
          description: "Список диалогов."
          items:
            $ref: "#/components/schemas/ConversationResponse"
    ConversationHistoryResponse:
      type: "object"
      description: "История сообщений диалога."
      properties:
        messages:
          type: "array"
          description: "Список сообщений."
          items:
            $ref: "#/components/schemas/MessageResponse"
    MessageResponse:
      type: "object"
      description: "Информация о сообщении."
      properties:
        id:
          type: "string"
          description: "Идентификатор сообщения."
          example: "Идентификатор сообщения"
        conversationId:
          type: "string"
          description: "Идентификатор диалога."
          example: "Идентификатор диалога"
        status:
          type: "string"
          description: "Служебный статус сообщения."
          example: "success"
          enum:
            - "success"
            - "error"
            - "warn"
        type:
          type: "string"
          description: "Тип сообщения."
          example: "request"
          enum:
            - "request"
            - "response"
            - "system"
        content:
          type: "array"
          description: "Содержимое сообщения. В зависимости от типа содержимого (type) состав полей может изменяться."
          items:
            $ref: "#/components/schemas/MessagePart"
        meta:
          $ref: "#/components/schemas/Meta"
        createdAt:
          type: "number"
          description: "Дата и время создания сообщения."
          example: 1700661509748
        updatedAt:
          type: "number"
          description: "Дата и время последнего обновления сообщения."
          example: 1700661509748
      required:
        - "conversationId"
        - "status"
        - "type"
        - "content"
    MessagePart:
      oneOf:
        - $ref: "#/components/schemas/TextMessagePart"
        - $ref: "#/components/schemas/ImageMessagePart"
        - $ref: "#/components/schemas/AudioMessagePart"
        - $ref: "#/components/schemas/FileMessagePart"
        - $ref: "#/components/schemas/LinkMessagePart"
      description: "Часть сообщения"
      discriminator:
        propertyName: "type"
        mapping:
          text: "#/components/schemas/TextMessagePart"
          image: "#/components/schemas/ImageMessagePart"
          audio: "#/components/schemas/AudioMessagePart"
          file: "#/components/schemas/FileMessagePart"
          link: "#/components/schemas/LinkMessagePart"
    TextMessagePart:
      type: "object"
      description: "Часть сообщения: текст."
      properties:
        type:
          type: "string"
          example: "text"
          description: "Тип содержимого: текст."
        text:
          type: "string"
          example: "Текст сообщения"
          description: "Текст сообщения."
        localizationKey:
          type: "string"
          example: "ru"
          description: "Идентификатор ошибки."
      required:
        - "type"
        - "text"
    ImageMessagePart:
      type: "object"
      description: "Часть сообщения: изображение."
      properties:
        type:
          type: "string"
          example: "image"
          description: "Тип содержимого: изображение."
        url:
          type: "string"
          example: "https://example.com/image.png"
          description: "URL изображения."
        name:
          type: "string"
          example: "image.png"
          description: "Имя файла с изображением."
      required:
        - "type"
        - "url"
    AudioMessagePart:
      type: "object"
      description: "Часть сообщения: аудио."
      properties:
        type:
          type: "string"
          example: "audio"
          description: "Тип содержимого: аудио."
        url:
          type: "string"
          example: "https://example.com/audio.mp3"
          description: "URL аудио."
        name:
          type: "string"
          example: "audio.mp3"
          description: "Имя аудиофайла."
      required:
        - "type"
        - "url"
    FileMessagePart:
      type: "object"
      description: "Часть сообщения: файл."
      properties:
        type:
          type: "string"
          example: "file"
          description: "Тип содержимого: файл."
        url:
          type: "string"
          example: "https://example.com/file.pdf"
          description: "URL файла."
        name:
          type: "string"
          example: "file.pdf"
          description: "Имя файла."
        mimeType:
          type: "string"
          description: "Тип файла."
          example: "application/pdf"
      required:
        - "type"
        - "url"
    LinkMessagePart:
      type: "object"
      description: "Часть сообщения: ссылка."
      properties:
        type:
          type: "string"
          example: "link"
          description: "Тип содержимого: ссылка."
        url:
          type: "string"
          description: "URL."
          example: "https://example.com/"
        name:
          type: "string"
          example: "local"
          description: "Текст ссылки."
      required:
        - "type"
        - "url"
    AppCreateRequest:
      type: "object"
      description: "Запрос на создание приложения."
      properties:
        name:
          type: "string"
          description: "Имя приложения."
          example: "Имя приложения"
        description:
          type: "string"
          description: "Описание приложения."
          example: "Описание приложения"
        template:
          type: "string"
          description: "Идентификатор шаблона приложения."
          example: "Идентификатор шаблона приложения."
        params:
          type: "object"
          description: "Параметры приложения."
          properties: { }
      required:
        - "template"
    AppUpdateRequest:
      type: "object"
      description: "Запрос на обновление приложения."
      properties:
        name:
          type: "string"
          description: "Имя приложения."
          example: "Имя приложения"
    AppResponse:
      type: "object"
      description: "Информация о приложении."
      required:
        - "id"
        - "status"
        - "template"
        - "params"
      properties:
        id:
          type: "string"
          description: "Идентификатор приложения."
          example: "Идентификатор приложения"
        name:
          type: "string"
          description: "Имя приложения."
          example: "Имя приложения"
        description:
          type: "string"
          description: "Описание приложения."
          example: "Описание приложения"
        status:
          type: "string"
          description: "Статус приложения."
          example: "READY"
          enum:
            - "READY"
            - "BUILDING"
            - "FAILED"
        favorite:
          type: "boolean"
          description: "Показывает, является ли приложение избранным."
          example: true
        template:
          type: "string"
          description: "Идентификатор шаблона приложения."
          example: "Идентификатор шаблона приложения"
        params:
          type: "object"
          description: "Параметры приложения."
          properties: { }
        meta:
          $ref: "#/components/schemas/Meta"
        createdAt:
          type: "number"
          description: "Дата и время создания приложения."
          example: 1700661509748
        updatedAt:
          type: "number"
          description: "Дата и время последнего изменения приложения."
          example: 1700661509748
    AppsListResponse:
      type: "object"
      description: "Информация о приложениях."
      required:
        - "apps"
      properties:
        apps:
          type: "array"
          description: "Список приложений."
          items:
            $ref: "#/components/schemas/AppResponse"
    TemplateResponse:
      type: "object"
      description: "Информация о шаблоне приложений."
      required:
        - "categories"
        - "info"
        - "params"
      properties:
        categories:
          type: "array"
          description: "Категории каталога, к которым относится шаблон приложения."
          example:
            - "content"
            - "data"
          items:
            type: "string"
        label:
          type: "string"
          description: "Название шаблона приложения."
          example: "Название шаблона приложения"
        info:
          type: "object"
          description: "Дополнительная информация о шаблоне приложения."
          required:
            - "icon"
            - "title"
            - "description"
            - "prompt"
          properties:
            icon:
              type: "string"
              description: "Иконка приложения."
              example: "📧"
            title:
              type: "string"
              description: "Название приложения."
              example: "Деловое письмо"
            description:
              type: "string"
              description: "Описание приложения."
              example: "Составит деловое письмо или\_ответ на\_него на\_указанную\
                \ тему"
            prompt:
              type: "string"
              description: "Промт."
              example: "Текст промта"
        params:
          type: "object"
          description: "Параметры шаблона приложения."
          properties: { }
        autoCreate:
          type: "boolean"
          description: "Создавать приложение автоматически."
          example: false
        requiredFeature:
          type: "string"
          description: "Необходимые фичи."
          example: "copilot_access"
        startRequest:
          type: "string"
          description: "Стартовый запрос."
          example: "Текст стартового запроса."
    FileResponse:
      type: "object"
      description: "Информация о файле."
      required:
        - "id"
        - "url"
      properties:
        id:
          type: "string"
          description: "Идентификатор файла."
          example: "Идентификатор файла"
        name:
          type: "string"
          description: "Имя файла."
          example: "Имя файла"
        url:
          type: "string"
          description: "URL файла."
          example: "https://example.com/file.pdf"
        contentType:
          type: "string"
          description: "Тип файла."
          example: "application/pdf"
        contentSize:
          type: "number"
          description: "Размер файла в байтах."
          example: 1024
        createdAt:
          type: "number"
          description: "Дата и время загрузки файла на сервер."
          example: 1700661509748
        meta:
          $ref: "#/components/schemas/Meta"
    TemplatesListResponse:
      type: "object"
      description: "Информация о шаблонах приложений."
      required:
        - "templates"
      properties:
        templates:
          type: "object"
          additionalProperties:
            $ref: "#/components/schemas/TemplateResponse"
    Meta:
      type: "object"
      description: "Дополнительная служебная информация."
      properties: { }
