Vector DB as a Service API Spec

swagger_spec.yaml

swagger: '2.0'
info:
  title: Vector Stores and Text Management API
  version: '1.0.0'
host: 'your-api.com'
schemes:
  - https
basePath: /api/v1
produces:
  - application/json
securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
  api_key:
    type: apiKey
    name: api_key
    in: header
paths:
  /vector-stores/:
    post:
      tags: 
        - Vector Stores Management
      summary: Create a Vector Store
      description: This API will create a new Vector Store for the supplied user ID.
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
      responses:
        '200':
          description: Successfully created a new Vector Store
          schema:
            type: object
            properties:
              id:
                type: string
              api_key:
                type: string
                x-nullable: true
              message:
                type: string
      security:
        - Bearer: []
    get:
      tags: 
        - Vector Stores Management
      summary: List all Vector Stores of a user
      responses:
        '200':
          description: Successful operation
          schema:
            type: object
            properties:
              stores:
                type: array
                items:
                  $ref: '#/definitions/Store'
              message:
                type: string
      security:
        - Bearer: []
  /vector-stores/{store_id}:
    parameters:
      - name: store_id
        in: path
        required: true
        type: string
    patch:
      tags: 
        - Vector Stores Management
      summary: Update a specific Vector Store
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
      responses:
        '200':
          description: Successfully updated the Vector Store
          schema:
            type: object
            properties:
              message:
                type: string
      security:
        - Bearer: []
    delete:
      tags: 
        - Vector Stores Management
      summary: Delete a specific Vector Store
      responses:
        '200':
          description: Successfully deleted the Vector Store
          schema:
            type: object
            properties:
              message:
                type: string
      security:
        - Bearer: []
    get:
      tags: 
        - Vector Stores Management
      summary: View a specific Vector Store
      description: Ideally, we might not want to return the API key in the response for security reasons. Instead, we could return the store ID and then the user could make a separate call to get or create the API key if needed.
      responses:
        '200':
          description: Successfully retrieved the Vector Store
          schema:
            $ref: '#/definitions/Store'
      security:
        - Bearer: []
  /vector-stores/{store_id}/rotate-api-key/:
    put:
      tags: 
        - Vector Stores Management
      summary: Update/Rotate API Key
      parameters:
        - name: store_id
          in: path
          required: true
          type: string
      responses:
        '200':
          description: Successfully updated the API key
          schema:
            type: object
            properties:
              api_key:
                type: string
              message:
                type: string
      security:
        - Bearer: []
  /vector-stores/documents:
    post:
      tags: 
        - Text Management
      summary: Upload Documents
      description: This API allows users to upload text and files simultaneously. If users provide one text and n files, it results in n+1 documents being created. Users can optionally provide custom names for files; otherwise, default names will be assigned.
      consumes:
        - multipart/form-data
      parameters:
        - in: header
          name: api_key
          required: true
          type: string
        - in: formData
          name: names
          type: array
          items:
            type: string
          description: Names for the uploaded documents
        - in: formData
          name: texts
          type: array
          items:
            type: string
          description: Text contents of the documents
        - in: formData
          name: file_1
          type: file
          description: File to be uploaded
        - in: formData
          name: file_2
          type: file
          description: File to be uploaded
        - in: formData
          name: file_3
          type: file
          description: File to be uploaded
      responses:
        '200':
          description: Successfully uploaded documents
          schema:
            type: object
            properties:
              message:
                type: string
      security:
        - api_key: []
    get:
      tags: 
        - Text Management
      summary: List all Documents
      parameters:
        - in: header
          name: api_key
          required: true
          type: string
        - name: page
          in: query
          required: false
          type: integer
          default: 1
          description: Page number
        - name: size
          in: query
          required: false
          type: integer
          default: 10
          description: Number of records to fetch per page
      responses:
        '200':
          description: Successfully listed all documents
          schema:
            type: object
            properties:
              results:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    content:
                      type: string
              total_pages:
                type: integer
              current_page:
                type: integer
      security:
        - api_key: []
  /vector-stores/query:
    post:
      tags: 
        - Text Management
      summary: Search
      description: This API conducts a search based on the 'query_text' and returns the top 'k' results.
      parameters:
        - in: header
          name: api_key
          required: true
          type: string
        - in: body
          name: body
          required: true
          schema:
            type: object
            properties:
              query_text:
                type: string
              top_k:
                type: integer
              next_chunks:
                type: string
              prev_chunks:
                type: string
      responses:
        '200':
          description: Successfully searched texts
          schema:
            type: object
            properties:
              matched_chunks:
                type: array
                items:
                  type: object
                  properties:
                    chunk_id:
                      type: string
                    document:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        type:
                          type: string
                        path:
                          type: string
                        url:
                          type: string
                        size:
                          type: integer
                        created_time:
                          type: string
                          format: date-time
                        modified_time:
                          type: string
                          format: date-time
                        indexed_on:
                          type: string
                          format: date-time
                    matched_content:
                      type: string
      security:
        - api_key: []
  /vector-stores/documents/{document_id}:
    parameters:
      - name: document_id
        in: path
        required: true
        type: string
    get:
      tags: 
        - Text Management
      summary: Get a Document
      parameters:
        - in: header
          name: api_key
          required: true
          type: string
      responses:
        '200':
          description: Successfully retrieved the document
          schema:
            type: object
            properties:
              id:
                type: string
              content:
                type: string
      security:
        - api_key: []
    delete:
      tags: 
        - Text Management
      summary: Delete a Document
      parameters:
        - in: header
          name: api_key
          required: true
          type: string
      responses:
        '200':
          description: Successfully deleted the document
          schema:
            type: object
            properties:
              message:
                type: string
      security:
        - api_key: []
definitions:
  Store:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      description:
        type: string
      api_key:
        type: string
        x-nullable: true