Haystack / deepset File API

openapi: 3.2.0
info:
  description: deepset API description
  title: Haystack Enterprise Platform File API
  version: 1.0.0
servers:
- description: deepset Europe
  url: https://api.cloud.deepset.ai
- description: deepset US
  url: https://api.us.deepset.ai
tags:
- name: File
paths:
  /api/v1/workspaces/{workspace_name}/files:
    delete:
      description: Deletes files specified in the `names` parameter from a workspace. If `names` is empty, it deletes all files.
      operationId: delete_files_api_v1_workspaces__workspace_name__files_delete
      parameters:
      - description: Type the name of the workspace.
        in: path
        name: workspace_name
        required: true
        schema:
          description: Type the name of the workspace.
          title: Workspace Name
          type: string
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/FileNames'
              - type: 'null'
              description: Type the names of the files you want to delete, separated with commas.
              title: Files
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Delete Files
      tags:
      - File
      x-deepset-permissions:
        action: write
        asset: files
        asset_description: Access to individual file details
        type: workspace
  /api/v1/workspaces/{workspace_name}/files/_search:
    post:
      description: Executes an OpenSearch query on the workspace's file index and returns the raw response. The query must follow the OpenSearch Query DSL syntax.
      operationId: search_files_api_v1_workspaces__workspace_name__files__search_post
      parameters:
      - description: Type the name of the workspace.
        in: path
        name: workspace_name
        required: true
        schema:
          description: Type the name of the workspace.
          title: Workspace Name
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              title: Query
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Search Files
      tags:
      - File
      x-deepset-permissions:
        action: read
        asset: files
        asset_description: Access to individual file details
        type: workspace
  /api/v1/workspaces/{workspace_name}/files/_sql:
    post:
      description: Executes an SQL query on the workspace's file index and returns the raw response. The query must follow the OpenSearch SQL Query syntax.The table must be `file`.
      operationId: query_files_api_v1_workspaces__workspace_name__files__sql_post
      parameters:
      - description: Type the name of the workspace.
        in: path
        name: workspace_name
        required: true
        schema:
          description: Type the name of the workspace.
          title: Workspace Name
          type: string
      - description: The format of the response. For explanation, see [Opensearch response formats](https://docs.opensearch.org/latest/search-plugins/sql/response-formats/).
        in: query
        name: format
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The format of the response. For explanation, see [Opensearch response formats](https://docs.opensearch.org/latest/search-plugins/sql/response-formats/).
          title: Format
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SQLRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Query Files
      tags:
      - File
      x-deepset-permissions:
        action: read
        asset: files
        asset_description: Access to individual file details
        type: workspace
  /api/v1/workspaces/{workspace_name}/files/update-meta:
    post:
      description: 'Updates the metadata of the files and of the documents created from these files. You can modify existing metadata or add new ones. If you send a new metadata dictionary, it''s merged with the existing dictionary. To change the value of an existing key, pass this key with the new value. To add a new key:value pair, simply pass it in the request. It will add the new metadata and keep the existing ones. To delete a key:value pair, pass the key with `None` as value, for example: "author":"None". (But to fully delete all metadata, upload the file again.)'
      operationId: update_file_meta_bulk_api_v1_workspaces__workspace_name__files_update_meta_post
      parameters:
      - description: Type the name of the workspace.
        in: path
        name: workspace_name
        required: true
        schema:
          description: Type the name of the workspace.
          title: Workspace Name
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileMetaBulkRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateFileMetaBulkResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Update File Meta Bulk
      tags:
      - File
      x-deepset-permissions:
        action: write
        asset: files
        asset_description: Access to individual file details
        type: workspace
  /api/v1/workspaces/{workspace_name}/files/{file_id}:
    get:
      description: Retrieves the file contents.
      operationId: get_file_api_v1_workspaces__workspace_name__files__file_id__get
      parameters:
      - in: path
        name: file_id
        required: true
        schema:
          format: uuid
          title: File ID
          type: string
      - description: Type the name of the workspace.
        in: path
        name: workspace_name
        required: true
        schema:
          description: Type the name of the workspace.
          title: Workspace Name
          type: string
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '404':
          description: There's no file with the ID '<file_id>' in the workspace. Check if the ID is correct. You can use the `list_files` endpoint to check file IDs.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '500':
          description: File with the ID '{file_id}' doesn't have a type.
      security:
      - HTTPBearer: []
      summary: Get File
      tags:
      - File
      x-deepset-permissions:
        action: read
        asset: files
        asset_description: Access to individual file details
        type: workspace
  /api/v1/workspaces/{workspace_name}/files/{file_id}/meta:
    get:
      description: Displays the metadata of a file.
      operationId: get_file_meta_api_v1_workspaces__workspace_name__files__file_id__meta_get
      parameters:
      - in: path
        name: file_id
        required: true
        schema:
          format: uuid
          title: File ID
          type: string
      - description: Type the name of the workspace.
        in: path
        name: workspace_name
        required: true
        schema:
          description: Type the name of the workspace.
          title: Workspace Name
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileMetadata'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Get File Meta
      tags:
      - File
      x-deepset-permissions:
        action: read
        asset: files
        asset_description: Access to individual file details
        type: workspace
  /api/v1/workspaces/{workspace_name}/temporary_files:
    post:
      description: Uploads a file into the workspace. You can also use this endpoint to create a text file. To do that, enter the file name and text as its contents.
      operationId: upload_temporary_file_api_v1_workspaces__workspace_name__temporary_files_post
      parameters:
      - description: Type the name of the workspace.
        in: path
        name: workspace_name
        required: true
        schema:
          description: Type the name of the workspace.
          title: Workspace Name
          type: string
      - description: The name of the file you want to create. Use this field only if you're creating a file to upload. If you're uploading an existing file, leave this field empty.
        in: query
        name: file_name
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The name of the file you want to create. Use this field only if you're creating a file to upload. If you're uploading an existing file, leave this field empty.
          title: File Name
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_temporary_file_api_v1_workspaces__workspace_name__temporary_files_post'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileResponse'
          description: Your file's in the workspace.
        '400':
          description: 'We couldn''t upload your file because some of the arguments specified were incompatible. You can upload a file from your disk or create a file by providing a file name and text as its contents. '
        '413':
          description: Too large payload.Either the file uploaded is larger than 200 MB or the metadata you tried to upload is too large. The string '<your-string>' of key '<your-key>' is longer than 32766 bytes, which approximately equals the same number of characters.To upload files larger than 200 MB, use the [deepset SDK](https://github.com/deepset-ai/deepset-cloud-sdk).
        '415':
          description: Haystack Enterprise Platform supports .txt, .csv, .json, .xml, .html, .md, .pdf, .docx, .pptx, .xlsx, .xlsb, .xlsm, .msg, .zip and ..DS_Store files. Upload a file in the supported format.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Upload Temporary File
      tags:
      - File
      x-deepset-permissions:
        action: read
        asset: pipelines
        asset_description: Access to individual pipeline details
        type: workspace
  /api/v1/workspaces/{workspace_name}/temporary_files/{file_id}:
    get:
      description: 'Retrieves the file contents of temporary files.


        :param session: The database session.

        :param file_id: The ID of the file to retrieve.

        :param workspace: The workspace from which to retrieve the file.'
      operationId: get_temporary_file_api_v1_workspaces__workspace_name__temporary_files__file_id__get
      parameters:
      - in: path
        name: file_id
        required: true
        schema:
          format: uuid
          title: File ID
          type: string
      - description: Type the name of the workspace.
        in: path
        name: workspace_name
        required: true
        schema:
          description: Type the name of the workspace.
          title: Workspace Name
          type: string
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '404':
          description: There's no file with the ID '<file_id>' in the workspace. Check if the ID is correct. You can use the `list_files` endpoint to check file IDs.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '500':
          description: File with the ID '{file_id}' doesn't have a type.
      security:
      - HTTPBearer: []
      summary: Get Temporary File
      tags:
      - File
      x-deepset-permissions:
        action: read
        asset: pipelines
        asset_description: Access to individual pipeline details
        type: workspace
components:
  schemas:
    FileUpdateError:
      properties:
        error_message:
          description: The error message.
          title: Error message
          type: string
        error_type:
          description: The type of error that occurred.
          title: Error type
          type: string
        file_id:
          description: Unique identifier of a file.
          format: uuid
          title: File ID
          type: string
      required:
      - file_id
      - error_type
      - error_message
      title: FileUpdateError
      type: object
    SQLRequest:
      properties:
        cursor:
          anyOf:
          - type: string
          - type: 'null'
          description: The cursor for paginating through results.
          title: Cursor
        fetch_size:
          anyOf:
          - type: integer
          - type: 'null'
          description: The number of results to return per page.
          title: Fetch size
        query:
          anyOf:
          - type: string
          - type: 'null'
          description: The OpenSearch SQL query to execute.
          title: SQL query
      title: SQLRequest
      type: object
    UpdateFileMetaBulkResponse:
      properties:
        failed_count:
          description: The number of files that failed to update.
          title: Failed file count
          type: integer
        failed_files:
          description: The files that failed to update.
          items:
            $ref: '#/components/schemas/FileUpdateError'
          title: Failed files
          type: array
        updated_count:
          description: The number of files that were updated.
          title: Updated file count
          type: integer
      required:
      - updated_count
      - failed_count
      - failed_files
      title: UpdateFileMetaBulkResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    FileMetadata:
      additionalProperties: true
      title: Metadata of file
      type: object
    UploadFileResponse:
      properties:
        file_id:
          description: Unique identifier of a file.
          format: uuid
          title: File ID
          type: string
      required:
      - file_id
      title: UploadFileResponse
      type: object
    FileNames:
      properties:
        names:
          description: The names of the files to delete.
          items:
            type: string
          maxItems: 6000
          title: File names
          type: array
      required:
      - names
      title: FileNames
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    Body_upload_temporary_file_api_v1_workspaces__workspace_name__temporary_files_post:
      properties:
        file:
          anyOf:
          - contentMediaType: application/octet-stream
            type: string
          - type: 'null'
          description: The name of the file you want to upload.
          title: File
        meta:
          default: '{}'
          description: A list of metadata fields in the "key":"value" format. During search, you can use these metadata as filters.
          title: Meta
          type: string
        text:
          anyOf:
          - type: string
          - type: 'null'
          description: Instead of uploading a file, you can paste the file contents here to create a text file.
          title: Text
      title: Body_upload_temporary_file_api_v1_workspaces__workspace_name__temporary_files_post
      type: object
    FileId:
      format: uuid
      title: File ID
      type: string
    UpdateFileMetaBulkRequest:
      additionalProperties:
        $ref: '#/components/schemas/FileMetadata'
      propertyNames:
        $ref: '#/components/schemas/FileId'
      title: Bulk file metadata update request
      type: object