openapi: 3.0.3
info:
  title: PropulsionAI API
  description: API for interacting with PropulsionAI models and tools.
  version: 1.0.0
  contact:
    name: PropulsionAI Support Team
    email: dev-support@propulsionhq.com
servers:
  - url: https://api.propulsionhq.com/api/v2
    description: PropulsionAI Production Server

tags:
  - name: Chat
    description: Given a list of messages comprising a conversation, the deployment will return a response.
  - name: Dataset
    description: Retrieve and manage datasets.
  - name: Knowledgebase
    description: Create and manage knowledgebases.

paths:
  /knowledgebase:
    post:
      summary: Creates a new knowledgebase.
      security:
        - bearerAuth: []
      tags:
        - Knowledgebase
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgebaseCreateRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgebaseCreateResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
  /knowledgebase/{knowledgebase_code}/file:
    post:
      summary: Uploads a file to a knowledgebase.
      security:
        - bearerAuth: []
      tags:
        - Knowledgebase
      parameters:
        - in: path
          name: knowledgebase_code
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/KnowledgebaseFileUploadRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgebaseFileUploadResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
  /knowledgebase/{knowledgebase_code}/item:
    post:
      summary: Upload content to a knowledgebase.
      security:
        - bearerAuth: []
      tags:
        - Knowledgebase
      parameters:
        - in: path
          name: knowledgebase_code
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgebaseItemRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgebaseItemResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
  /knowledgebase/{knowledgebase_code}/file/{file_id}:
    delete:
      summary: Deletes a file from a knowledgebase.
      security:
        - bearerAuth: []
      tags:
        - Knowledgebase
      parameters:
        - in: path
          name: knowledgebase_code
          required: true
          schema:
            type: string
        - in: path
          name: file_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgebaseFileDeleteResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
  /dataset:
    post:
      summary: Creates a new dataset.
      security:
        - bearerAuth: []
      tags:
        - Dataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetCreateRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetCreateResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
  /dataset/item:
    post:
      summary: Creates a new item in a dataset.
      security:
        - bearerAuth: []
      tags:
        - Dataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetItemCreateRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetItemCreateResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
  /chat/completions:
    post:
      summary: Call a deployment endpoint with specified tools and messages.
      security:
        - bearerAuth: []
      tags:
        - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Successful response
          headers:
            X-TASK-ID:
              schema:
                type: string
            X-POLLING-ID:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  schemas:
    KnowledgebaseFileUploadRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
      required:
        - file
    
    KnowledgebaseItemRequest:
      type: object
      properties:
        source:
          type: string
          description: You should use this field to specify the source of the content like url, filename, etc. This will be used for citation purposes.
        metadata:
          type: object
          description: You can use this field to specify any metadata associated with the content.
        content:
          type: string
          description: The content that you want to upload to the knowledgebase.
      required:
        - source
        - content

    KnowledgebaseCreateRequest:
      type: object
      properties:
        tags:
          type: string
        name:
          type: string
        description:
          type: string
      required:
        - name
        - tags
    
    KnowledgebaseFileDeleteResponse:
      type: object
      properties:
        message:
          type: string
        id:
          type: string
    
    KnowledgebaseFileUploadResponse:
      type: object
      properties:
        message:
          type: string
        id:
          type: string
    
    KnowledgebaseItemResponse:
      type: object
      properties:
        message:
          type: string
        id:
          type: string
    
    KnowledgebaseCreateResponse:
      type: object
      properties:
        message:
          type: string
        code:
          type: string

    DatasetItemCreateResponse:
      type: object
      properties:
        message:
          type: string
        id:
          type: string

    DatasetItemDataObject:
      type: object
      properties:
        query:
          type: string
          nullable: true
        tools:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ChatCompletionTool'
        chosen:
          type: string
          nullable: true
        images:
          type: string
          nullable: true
        prompt:
          type: string
          nullable: true
        system:
          type: string
          nullable: true
        history:
          type: array
          nullable: true
          items:
            type: array
            items:
              type: string
        kto_tag:
          type: string
          nullable: true
        messages:
          type: array
          items:
            $ref: '#/components/schemas/RequestMessage'
        rejected:
          type: string
          nullable: true
        response:
          type: string
          nullable: true
        
    DatasetItemCreateRequest:
      type: object
      properties:
        dataset_id:
          type: integer
        data:
          $ref: '#/components/schemas/DatasetItemDataObject'
      required:
        - dataset_id
        - data

    DatasetCreateRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        settings:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
      required:
        - name

    DatasetCreateResponse:
      type: object
      properties:
        message:
          type: string
        id:
          type: integer
        dataset:
          $ref: '#/components/schemas/DatasetCreateResponseObject'
          
    DatasetCreateResponseObject:
      type: object
      properties:
        id:
          type: integer
        project_id:
          type: integer
        name:
          type: string
        description:
          type: string
        settings:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        created:
          type: integer
        updated:
          type: integer

    ChatRequest:
      type: object
      properties:
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionTool'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/RequestMessage'
        deployment:
          type: string
        stream:
          type: boolean
          default: false
        temperature:
          $ref: '#/components/schemas/Temperature'
        top_p:
          $ref: '#/components/schemas/TopP'
        n:
          $ref: '#/components/schemas/N'
        max_tokens:
          type: integer
        tool_choice:
          $ref: '#/components/schemas/ChatCompletionToolChoiceOption'
        knowledgebases:
          type: array
          items:
            type: string
        task_id:
          type: string
      required:
        - messages
        - deployment

    RequestMessage:
      type: object
      properties:
        role:
          type: string
          enum: [system, user, assistant, tool]
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum: [text, image_url]
                  text:
                    type: string
                  image_url:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
              required:
                - type
    
    ResponseMessage:
      type: object
      properties:
        role:
          type: string
          enum: [system, user, assistant, tool]
        content:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'

    ChatCompletionTool:
      type: object
      properties:
        type:
          type: string
          enum: ['function']
        function:
          $ref: '#/components/schemas/FunctionRequestObject'
      required:
        - type
        - function

    FunctionRequestObject:
      type: object
      properties:
        description:
          type: string
        name:
          type: string
          pattern: ^[a-zA-Z0-9_-]{1,64}$
        parameters:
          type: object
          additionalProperties: true
      required:
        - name
    
    FunctionResponseObject:
      type: object
      properties:
        description:
          type: string
        name:
          type: string
          pattern: ^[a-zA-Z0-9_-]{1,64}$
        arguments:
          type: object
          additionalProperties: true
      required:
        - name

    ChatCompletionToolChoiceOption:
      oneOf:
        - type: string
          enum: [none, auto, required]
        - $ref: '#/components/schemas/ChatCompletionNamedToolChoice'

    ChatCompletionNamedToolChoice:
      type: object
      properties:
        type:
          type: string
          enum: ['function']
        function:
          $ref: '#/components/schemas/FunctionRequestObject'
      required:
        - type
        - function

    Temperature:
      type: number
      minimum: 0
      maximum: 1
      default: 0.4

    TopP:
      type: number
      minimum: 0
      maximum: 1
      default: 0.5
      description: Probability threshold for token selection in text generation, controlling output randomness.

    N:
      type: integer
      minimum: 1
      maximum: 128
      default: 1

    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
        model:
          type: string
        task_id:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        usage:
          $ref: '#/components/schemas/Usage'

    Choice:
      type: object
      properties:
        index:
          type: integer
        message:
          $ref: '#/components/schemas/ResponseMessage'

    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer

    ToolCall:
      type: object
      properties:
        type:
          type: string
          enum: ['function']
        function:
          $ref: '#/components/schemas/FunctionResponseObject'

security:
  - bearerAuth: []