openapi: 3.0.3
info:
  title: IONOS Cloud - AI Model Hub API
  version: 1.0.0
  description: |
    # IONOS Cloud AI Model Hub API
    
    An API to interact with various AI models running on the IONOS Cloud.
    
    **⚠️ Important Notice: Scheduled to Retire on May 5, 2026**
    
    The native `/predictions` endpoint is scheduled to retire on **May 5, 2026**.
    
    - **For text and image generation use cases**: Please switch to using the 
      OpenAI-compatible API endpoints.
    - **For Retrieval Augmented Generation (RAG) scenarios**: Please continue to use 
      the native API endpoints (`/collections`, `/documents`, and `/query`).
    
    For details on how to migrate your existing implementations, see the 
    [Migration Guide from Predictions Endpoint](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/migration-guide).
    
    This migration provides straightforward integration with OpenAI-compatible tools 
    and SDKs and a more standardized developer experience.
  contact:
    name: IONOS Cloud Support
    url: https://docs.ionos.com/support/general-information/contact-information
    email: support@cloud.ionos.com
tags:
  - name: Foundation Models
    description: Browse and call foundation models.
  - name: Document Collections
    description: Manage your custom document collections in a Vector Dababase.
externalDocs:
  description: IONOS Cloud - AI Model Hub - Documentation
  url: https://docs.ionos.com/cloud/ai/ai-model-hub

servers:
  - url: https://inference.de-txl.ionos.com
    description: Berlin
security:
  - tokenAuth: []

paths:
  /models:
    get:
      operationId: modelsGet
      deprecated: true
      x-deprecation-date: "2026-05-05"
      summary: Retrieve available AI models
      description: |
        **Deprecated** – This endpoint will be removed on **2026-05-05**.
        Please refer to the [Migration Guide](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/migration-guide) 
        for instructions on how to migrate.
        
        Retreieve the list of AI models running on the IONOS AI Model Hub.
        The model identifier is then used with the /predictions endpoint.
      tags:
        - Foundation Models
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelsCollection"
              example:
                id: "9fa7d335-209c-5a1e-a8b2-686772fe7a33"
                type: collection
                href: "<RESOURCE-URL>"
                items:
                  - id: "4b71d0fe-d992-463e-82a1-de337d88ac2d"
                    type: model
                    metadata:
                      lastModifiedDate: 2023-07-21T15:52:53Z
                      createdDate: 2023-07-21T15:52:53Z
                    properties:
                      name: "bloom-7b"
                      description: "BLOOM 7B model"
                      category: "text/nlp"
                  - id: "3a62d0fe-d992-463e-82a1-de337d88ac42"
                    type: model
                    metadata:
                      lastModifiedDate: 2022-08-21T15:52:53Z
                      createdDate: 2022-08-21T15:52:53Z
                    properties:
                      name: "othermodel-13b"
                      description: "Other model 13B"
                      category: "text/nlp"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /models/{modelId}/predictions:
    post:
      operationId: modelsPredictionsPost
      deprecated: true
      x-deprecation-date: "2026-05-05"
      summary: Send a request to the selected AI model
      description: |
        **Deprecated** – This endpoint will be removed on **2026-05-05**.
        Please refer to the [Migration Guide](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/migration-guide) 
        for instructions on how to migrate.
        
        Send a request to the AI model and receive the result. The endpoint is 
        synchronous and will return as soon as the model generates the full reply.
      parameters:
        - name: modelId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the model.
      requestBody:
        description: Prediction input
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModelsPredictionBody"
            example:
              type: prediction
              properties:
                input: Please provide some sugestion names for my business. I own a flower shop in Berlin.
                collectionId: "550e8400-e29b-41d4-a716-446655440000"
                collectionQuery: "What is a domain?"
                options:
                  max_length: "300"
                  temperature: "0.01"
      tags:
        - Foundation Models
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelsPrediction"
              example:
                type: prediction
                metadata:
                  lastModifiedDate: 2022-08-21T15:52:53Z
                  createdDate: 2022-08-21T15:52:53Z
                  duration: 0.01
                properties:
                  input: Please provide some sugestion names for my business. I own a flower shop in Berlin.
                  options:
                    max_length: "300"
                    temperature: "0.01"
                  output: The ML model said something smart
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /collections:
    post:
      operationId: collectionsPost
      summary: Create a new collection
      description: Create a new, empty document collection for storing documents
      requestBody:
        description: Collection input
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionCreate"
            examples:
              collectionCreateExample:
                $ref: "#/components/examples/CollectionCreateRequestBodyExample"
      tags:
        - Document Collections
      responses:
        "201":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collection"
              examples:
                collectionResponseBodyExample:
                  $ref: "#/components/examples/CollectionResponseBodyExample"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
    get:
      operationId: collectionsGet
      summary: Get all collections
      description: Retrieve all stored document collections
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
          required: false
          description: The maximum number of collections to return - defaults to 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          required: false
          description: The offset to start from - defaults to 0
      tags:
        - Document Collections
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionsList"
              examples:
                collectionListExample:
                  $ref: "#/components/examples/CollectionListResponseBodyExample"
                
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /collections/{collectionId}:
    get:
      operationId: collectionsFindById
      summary: Get collection
      description: Returns the properties and metadata for the document collection
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
      tags:
        - Document Collections
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collection"
              examples:
                collectionResponseBodyExample:
                  $ref: "#/components/examples/CollectionResponseBodyExample"
                
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      operationId: collectionsPut
      summary: Update an existing collection
      description: Update collection details and metadata. No modification is done on the documents.
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
      requestBody:
        description: Collection input
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionUpdate"
            examples:
              collectionUpdateRequestBodyExample:
                $ref: "#/components/examples/CollectionUpdateRequestBodyExample"
      tags:
        - Document Collections
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collection"
              examples:
                collectionUpdateResponseBodyExample:
                  $ref: "#/components/examples/CollectionUpdateResponseBodyExample"
                
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"    
    delete:
      operationId: collectionsDelete
      summary: Delete a collection and its documents
      description: Delete a collection and all documents stored in it
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
      tags:
        - Document Collections
      responses:
        "204":
          description: Successful operation.
        "404":
          $ref: "#/components/responses/NotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
  /collections/{collectionId}/documents:
    get:
      operationId: collectionsDocumentsGet
      summary: Get the list of documents stored in the collection
      description: Get the list of documents stored in the collection
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
          required: false
          description: The maximum number of documents to return - defaults to 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          required: false
          description: The offset to start from - defaults to 0
      tags:
        - Document Collections
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionDocumentsList"
              examples:
                documentListExample:
                  $ref: "#/components/examples/CollectionDocumentsListResponseBodyExample"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      operationId: collectionsDocumentsPut
      summary: Add documents to the collection
      description: |
        Add documents to the collection.
      requestBody:
        description: Document input
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionDocumentsListCreate"
            examples:
              requestDocumentBodyExample:
                $ref: "#/components/examples/DocumentsAddRequestBodyExample"             
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
      tags:
        - Document Collections
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionDocumentsList"
              examples:
                responseDocumentsBodyExample:
                  $ref: "#/components/examples/DocumentsAddResponseBodyExample"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      operationId: collectionsDocumentsDelete
      summary: Prune all documents in a collection
      description: Delete all documents from a collection, thus pruning it
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
      tags:
        - Document Collections
      responses:
        "200":
          description: Successful operation.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
  /collections/{collectionId}/documents/{documentId}:
    get:
      operationId: collectionsDocumentsFindById
      summary: Get document details
      description: Retreieve document's details.
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
        - name: documentId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the document.
      tags:
        - Document Collections
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Document"
              examples:
                documentResponseBodyExample:
                  $ref: "#/components/examples/DocumentResponseBodyExample"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      operationId: collectionsDocumentUpdate
      summary: Update a document
      description: Replaces the existing document identified by documentId with the contents of the request payload
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
        - name: documentId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the document.
      tags:
        - Document Collections
      requestBody:
        description: Document input
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Document"
            example:
              type: document
              properties:
                name: Lorem Doc 1
                description: This is a document about lorem ipsum
                contentType: text/plain
                content: "<DOCUMENT-CONTENT-BASE64-ENCODED>"
                labels:
                  topic: linux
                  subtopic: networking
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Document"
              examples:
                documentExample:
                  $ref: "#/components/examples/DocumentResponseBodyExample"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      operationId: collectionsDocumentDelete
      summary: Delete a document
      description: Remove a document from the collection
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
        - name: documentId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the document.
      tags:
        - Document Collections
      responses:
        "200":
          description: Successful operation.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
  /collections/{collectionId}/documents/{documentId}/chunks:
    get:
      operationId: collectionsDocumentsChunksGet
      summary: Get document chunks details
      description: Retrieve existing chunks for the document with documentId.
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
        - name: documentId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the document.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 10000
          required: false
          description: The maximum number of documents to return - defaults to 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 1000000
          required: false
          description: The offset to start from - defaults to 0
      tags:
        - Document Collections
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionDocumentsList"
              examples:
                responseBodyExample:
                  $ref: "#/components/examples/CollectionDocumentsListResponseBodyExample"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /collections/{collectionId}/query:
    post:
      operationId: collectionsQueryPost
      summary: Query a collection / search for related content
      description: |
        Query a collection / search for related content.
        This endpoint is used to return relevant documents from a collection.
      parameters:
        - name: collectionId
          in: path
          schema:
            type: string
          required: true
          description: The ID of the collection.
        - in: query
          name: labels
          schema:
            type: object
            additionalProperties:
              type: array
              items:
                type: string
              description: An array of values for the dynamic label.
          style: deepObject
          explode: true
          description: >
            A map of dynamic label keys to their array of string values.
            Example: /collections/{collectionId}/query?labels[category][0]=cat1&labels[category][1]=cat2&labels[status][0]=active
      requestBody:
        description: Query string and parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryRequest"
            example:
              limit: 5
              query: "What is Managed Kubernetes?"
      tags:
        - Document Collections
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryResult"
              example:
                type: result
                metadata:
                  lastModifiedDate: 2022-08-21T15:52:53Z
                  createdDate: 2022-08-21T15:52:53Z
                  duration: 0.01
                properties:
                  matches:
                    - document:
                        id: "9fa7d335-209c-5a1e-a8b2-686772fe7a33"
                        type: document
                        href: "<RESOURCE-URL>"
                        properties:
                          contentType: text/plain
                          name: Lorem doc 1
                          content: "<DOCUMENT-CONTENT-BASE64-ENCODED>"
                        metadata:
                          lastModifiedDate: "2022-07-19T15:52:53Z"
                          createdDate: "2022-07-19T15:52:53Z"
                      score: 0.99
                    - document:
                        id: "7ea7d335-209c-5a1e-a8b2-686772fe7a22"
                        type: document
                        href: "<RESOURCE-URL>"
                        properties:
                          contentType: text/plain
                          name: Lorem doc 2
                          content: "<DOCUMENT-CONTENT-BASE64-ENCODED>"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
components:
  schemas:
    Model:
      deprecated: true
      x-deprecation-date: "2026-05-05"
      type: object
      description: |
        **Deprecated** – This schema will be removed on **2026-05-05**.
        Please refer to the [Migration Guide](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/migration-guide) 
        for instructions on how to migrate.
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier of the model.
          example: 4b71d0fe-d992-463e-82a1-de337d88ac2d
        type:
          type: string
          readOnly: true
          description: Entity type.
          example: model
        properties:
          $ref: "#/components/schemas/ModelProperties"
        metadata:
          $ref: "#/components/schemas/Metadata"
      required:
        - id
        - type
        - metadata
        - properties

    ModelProperties:
      deprecated: true
      x-deprecation-date: "2026-05-05"
      type: object
      description: |
        **Deprecated** – This schema will be removed on **2026-05-05**.
        Please refer to the [Migration Guide](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/migration-guide) 
        for instructions on how to migrate.
      properties:
        name:
          type: string
          description: The name of the model.
          example: bloom-7b
        description:
          type: string
          description: The description of the model.
          example: BLOOM 7B model
        category:
          type: string
          enum:
            - "text/nlp"
          description: The type/category of the model.
          example: text/nlp
      required:
        - name
        - description
        - category

    Prediction:
      deprecated: true
      x-deprecation-date: "2026-05-05"
      type: object
      description: |
        **Deprecated** – This schema will be removed on **2026-05-05**.
        Please refer to the [Migration Guide](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/migration-guide) 
        for instructions on how to migrate.
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier of the model.
          example: 4b71d0fe-d992-463e-82a1-de337d88ac2d
        type:
          type: string
          readOnly: true
          description: Entity type.
          example: model
        properties:
          $ref: "#/components/schemas/PredictionProperties"
        metadata:
          $ref: "#/components/schemas/Metadata"
      required:
        - id
        - type
        - metadata
        - properties

    PredictionProperties:
      deprecated: true
      x-deprecation-date: "2026-05-05"
      type: object
      description: |
        **Deprecated** – This schema will be removed on **2026-05-05**.
        Please refer to the [Migration Guide](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/migration-guide) 
        for instructions on how to migrate.
      properties:
        input:
          description: The input required for the model to run the prediction. For NLP models this is plain text.
          type: string
        collectionId:
          description: ID of the collection
          type: string
        collectionQuery:
          description: Query for the collection
          type: string
        options:
          type: object
          additionalProperties:
            type: string
        additionalOutput:
          type: object
          readOnly: true
          additionalProperties:
            type: string
        output:
          type: string
          readOnly: true
          description: The output of the model.
          example: The AI just said something super smart.
        inputLengthInTokens:
          description: Tokens for input
          type: integer
          format: int32
        outputLengthInTokens:
          description: Tokens for output
          type: integer
          format: int32
      required:
        - input

    ModelsCollection:
      deprecated: true
      x-deprecation-date: "2026-05-05"
      type: object
      description: |
        **Deprecated** – This schema will be removed on **2026-05-05**.
        Please refer to the [Migration Guide](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/migration-guide) 
        for instructions on how to migrate.
      properties:
        id:
          type: string
          description: Unique Collection Identifier
          example: 9fa7d335-209c-5a1e-a8b2-686772fe7a33
          readOnly: true
        type:
          type: string
          description: Entity type
          enum:
            - "collection"
        href:
          type: string
          description: Resource URL
        items:
          type: array
          items:
            $ref: "#/components/schemas/Model"
          description: The list of pretrained models available with the inference service.
      required:
        - id
        - type
        - href
        - items

    ModelsPrediction:
      deprecated: true
      x-deprecation-date: "2026-05-05"
      type: object
      description: |
        **Deprecated** – This schema will be removed on **2026-05-05**.
        Please refer to the [Migration Guide](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/migration-guide) 
        for instructions on how to migrate.
      properties:
        type:
          type: string
          description: The entity type
          enum:
            - prediction
          readOnly: true
        properties:
          $ref: "#/components/schemas/PredictionProperties"
        metadata:
          $ref: "#/components/schemas/MetadataWithDuration"
      required:
        - type
        - metadata
        - properties

    ModelsPredictionBody:
      deprecated: true
      x-deprecation-date: "2026-05-05"
      type: object
      description: |
        **Deprecated** – This schema will be removed on **2026-05-05**.
        Please refer to the [Migration Guide](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/migration-guide) 
        for instructions on how to migrate.
      properties:
        type:
          type: string
          description: The entity type
          enum:
            - prediction
          readOnly: true
        properties:
          $ref: "#/components/schemas/PredictionProperties"
      required:
        - type
        - properties

    Metadata:
      type: object
      description: Metadata of the resource.
      readOnly: true
      properties:
        lastModifiedDate:
          type: string
          readOnly: true
          format: date-time
          example: "2022-08-21T15:52:53Z"
          description: The date of the last change formatted as yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
        createdDate:
          type: string
          readOnly: true
          format: date-time
          example: "2022-08-21T15:52:53Z"
          description: The date of creation of the zone formatted as yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

    MetadataWithDuration:
      allOf:
        - $ref: "#/components/schemas/Metadata"
        - type: object
          readOnly: true
          properties:
            duration:
              type: number
              format: float
              readOnly: true
              description: The time it took for the model to generate the output (in ms).
            outputTokens:
              type: number
              readOnly: true
              description: The length in tokens of the output generated by the model.
            inputTokens:
              type: number
              readOnly: true
              description: The length in tokens of the input sent to the model.

    MetadataQueryResult:
      allOf:
        - $ref: "#/components/schemas/Metadata"
        - type: object
          readOnly: true
          properties:
            duration:
              type: number
              format: float
              readOnly: true
              description: The time it took for the model to generate the output (in ms).
            inputTokens:
              type: number
              example: 23
              description: "The length in tokens of the input sent to the embedding model"

    Error:
      type: object
      additionalProperties: false
      properties:
        httpStatus:
          type: integer
          description: |
            HTTP status code of the operation as specified by [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-6).
          example: 400
        messages:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              errorCode:
                type: string
                description: |
                  Internal error code.
                example: inference-rest-0123
              message:
                type: string
                description: |
                  Human readable explanation of the issue.
                example: example error message

    CollectionsList:
      type: object
      properties:
        id:
          type: string
          description: Unique Collection Identifier
          example: 9fa7d335-209c-5a1e-a8b2-686772fe7a33
          readOnly: true
        type:
          type: string
          description: Entity type
          readOnly: true
          enum:
            - collection
        href:
          type: string
          description: Resource URL
        items:
          type: array
          items:
            $ref: "#/components/schemas/Collection"
          description: The list of available collections.
      required:
        - id
        - type
        - href
        - items

    CollectionDocumentsList:
      type: object
      properties:
        id:
          type: string
          description: Unique Collection Identifier
          example: d4a7d335-209c-5a1e-a8b2-686772fe7a55
          readOnly: true
        type:
          type: string
          description: Entity type
          enum:
            - collection
          readOnly: true
        href:
          type: string
          description: Resource URL
          readOnly: true
        items:
          type: array
          items:
            $ref: "#/components/schemas/Document"
          description: The list of all documents in a collection

    CollectionDocumentsListCreate:
      type: object
      properties:
        id:
          type: string
          description: Unique Collection Identifier
          example: d4a7d335-209c-5a1e-a8b2-686772fe7a55
          readOnly: true
        type:
          type: string
          description: Entity type
          enum:
            - collection
          readOnly: true
        href:
          type: string
          description: Resource URL
          readOnly: true
        items:
          type: array
          items:
            $ref: "#/components/schemas/DocumentCreate"
          description: The list of all documents in a collection
          x-oapi-codegen-extra-tags:
            validate: required
      required:
        - type
        - items
      
    Document:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier of the document.
          example: 4b71d0fe-d992-463e-82a1-de337d88ac2d
        type:
          type: string
          readOnly: true
          description: Type of object
          enum:
            - document
        href:
          type: string
          readOnly: true
          description: Resource URL
        properties:
          $ref: "#/components/schemas/DocumentProperties"
        metadata:
          $ref: "#/components/schemas/Metadata"
      required:
        - properties

    DocumentCreate:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier of the document.
          example: 4b71d0fe-d992-463e-82a1-de337d88ac2d
        type:
          type: string
          readOnly: true
          description: Type of object
          enum:
            - document
        href:
          type: string
          readOnly: true
          description: Resource URL
        properties:
          allOf:
            - $ref: "#/components/schemas/DocumentPropertiesCreate"
            - type: object
          x-oapi-codegen-extra-tags:
            validate: required                    
        metadata:
          $ref: "#/components/schemas/Metadata"
      required:
        - properties

    DocumentProperties:
      type: object
      description: Document properties.
      minProperties: 1
      properties:
        name:
          type: string
          description: |
            The name set for the document. should have a length between 3 and 256 characters,
            should start and ends with an alphanumeric character, can only contain alphanumeric
            characters or hyphens, should not contain two consecutive periods and should not
            be a valid IPv4 address.
          minLength: 3
          maxLength: 256
          x-oapi-codegen-extra-tags:
            validate: omitempty,gte=3,lte=256
        description:
          type: string
          description: The description set for the document, max 1024 chars.
          x-oapi-codegen-extra-tags:
            validate: omitempty,lte=1024
        contentType:
          type: string
          readOnly: false
          description: The type of document, content-type values accepted.
          enum:
            - text/plain
          example: text/plain
        content:
          type: string
          description: The content of the document, base64 encoded. The maximum length of undecoded content is 65535 characters.
          example: TG9yZW0gaXBzdW0uLi4K
          x-oapi-codegen-extra-tags:
            validate: omitempty,base64
        labels:
          type: object
          description: The labels set for the document.
          additionalProperties:
            oneOf:
              - type: string
                maxLength: 256
                description: The label value, max 256 chars.
              - type: boolean
              - type: number
          x-oapi-codegen-extra-tags:
            validate: omitempty,dive,labelsValidation
      x-oapi-codegen-extra-tags:
        validate: minProperties=1

    DocumentPropertiesCreate:
      type: object
      description: Document properties.
      properties:
        name:
          type: string
          description: |
            The name set for the document. should have a length between 3 and 256 characters,
            should start and ends with an alphanumeric character, can only contain alphanumeric
            characters or hyphens, should not contain two consecutive periods and should not
            be a valid IPv4 address.
          minLength: 3
          maxLength: 256
          x-oapi-codegen-extra-tags:
            validate: required,gte=3,lte=256
        description:
          type: string
          description: The description set for the document, max 1024 chars.
          x-oapi-codegen-extra-tags:
            validate: omitempty,lte=1024
        contentType:
          type: string
          readOnly: false
          description: The type of document, content-type values accepted.
          enum:
            - text/plain
          example: text/plain
          x-oapi-codegen-extra-tags:
            validate: required   
        content:
          type: string
          description: The content of the document, base64 encoded. The maximum length of undecoded content is 65535 characters. 
          example: TG9yZW0gaXBzdW0uLi4K
          x-oapi-codegen-extra-tags:
            validate: required,base64   
        labels:
          type: object
          description: The labels set for the document.
          additionalProperties:
            oneOf:
              - type: string
                maxLength: 256
                description: The label value, max 256 chars.
              - type: boolean
              - type: number
          x-oapi-codegen-extra-tags:
            validate: omitempty,dive,labelsValidation
      required:
        - name
        - contentType
        - content
      
    Collection:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier of the documents collection.
          example: 4b71d0fe-d992-463e-82a1-de337d88ac2d
        href:
          type: string
          readOnly: true
          description: Resource URL
        type:
          type: string
          enum:
            - collection
          readOnly: true
          example: collection
          description: Type of object
        properties:
          $ref: "#/components/schemas/CollectionProperties"
        metadata:
          $ref: "#/components/schemas/Metadata"
      required: 
        - properties
    
    CollectionUpdate:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier of the documents collection.
          example: 4b71d0fe-d992-463e-82a1-de337d88ac2d
        href:
          type: string
          readOnly: true
          description: Resource URL
        type:
          type: string
          enum:
            - collection
          readOnly: true
          example: collection
          description: Type of object
        properties:
          $ref: "#/components/schemas/CollectionPropertiesUpdate"
        metadata:
          $ref: "#/components/schemas/Metadata"
      required: 
        - properties

    CollectionCreate:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier of the documents collection.
        href:
          type: string
          readOnly: true
          description: Resource URL
        type:
          type: string
          enum:
            - collection
          readOnly: true
          description: Type of object
        properties:
          allOf:
            - $ref: "#/components/schemas/CollectionPropertiesCreate"
            - type: object
          x-oapi-codegen-extra-tags:
            validate: required 
        metadata:
          $ref: "#/components/schemas/Metadata"
      required:
        - properties

    CollectionProperties:
      type: object
      description: Collection properties.
      minProperties: 1
      properties:
        name:
          type: string
          description: |
            The name set for the collection. should have a length between 3 and 256 characters,
            should start and ends with an alphanumeric character, can only contain alphanumeric
            characters or hyphens, should not contain two consecutive periods and should not
            be a valid IPv4 address.
          minLength: 3
          maxLength: 256
          x-oapi-codegen-extra-tags:
            validate: omitempty,gte=3,lte=256
        description:
          type: string
          description: The description set for the collection, max 1024 chars.
          x-oapi-codegen-extra-tags:
            validate: omitempty,lte=1024
        labels:
          type: object
          description: The labels set for the collection.
          additionalProperties:
            description: The label value, max 256 chars.
          x-oapi-codegen-extra-tags:
            validate: omitempty,dive,lte=256
        documentsCount:
          type: integer
          description: The number of documents in the collection.
          example: 2
        totalTokens:
          type: integer
          description: The total size of all documents in the collection, in tokens.
          example: 1024
        embedding:
          $ref: "#/components/schemas/Embedding"
        engine:
          $ref: "#/components/schemas/Engine"
        chunking:
          $ref: "#/components/schemas/Chunking"
      x-oapi-codegen-extra-tags:
        validate: minProperties=1

    CollectionPropertiesUpdate:
      type: object
      description: Collection properties.
      minProperties: 1
      properties:
        name:
          type: string
          description: |
            The name set for the collection. should have a length between 3 and 256 characters,
            should start and ends with an alphanumeric character, can only contain alphanumeric
            characters or hyphens, should not contain two consecutive periods and should not
            be a valid IPv4 address.
          minLength: 3
          maxLength: 256
          x-oapi-codegen-extra-tags:
            validate: omitempty,gte=3,lte=256
        description:
          type: string
          description: The description set for the collection, max 1024 chars.
          x-oapi-codegen-extra-tags:
            validate: omitempty,lte=1024
        labels:
          type: object
          description: The labels set for the collection.
          additionalProperties:
            description: The label value, max 256 chars.
          x-oapi-codegen-extra-tags:
            validate: omitempty,dive,lte=256
      x-oapi-codegen-extra-tags:
        validate: minProperties=1   

    CollectionPropertiesCreate:
      type: object
      description: Collection properties.
      properties:
        name:
          type: string
          description: |
            The name set for the collection. should have a length between 3 and 256 characters,
            should start and ends with an alphanumeric character, can only contain alphanumeric
            characters or hyphens, should not contain two consecutive periods and should not
            be a valid IPv4 address.
          minLength: 3
          maxLength: 256
          x-oapi-codegen-extra-tags:
            validate: required,gte=3,lte=256
        description:
          type: string
          description: The description set for the collection, max 1024 chars.
          x-oapi-codegen-extra-tags:
            validate: omitempty,lte=1024
        labels:
          type: object
          description: The labels set for the collection.
          additionalProperties:
            description: The label value, max 256 chars.
          x-oapi-codegen-extra-tags:
            validate: omitempty,dive,lte=256
        embedding:
          $ref: "#/components/schemas/Embedding"
        engine:
          $ref: "#/components/schemas/Engine"
        chunking:
          $ref: "#/components/schemas/Chunking"
      required:
        - name

    QueryRequest:
      type: object
      properties:
        query:
          type: string
          description: The string used to query the vector database.
          minLength: 1
        limit:
          type: integer
          default: 10
          description: The maximum number of matches to return.
      required:
        - query

    QueryResult:
      type: object
      properties:
        type:
          type: string
          enum:
            - result
          readOnly: true
          description: Type of object
        properties:
          $ref: "#/components/schemas/QueryResultProperties"
        metadata:
          $ref: "#/components/schemas/MetadataQueryResult"
      required:
        - type
        - metadata
        - properties

    QueryResultProperties:
      type: object
      description: Query result properties.
      properties:
        matches:
          type: array
          items:
            type: object
            properties:
              score:
                type: number
                description: |
                  The match score. Lower values indicate better matches.
              document:
                $ref: "#/components/schemas/Document"
      required:
        - matches

    Chunking:
      type: object
      description: |
        Indicating if there should be a chunking strategy and if enabled,
        specify parameters needed for the chosen strategy.
      properties:
        enabled:
          type: boolean
          description: Flag to indicate whether chunking is enabled.
          default: false
        strategy:
          $ref: '#/components/schemas/Strategy'

    Strategy:
      type: object
      description: |
        Strategy object which will vary based on the type of strategy selected. 
        If enabled, the default strategy is "fixed_size" with the default values.
        * `fixed_size` It splits the text into chunk_size tokens
      properties:
        name:
          type: string
          default: fixed_size
          description: The name of the chunking strategy.
        config:
          type: object
          description: Configuring chunk_size and chunk_overlap for the selected chunking strategy.
          properties:
            chunk_size:
              type: integer
              description: Size of each chunk when the strategy is "fixed_size".
              minimum: 128
              default: 128
              x-oapi-codegen-extra-tags:
                validate: omitempty,gte=128
            chunk_overlap:
              type: integer
              description: Overlap between consecutive chunks when the strategy is "fixed_size".
              minimum: 50
              default: 50
              x-oapi-codegen-extra-tags:
                validate: omitempty,gte=50

    Embedding:
      type: object
      description: Indicates information about the embedding model used by this collection
      properties:
        model:
          type: string
          description: Name of the model to use.

    Engine:
      type: object
      description: Additional information about the database engine that user wants to use.
      properties:
        db_type:
          type: string
          enum:
            - chromadb
            - pgvector
          default: chromadb
          description: Type of database to use. Defaults to chromadb.

  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description:
        Please provide header value as 'Bearer <token>' and don't forget
        to add 'Bearer' HTTP Authorization Scheme before the token.

  responses:
    BadRequest:
      description: |
        ### Bad Request
        The request send to the API was malformed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: |
        ### Unauthorized
        The request is missing authorization information or the authorization information provided are expired.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: |
        ### Forbidden
        The user issuing the request does not have the needed permissions.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: |
        ### Not Found
        The resource that was requested could not be found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: |
        ### Internal Server Error
        An internal error occurred. We apologize for the inconvenience!
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  examples:
    CollectionDocumentsListResponseBodyExample:
      description: Documents list response body example
      value:
        id: 63a7d335-209c-5a1e-a8b2-686772fe2e55
        type: collection
        href: "<RESOURCE-URL>"
        items:
          - id: 9fa7d335-209c-5a1e-a8b2-686772fe7a33
            type: document
            properties:
              contentType: text/plain
              name: Lorem doc 1
              content: "<DOCUMENT-CONTENT-BASE64-ENCODED>"
            metadata:
              lastModifiedDate: "2022-07-19T15:52:53Z"
              createdDate: "2022-07-19T15:52:53Z"
          - id: 7ea7d335-209c-5a1e-a8b2-686772fe7a22
            type: document
            properties:
              contentType: text/plain
              name: Lorem doc 2
              content: "<DOCUMENT-CONTENT-BASE64-ENCODED>"
            metadata:
              lastModifiedDate: "2022-08-21T15:52:53Z"
              createdDate: "2022-08-21T15:52:53Z"   

    DocumentsAddRequestBodyExample:
      description: Array of documents to add
      value:
        type: collection
        items:
          - type: document
            properties:
              name: Lorem Doc 1
              description: This is a document about lorem ipsum
              contentType: text/plain
              content: "<DOCUMENT-CONTENT-BASE64-ENCODED>"
              labels:
                topic: linux
                subtopic: networking
    
    DocumentsAddResponseBodyExample:
      description: Response documents example
      value:
        id: collection_id
        type: collection
        href: collection_href
        items:
          - type: document
            properties:
              name: Lorem Doc 1
              description: This is a document about lorem ipsum
              contentType: text/plain
              content: "<DOCUMENT-CONTENT-BASE64-ENCODED>"
              labels:
                topic: linux
                subtopic: networking

    DocumentResponseBodyExample:
      description: Document response body example
      value:
        id: 9fa7d335-209c-5a1e-a8b2-686772fe7a33
        type: document
        href: "<RESOURCE-URL>"
        properties:
          contentType: text/plain
          name: Lorem doc 1
          content: "<DOCUMENT-CONTENT-BASE64-ENCODED>"
          description: "This is a document about lorem ipsum"
        metadata:
          lastModifiedDate: "2022-07-19T15:52:53Z"
          createdDate: "2022-07-19T15:52:53Z"

    CollectionListResponseBodyExample:
      description: List of all collections
      value:
        id: 63a7d335-209c-5a1e-a8b2-686772fe2e55
        type: collection
        href: "<RESOURCE-URL>"
        items:
          - id: 9fa7d335-209c-5a1e-a8b2-686772fe7a33
            type: collection
            href: "<RESOURCE-URL>"
            properties:
              name: My first collection
              description: My first collection description
              chunking:
                enabled: true
                strategy:
                  name: fixed_size
                  config:
                    chunk_overlap: 50
                    chunk_size: 128
              embedding: 
                model: "BAAI/bge-large-en-v1.5"
              engine: 
                db_type: "pgvector"
              labels:
                label_1: "label value"
                label_2: "label value"
          - id: bbdda335-209c-5a1e-a8b2-686772fe7a33
            type: collection
            href: "<RESOURCE-URL>"
            properties:
              name: My second collection
              description: My second collection description
              chunking:
                enabled: false
              embedding: 
                model: "sentence-transformers/paraphrase-multilingual-mpnet-base-v2"
              engine: 
                db_type: "chromadb"
              labels:
                label_1: "label value"
                label_2: "label value"
        
    CollectionResponseBodyExample:
      description: Collection response body example
      value:
        id: 9fa7d335-209c-5a1e-a8b2-686772fe7a33
        type: collection
        href: "<RESOURCE-URL>"
        properties:
          name: My collection
          description: My collection description
          chunking:
            enabled: true
            strategy:
              name: fixed_size
              config:
                chunk_overlap: 50
                chunk_size: 128
          embedding: 
            model: "BAAI/bge-large-en-v1.5"
          engine: 
            db_type: "pgvector"
          labels:
            label_1: "label value"
            label_2: "label value"
    
    CollectionCreateRequestBodyExample: 
      description: Create a new collection request body example
      value:
        type: collection
        properties:
          name: My collection
          description: My collection description
          chunking:
            enabled: true
            strategy:
              name: fixed_size
              config:
                chunk_overlap: 50
                chunk_size: 128
          embedding: 
            model: "BAAI/bge-large-en-v1.5"
          engine: 
            db_type: "pgvector"
          labels:
            label_1: "label value"
            label_2: "label value"
    
    CollectionUpdateResponseBodyExample:
      description: Collection response body example
      value:
        id: 9fa7d335-209c-5a1e-a8b2-686772fe7a33
        type: collection
        href: "<RESOURCE-URL>"
        properties:
          name: My updated collection
          description: My updated collection description
          chunking:
            enabled: true
            strategy:
              name: fixed_size
              config:
                chunk_overlap: 50
                chunk_size: 128
          embedding: 
            model: "BAAI/bge-large-en-v1.5"
          engine: 
            db_type: "pgvector"
          labels:
            label_1: "updated label value"
            label_2: "label value"
         
    CollectionUpdateRequestBodyExample:
      description: Update properties of collection example
      value:
        properties:
          name: My updated collection
          description: My updated collection description
          labels:
            label_1: "updated label value"
