openapi: 3.1.0
info:
  title: Peeloff Client API
  version: 0.0.0-release-d4f2462
  license:
    name: Copyright © 2024 오프너드. All right reserved.
    url: https://dev.opnd.io/LICENSE
servers:
  - url: https://api.peeloff.app.dev.opnd.io/api/v1
    description: 서버
tags:
  - name: Global
    x-displayName: Global
  - name: Profiles
    x-displayName: Profiles
  - name: Vectors
    x-displayName: Vectors
paths:
  /health:
    get:
      security: []
      tags:
        - Global
      summary: Health 정보 획득
      operationId: GetHealth
      responses:
        '200':
          description: Health 정보 획득
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '500':
          description: Health 정보 획득 오류
          content:
            application/json:
              examples:
                내부 서버 에러.:
                  value:
                    code: INTERNAL_SERVER_ERROR
                    message: 내부 서버 에러.
              schema:
                $ref: '#/components/schemas/InternalServerError'
  /profiles:
    get:
      tags:
        - Profiles
      security:
        - ApiKeyAuth: []
      operationId: GetProfileList
      summary: 프로파일
      description: 프로파일
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/SizeParam'
        - $ref: '#/components/parameters/ProfileSortParam'
      responses:
        '200':
          description: 요청이 성공적으로 생성되었습니다.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginationResponse'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ProfileList'
  /vectors/requests/file:
    post:
      tags:
        - Vectors
      security:
        - ApiKeyAuth: []
      operationId: RequestFileToVectors
      summary: 파일 업로드 후 요청 ID 반환
      description: 파일을 업로드하고 요청 추적을 위한 ID를 반환합니다.
      parameters:
        - name: vectorRole
          in: query
          description: 벡터 접근 역할, 단순 문자열 지정 가능
          required: false
          schema:
            type: array
            items:
              type: string
              pattern: ^[a-zA-Z0-9_-]+$
              minLength: 10
              maxLength: 64
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: 업로드할 파일, 현재 PDF만 지원
      responses:
        '200':
          description: 요청이 성공적으로 생성되었습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    description: 생성된 요청 ID
  /vectors/requests/text:
    post:
      tags:
        - Vectors
      security:
        - ApiKeyAuth: []
      operationId: RequestTextToVectors
      summary: 텍스트 업로드 후 요청 ID 반환
      description: 텍스트를 전송하고 요청 추적을 위한 ID를 반환합니다.
      parameters:
        - name: vectorRole
          in: query
          description: 벡터 접근 역할, 단순 문자열 지정 가능
          required: false
          schema:
            type: array
            items:
              type: string
              pattern: ^[a-zA-Z0-9_-]+$
              minLength: 10
              maxLength: 64
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        '200':
          description: 요청이 성공적으로 생성되었습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    description: 생성된 요청 ID
  /vectors/requests/{id}:
    get:
      tags:
        - Vectors
      security:
        - ApiKeyAuth: []
      operationId: GetVectorsRequest
      summary: 요청 상태 조회
      description: 특정 요청 ID를 기준으로 요청의 현재 상태 및 최종 결과를 반환합니다.
      parameters:
        - name: id
          in: path
          description: 요청 ID
          required: true
          schema:
            type: string
            format: uuid
            example: 7058a0ce-d1ce-4ca4-8765-b1fad9082110
      responses:
        '200':
          description: 요청 상태 및 결과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestStatus'
  /vectors/requests:
    get:
      tags:
        - Vectors
      security:
        - ApiKeyAuth: []
      operationId: ListVectorsRequests
      summary: 요청 상태 및 리스트 조회
      description: 요청의 현재 상태 및 최종 결과를 반환합니다.
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/SizeParam'
        - $ref: '#/components/parameters/VectorSortParam'
        - name: status
          in: query
          description: 요청 상태로 필터링
          required: false
          schema:
            type: string
            enum:
              - waiting
              - processing
              - completed
              - failed
              - canceled
      responses:
        '200':
          description: 요청 상태 리스트
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginationResponse'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/RequestStatus'
    delete:
      tags:
        - Vectors
      security:
        - ApiKeyAuth: []
      operationId: DeleteVectorsRequest
      summary: 요청 취소
      description: 특정 요청 ID를 기준으로 요청을 취소합니다.
      parameters:
        - name: id
          in: query
          description: 취소할 요청 ID
          required: true
          schema:
            type: array
            items:
              type: string
              format: uuid
              example: 7058a0ce-d1ce-4ca4-8765-b1fad9082110
      responses:
        '200':
          description: 요청이 성공적으로 취소되었습니다.
  /vectors/requests/{id}/download:
    get:
      tags:
        - Vectors
      security:
        - ApiKeyAuth: []
      operationId: DownloadVectorsRequestFile
      summary: 요청 파일 다운로드
      description: 특정 요청에 업로드된 파일을 다운로드합니다.
      parameters:
        - name: id
          in: path
          description: 요청 ID
          required: true
          schema:
            type: string
            format: uuid
            example: 7058a0ce-d1ce-4ca4-8765-b1fad9082110
        - name: fileType
          in: query
          description: 다운로드 타입
          required: true
          schema:
            type: string
            enum:
              - original
              - text
      responses:
        '200':
          description: 요청 파일 다운로드 성공
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /vectors/query:
    post:
      tags:
        - Vectors
      security:
        - ApiKeyAuth: []
      operationId: RequestVectorQuery
      summary: 벡터 쿼리 요청
      description: 벡터 데이터를 업로드하고 결과를 반환받습니다.
      parameters:
        - name: profileId
          in: query
          description: profile ID
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: vectorRole
          in: query
          description: 벡터 접근 역할, 단순 문자열 지정 가능
          required: false
          schema:
            type: array
            items:
              type: string
              pattern: ^[a-zA-Z0-9_-]+$
              minLength: 10
              maxLength: 64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vector:
                  description: 업로드할 벡터 데이터
                  type: array
                  items:
                    type: number
                    description: 업로드할 벡터 데이터
                metadata:
                  $ref: '#/components/schemas/StringToStringMap'
            examples:
              simple:
                summary: 간단한 예
                value:
                  vector:
                    - 1
                    - 2
                    - 3
                  metadata:
                    FileName: example.pdf
      responses:
        '200':
          description: 쿼리 결과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '404':
          description: 벡터 데이터가 존재하지 않습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
components:
  schemas:
    HealthResponse:
      type: object
    InternalServerError:
      title: InternalServerError
      description: 서버 내부 오류가 발생한 경우
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: INTERNAL_SERVER_ERROR
        message:
          type: string
          example: 서버 내부 오류가 발생했습니다.
    PageParam:
      type: integer
      format: int32
      minimum: 1
      description: 페이지 번호 (Default= 1)
      example: 1
    SizeParam:
      type: integer
      format: int32
      minimum: 1
      description: 페이지당 아이템 수 페이지 번호 (Default= 20)
      example: 20
    SortParam:
      type: array
      items:
        type: string
      description: 정렬 순서.
      example:
        - createdAt+ASC
        - modifiedAt+DESC
    PaginationResponse:
      x-parent: abstract
      type: object
      required:
        - page
        - pageSize
      properties:
        totalPages:
          type: integer
          format: int32
          description: Total pages
        totalItems:
          type: integer
          format: int64
          description: Total elements
        page:
          type: integer
          format: int32
          description: Current page number
        pageSize:
          type: integer
          format: int32
          description: Number of items in one page
    ProfileList:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 7058a0ce-d1ce-4ca4-8765-b1fad9082110
        name:
          type: string
        note:
          type: string
    RequestStatus:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: 요청 ID
        status:
          type: string
          enum:
            - waiting
            - processing
            - completed
            - failed
            - canceled
          description: 요청 상태
        result:
          type: object
          description: 최종 결과(파일 또는 JSON 데이터)
        createdAt:
          type: string
          format: date-time
          description: 요청 생성 시간
        startedAt:
          type: string
          format: date-time
          description: 수행 시작 시간
        completedAt:
          type: string
          format: date-time
          description: 수행 완료 시간
    StringToStringMap:
      type: object
      additionalProperties:
        type: string
    QueryResult:
      type: object
      properties:
        vectors:
          type: array
          items:
            type: object
            properties:
              vector:
                type: array
                items:
                  type: number
              metadata:
                type: object
    NotFoundError:
      title: NotFoundError
      description: 요청된 리소스를 찾을 수 없는 경우
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: NOT_FOUND
        message:
          type: string
          example: 요청된 리소스를 찾을 수 없습니다.
  parameters:
    PageParam:
      in: query
      name: page
      schema:
        $ref: '#/components/schemas/PageParam'
    SizeParam:
      in: query
      name: size
      schema:
        $ref: '#/components/schemas/SizeParam'
    ProfileSortParam:
      in: query
      name: sort
      schema:
        $ref: '#/components/schemas/SortParam'
      description: 정렬 순서. | ex) url?sort=createdAt+ASC&sort=name+DESC
      style: form
      explode: true
      examples:
        single:
          summary: Single sort
          value:
            - id+DESC
        multiple:
          summary: Multiple sorts
          value:
            - id+DESC
            - name+DESC
    VectorSortParam:
      in: query
      name: sort
      schema:
        $ref: '#/components/schemas/SortParam'
      description: 정렬 순서. | ex) url?sort=createdAt+ASC&sort=status+DESC
      style: form
      explode: true
      examples:
        single:
          summary: Single sort
          value:
            - id+DESC
        multiple:
          summary: Multiple sorts
          value:
            - id+DESC
            - status+DESC
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API 키는 특정 Role에 대한 키 입니다.
x-tagGroups:
  - name: 기본 API
    tags:
      - Global
  - name: 프로파일 API
    tags:
      - Profiles
  - name: 백터 API
    tags:
      - Vectors
security:
  - ApiKeyAuth: []