Microsoft Azure AI Foundry Files API

openapi: 3.2.0
info:
  title: Azure AI Files API
  version: v1
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
security:
- OAuth2Auth:
  - https://ai.azure.com/.default
tags:
- name: Files
paths:
  /files:
    get:
      operationId: Files_ListFiles
      description: Gets a list of previously uploaded files.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: purpose
        in: query
        description: The purpose of the file.
        required: false
        x-ms-enum:
          name: FilePurpose
          modelAsString: true
          values:
          - name: agents
            value: assistants
            description: Indicates a file is used as input to agents.
          - name: agentsOutput
            value: assistants_output
            description: Indicates a file is used as output by agents.
          - name: vision
            value: vision
            description: Indicates a file is used as input to a vision operation.
        schema:
          type: string
          enum:
          - assistants
          - assistants_output
          - vision
      responses:
        '200':
          description: The requested list of files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
      tags:
      - Files
      summary: Files list files
      x-summary-source: derived
    post:
      operationId: Files_UploadFile
      description: Uploads a file for use by other operations.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      responses:
        '200':
          description: A representation of the uploaded file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileInfo'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: The file data, in bytes.
                  format: binary
                purpose:
                  type: string
                  enum:
                  - assistants
                  - assistants_output
                  - vision
                  description: The intended purpose of the uploaded file. Use `assistants` for Agents and Message files, `vision` for Agents image file inputs, `batch` for Batch API, and `fine-tune` for Fine-tuning.
                filename:
                  type: string
                  description: The name of the file.
              required:
              - file
              - purpose
      tags:
      - Files
      summary: Files upload file
      x-summary-source: derived
  /files/{fileId}:
    get:
      operationId: Files_GetFile
      description: Returns information about a specific file. Does not retrieve file content.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: fileId
        in: path
        description: The ID of the file to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileInfo'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
      tags:
      - Files
      summary: Files get file
      x-summary-source: derived
    delete:
      operationId: Files_DeleteFile
      description: Delete a previously uploaded file.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: fileId
        in: path
        description: The ID of the file to delete.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Status of the deletion operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDeletionStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
      tags:
      - Files
      summary: Files delete file
      x-summary-source: derived
  /files/{fileId}/content:
    get:
      operationId: Files_GetFileContent
      description: Retrieves the raw content of a specific file.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: fileId
        in: path
        description: The ID of the file to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: string
                format: binary
        default:
          description: An unexpected error response.
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
            application/json:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
      tags:
      - Files
      summary: Files get file content
      x-summary-source: derived
components:
  schemas:
    FileDeletionStatus:
      type: object
      description: A status response from a file deletion operation.
      properties:
        id:
          type: string
          description: The ID of the resource specified for deletion.
        deleted:
          type: boolean
          description: A value indicating whether deletion was successful.
        object:
          type: string
          description: The object type, which is always 'file'.
          enum:
          - file
          x-ms-enum:
            modelAsString: false
      required:
      - id
      - deleted
      - object
    FilePurpose:
      type: string
      description: The possible values denoting the intended usage of a file.
      enum:
      - assistants
      - assistants_output
      - vision
      x-ms-enum:
        name: FilePurpose
        modelAsString: true
        values:
        - name: agents
          value: assistants
          description: Indicates a file is used as input to agents.
        - name: agentsOutput
          value: assistants_output
          description: Indicates a file is used as output by agents.
        - name: vision
          value: vision
          description: Indicates a file is used as input to a vision operation.
    FileState:
      type: string
      description: The state of the file.
      enum:
      - uploaded
      - pending
      - running
      - processed
      - error
      - deleting
      - deleted
      x-ms-enum:
        name: FileState
        modelAsString: true
        values:
        - name: uploaded
          value: uploaded
          description: 'The file has been uploaded but it''s not yet processed. This state is not returned by Azure OpenAI and exposed only for

            compatibility. It can be categorized as an inactive state.'
        - name: pending
          value: pending
          description: The operation was created and is not queued to be processed in the future. It can be categorized as an inactive state.
        - name: running
          value: running
          description: The operation has started to be processed. It can be categorized as an active state.
        - name: processed
          value: processed
          description: The operation has successfully processed and is ready for consumption. It can be categorized as a terminal state.
        - name: error
          value: error
          description: The operation has completed processing with a failure and cannot be further consumed. It can be categorized as a terminal state.
        - name: deleting
          value: deleting
          description: 'The entity is in the process to be deleted. This state is not returned by Azure OpenAI and exposed only for compatibility.

            It can be categorized as an active state.'
        - name: deleted
          value: deleted
          description: 'The entity has been deleted but may still be referenced by other entities predating the deletion. It can be categorized as a

            terminal state.'
    AgentErrorDetail:
      type: object
      description: Describes the error information returned by the agents API.
      properties:
        message:
          type:
          - string
          - 'null'
          description: Human-readable description of the error.
        type:
          type:
          - string
          - 'null'
          description: Error type identifier (e.g. `invalid_request_error`).
        param:
          type:
          - string
          - 'null'
          description: Name of the parameter that caused the error, if applicable.
        code:
          type:
          - string
          - 'null'
          description: Machine-readable error code.
    FileListResponse:
      type: object
      description: The response data from a file list operation.
      properties:
        object:
          type: string
          description: The object type, which is always 'list'.
          enum:
          - list
          x-ms-enum:
            modelAsString: false
        data:
          type: array
          description: The files returned for the request.
          items:
            $ref: '#/components/schemas/FileInfo'
      required:
      - object
      - data
    FileInfo:
      type: object
      description: Represents an agent that can call the model and use tools.
      properties:
        object:
          type: string
          description: The object type, which is always 'file'.
          enum:
          - file
          x-ms-enum:
            modelAsString: false
        id:
          type: string
          description: The identifier, which can be referenced in API endpoints.
        bytes:
          type: integer
          format: int32
          description: The size of the file, in bytes.
        filename:
          type: string
          description: The name of the file.
        created_at:
          type: integer
          format: unixtime
          description: The Unix timestamp, in seconds, representing when this object was created.
          x-ms-client-name: createdAt
        purpose:
          $ref: '#/components/schemas/FilePurpose'
          description: The intended purpose of a file.
        status:
          $ref: '#/components/schemas/FileState'
          description: The state of the file. This field is available in Azure OpenAI only.
        status_details:
          type: string
          description: The error message with details in case processing of this file failed. This field is available in Azure OpenAI only.
          x-ms-client-name: statusDetails
      required:
      - object
      - id
      - bytes
      - filename
      - created_at
      - purpose
    AgentV1Error:
      type: object
      description: Error payload returned by the agents API.
      properties:
        error:
          $ref: '#/components/schemas/AgentErrorDetail'
          description: Represents the error.
      required:
      - error
  parameters:
    Azure.Core.Foundations.ApiVersionParameter:
      name: api-version
      in: query
      description: The API version to use for this operation.
      required: true
      x-ms-parameter-location: method
      x-ms-client-name: apiVersion
      schema:
        type: string
        minLength: 1
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            https://ai.azure.com/.default: ''
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    in: path
    description: 'Project endpoint in the form of: https://<aiservices-id>.services.ai.azure.com/api/projects/<project-name>'
    required: true
    type: string
    format: uri
    x-ms-skip-url-encoding: true