#@ load("openapi.lib.yml", "response", "reference", "type", "array")

paths:
  /collections:
    get:
      tags:
        - Collections
      summary: List collections
      description: Get list name of all existing collections
      operationId: get_collections
      responses: #@ response(reference("CollectionsResponse"))

  /collections/{collection_name}:
    get:
      tags:
        - Collections
      summary: Collection info
      description: Get detailed information about specified existing collection
      operationId: get_collection
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to retrieve
          required: true
          schema:
            type: string
      responses: #@ response(reference("CollectionInfo"))

    put:
      tags:
        - Collections
      summary: Create collection
      description: Create new collection with given parameters
      operationId: create_collection
      requestBody:
        description: Parameters of a new collection
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCollection"

      parameters:
        - name: collection_name
          in: path
          description: Name of the new collection
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          description: |
            Wait for operation commit timeout in seconds.
            If timeout is reached - request will return with service error.
          schema:
            type: integer
            minimum: 1
      responses: #@ response(type("boolean"))

    patch:
      tags:
        - Collections
      summary: Update collection parameters
      description: Update parameters of the existing collection
      operationId: update_collection
      requestBody:
        description: New parameters
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateCollection"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to update
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          description: |
            Wait for operation commit timeout in seconds.
            If timeout is reached - request will return with service error.
          schema:
            type: integer
            minimum: 1
      responses: #@ response(type("boolean"))

    delete:
      tags:
        - Collections
      summary: Delete collection
      description: Drop collection and all associated data
      operationId: delete_collection
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to delete
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          description: |
            Wait for operation commit timeout in seconds.
            If timeout is reached - request will return with service error.
          schema:
            type: integer
            minimum: 1
      responses: #@ response(type("boolean"))

  /collections/aliases:
    post:
      tags:
        - Aliases
      summary: Update aliases of the collections
      operationId: update_aliases
      requestBody:
        description: Alias update operations
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChangeAliasesOperation"
      parameters:
        - name: timeout
          in: query
          description: |
            Wait for operation commit timeout in seconds.
            If timeout is reached - request will return with service error.
          schema:
            type: integer
            minimum: 1
      responses: #@ response(type("boolean"))

  /collections/{collection_name}/index:
    put:
      tags:
        - Indexes
      summary: Create index for field in collection
      description: Create index for field in collection
      operationId: create_field_index
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
        - name: timeout
          in: query
          description: "Timeout for the operation"
          required: false
          schema:
            type: integer
            minimum: 1
      requestBody:
        description: Field name
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateFieldIndex"

      responses: #@ response(reference("UpdateResult"))

  /collections/{collection_name}/exists:
    get:
      tags:
        - Collections
      summary: Check the existence of a collection
      description: Returns "true" if the given collection name exists, and "false" otherwise
      operationId: collection_exists
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection
          required: true
          schema:
            type: string
      responses: #@ response(reference("CollectionExistence"))

  /collections/{collection_name}/index/{field_name}:
    delete:
      tags:
        - Indexes
      summary: Delete index for field in collection
      description: Delete field index for collection
      operationId: delete_field_index
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection
          required: true
          schema:
            type: string
        - name: field_name
          in: path
          description: Name of the field where to delete the index
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
        - name: timeout
          in: query
          description: "Timeout for the operation"
          required: false
          schema:
            type: integer
            minimum: 1
      responses: #@ response(reference("UpdateResult"))

  /collections/{collection_name}/vectors/{vector_name}:
    put:
      tags:
        - Collections
      summary: Create named vector
      description: Create a new named vector on an existing collection
      operationId: create_vector_name
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection
          required: true
          schema:
            type: string
        - name: vector_name
          in: path
          description: Name of the vector to create
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
        - name: timeout
          in: query
          description: "Timeout for the operation"
          required: false
          schema:
            type: integer
            minimum: 1
      requestBody:
        description: Vector configuration - dense or sparse
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VectorNameConfig"
      responses: #@ response(reference("UpdateResult"))

    delete:
      tags:
        - Collections
      summary: Delete named vector
      description: Delete a named vector from a collection
      operationId: delete_vector_name
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection
          required: true
          schema:
            type: string
        - name: vector_name
          in: path
          description: Name of the vector to delete
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: "If true, wait for changes to actually happen"
          required: false
          schema:
            type: boolean
        - name: ordering
          in: query
          description: "define ordering guarantees for the operation"
          required: false
          schema:
            $ref: "#/components/schemas/WriteOrdering"
        - name: timeout
          in: query
          description: "Timeout for the operation"
          required: false
          schema:
            type: integer
            minimum: 1
      responses: #@ response(reference("UpdateResult"))

  /collections/{collection_name}/cluster:
    get:
      tags:
        - Distributed
      summary: Collection cluster info
      description: Get cluster information for a collection
      operationId: collection_cluster_info
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to retrieve the cluster info for
          required: true
          schema:
            type: string
      responses: #@ response(reference("CollectionClusterInfo"))

    post:
      tags:
        - Distributed
      summary: Update collection cluster setup
      operationId: update_collection_cluster
      requestBody:
        description: Collection cluster update operations
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClusterOperations"
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection on which to to apply the cluster update operation
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          description: |
            Wait for operation commit timeout in seconds.
            If timeout is reached - request will return with service error.
          schema:
            type: integer
            minimum: 1
      responses: #@ response(type("boolean"))

  /collections/{collection_name}/optimizations:
    get:
      tags:
        - Collections
      summary: Get optimization progress
      description: Get progress of ongoing and completed optimizations for a collection
      operationId: get_optimizations
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection
          required: true
          schema:
            type: string
        - name: with
          in: query
          description: |-
            Comma-separated list of optional fields to include in the response.
            Possible values: queued, completed, idle_segments.
          required: false
          schema:
            type: string
        - name: completed_limit
          in: query
          description: |-
            Maximum number of completed optimizations to return.
            Ignored if `completed` is not in the `with` parameter.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 16 #! Keep in sync with DEFAULT_OPTIMIZATIONS_COMPLETED_LIMIT
      responses: #@ response(reference("OptimizationsResponse"))

  /collections/{collection_name}/aliases:
    get:
      tags:
        - Aliases
      summary: List aliases for collection
      description: Get list of all aliases for a collection
      operationId: get_collection_aliases
      parameters:
        - name: collection_name
          in: path
          description: Name of the collection
          required: true
          schema:
            type: string
      responses: #@ response(reference("CollectionsAliasesResponse"))

  /aliases:
    get:
      tags:
        - Aliases
      summary: List collections aliases
      description: Get list of all existing collections aliases
      operationId: get_collections_aliases
      responses: #@ response(reference("CollectionsAliasesResponse"))
