Azure OpenAI Service Files: API

The Files: API from Azure OpenAI Service — 4 operation(s) for files:.

GitHub OpenAPI

Operations 6

GET /files Gets a list of all files owned by the Azure OpenAI resource. #
POST /files Creates a new file entity by uploading data from a local machine. #
GET /files/{file-id} Gets details for a single file specified by the given file-id including status… #
DELETE /files/{file-id} Deletes the file with the given file-id. #
GET /files/{file-id}/content Gets the content of the file specified by the given file-id. #
POST /files/import Creates a new file entity by importing data from a provided url. #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/microsoft-azure-openai:microsoft-azure-openai-files-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

microsoft-azure-openai-files-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: 'Azure OpenAI API version 2024-10-21 Files: API'
  description: APIs for fine-tuning and managing deployments of OpenAI models.
  version: '2024-10-21'
security:
- api-key: []
tags:
- name: Files
paths:
  /files:
    get:
      tags:
      - Files
      summary: Gets a list of all files owned by the Azure OpenAI resource.
      operationId: Files_List
      parameters:
      - in: query
        name: purpose
        description: Only return files with the given purpose.
        x-ms-enum:
          name: Purpose
          modelAsString: true
          values:
          - value: fine-tune
            description: This file contains training data for a fine tune job.
          - value: fine-tune-results
            description: This file contains the results of a fine tune job.
          - value: assistants
            description: This file contains data to be used in assistants.
          - value: assistants_output
            description: This file contains the results of an assistant.
          - value: batch
            description: This file contains the input data for a batch.
          - value: batch_output
            description: This file contains the results of a batch.
        schema:
          type: string
          enum:
          - fine-tune
          - fine-tune-results
          - assistants
          - assistants_output
          - batch
          - batch_output
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileList'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - Files
      summary: Creates a new file entity by uploading data from a local machine.
      operationId: Files_Upload
      parameters:
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '201':
          description: The file has been successfully created.
          headers:
            Location:
              description: The location of the newly created item.
              schema:
                type: string
                format: url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                purpose:
                  type: string
                  enum:
                  - fine-tune
                  - fine-tune-results
                  - assistants
                  - assistants_output
                  - batch
                  description: The intended purpose of the uploaded documents. Use "fine-tune" for fine-tuning. This allows us to validate the format of the uploaded file.
                file:
                  type: string
                  description: Gets or sets the file to upload into Azure OpenAI.
                  format: binary
              required:
              - purpose
              - file
  /files/{file-id}:
    get:
      tags:
      - Files
      summary: Gets details for a single file specified by the given file-id including status…
      operationId: Files_Get
      parameters:
      - in: path
        name: file-id
        description: The identifier of the file.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Files
      summary: Deletes the file with the given file-id.
      operationId: Files_Delete
      parameters:
      - in: path
        name: file-id
        description: The identifier of the file.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: The file was successfully deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDelete'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /files/{file-id}/content:
    get:
      tags:
      - Files
      summary: Gets the content of the file specified by the given file-id.
      operationId: Files_GetContent
      parameters:
      - in: path
        name: file-id
        description: The identifier of the file.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: Success
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: string
                format: binary
        default:
          description: An error occurred.
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /files/import:
    post:
      tags:
      - Files
      summary: Creates a new file entity by importing data from a provided url.
      operationId: Files_Import
      parameters:
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '201':
          description: The file has been successfully created.
          headers:
            Location:
              description: The location of the newly created item.
              schema:
                type: string
                format: url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileImport'
        description: The definition of the file to create including its purpose, the file name and the url of the file location.
        required: true
components:
  schemas:
    ErrorCode:
      title: ErrorCode
      description: 'Error codes as defined in the Microsoft REST guidelines

        (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).'
      enum:
      - conflict
      - invalidPayload
      - forbidden
      - notFound
      - unexpectedEntityState
      - itemDoesAlreadyExist
      - serviceUnavailable
      - internalFailure
      - quotaExceeded
      - jsonlValidationFailed
      - fileImportFailed
      - tooManyRequests
      - unauthorized
      - contentFilter
      type: string
      x-ms-enum:
        name: ErrorCode
        modelAsString: true
        values:
        - value: conflict
          description: The requested operation conflicts with the current resource state.
        - value: invalidPayload
          description: The request data is invalid for this operation.
        - value: forbidden
          description: The operation is forbidden for the current user/api key.
        - value: notFound
          description: The resource is not found.
        - value: unexpectedEntityState
          description: The operation cannot be executed in the current resource's state.
        - value: itemDoesAlreadyExist
          description: The item does already exist.
        - value: serviceUnavailable
          description: The service is currently not available.
        - value: internalFailure
          description: Internal error. Please retry.
        - value: quotaExceeded
          description: Quota exceeded.
        - value: jsonlValidationFailed
          description: Validation of jsonl data failed.
        - value: fileImportFailed
          description: Import of file failed.
        - value: tooManyRequests
          description: Too many requests. Please retry later.
        - value: unauthorized
          description: The current user/api key is not authorized for the operation.
        - value: contentFilter
          description: Image generation failed as a result of our safety system.
    FileState:
      title: FileState
      description: The state of a file.
      enum:
      - uploaded
      - pending
      - running
      - processed
      - error
      - deleting
      - deleted
      type: string
      readOnly: true
      x-ms-enum:
        name: FileState
        modelAsString: true
        values:
        - 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.
        - 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.
        - value: running
          description: The operation has started to be processed. It can be categorized as an active state.
        - value: processed
          description: The operation has successfully be processed and is ready for consumption. It can be categorized as a terminal state.
        - value: error
          description: The operation has completed processing with a failure and cannot be further consumed. It can be categorized as a terminal state.
        - value: deleting
          description: The entity is ni 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.
        - 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.
    FileDelete:
      title: FileDelete
      description: Defines the response for File Delete.
      required:
      - deleted
      - id
      type: object
      properties:
        object:
          $ref: '#/components/schemas/TypeDiscriminator'
        deleted:
          description: A value indicating whether gets if the file was deleted.
          type: boolean
        id:
          description: The file-id that was deleted.
          minLength: 1
          type: string
    TypeDiscriminator:
      title: TypeDiscriminator
      description: Defines the type of an object.
      enum:
      - list
      - fine_tuning.job
      - file
      - fine_tuning.job.event
      - fine_tuning.job.checkpoint
      - model
      - batch
      - upload
      - upload.part
      type: string
      readOnly: true
      x-ms-enum:
        name: TypeDiscriminator
        modelAsString: true
        values:
        - value: list
          description: This object represents a list of other objects.
        - value: fine_tuning.job
          description: This object represents a fine tune job.
        - value: file
          description: This object represents a file.
        - value: fine_tuning.job.event
          description: This object represents an event of a fine tuning job.
        - value: fine_tuning.job.checkpoint
          description: This object represents a checkpoint of a fine tuning job.
        - value: model
          description: This object represents a model (can be a base model or fine tune job result).
        - value: batch
          description: This object represents a batch.
        - value: upload
          description: This object represents a file upload.
        - value: upload.part
          description: This object represents part of a file upload.
    File:
      title: File
      description: A file is a document usable for training and validation. It can also be a service generated document with result details.
      required:
      - filename
      - purpose
      type: object
      properties:
        object:
          $ref: '#/components/schemas/TypeDiscriminator'
        created_at:
          format: unixtime
          description: A timestamp when this job or item was created (in unix epochs).
          type: integer
          readOnly: true
        id:
          description: The identity of this item.
          type: string
          readOnly: true
        status:
          $ref: '#/components/schemas/FileState'
        bytes:
          format: int64
          description: 'The size of this file when available (can be null). File sizes larger than 2^53-1 are not supported to ensure compatibility

            with JavaScript integers.'
          type: integer
          readOnly: true
        purpose:
          $ref: '#/components/schemas/Purpose'
        filename:
          description: The name of the file.
          minLength: 1
          type: string
        status_details:
          description: The error message with details in case processing of this file failed.
          type: string
          readOnly: true
      readOnly: true
    ErrorResponse:
      title: ErrorResponse
      description: 'Error response as defined in the Microsoft REST guidelines

        (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).'
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Purpose:
      title: Purpose
      description: The intended purpose of the uploaded documents. Use "fine-tune" for fine-tuning. This allows us to validate the format of the uploaded file.
      enum:
      - fine-tune
      - fine-tune-results
      - assistants
      - assistants_output
      - batch
      - batch_output
      type: string
      readOnly: true
      x-ms-enum:
        name: Purpose
        modelAsString: true
        values:
        - value: fine-tune
          description: This file contains training data for a fine tune job.
        - value: fine-tune-results
          description: This file contains the results of a fine tune job.
        - value: assistants
          description: This file contains data to be used in assistants.
        - value: assistants_output
          description: This file contains the results of an assistant.
        - value: batch
          description: This file contains the input data for a batch.
        - value: batch_output
          description: This file contains the results of a batch.
    Error:
      title: Error
      description: 'Error content as defined in the Microsoft REST guidelines

        (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).'
      required:
      - code
      - message
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          description: The message of this error.
          minLength: 1
          type: string
        target:
          description: The location where the error happened if available.
          type: string
        details:
          description: The error details if available.
          type: array
          items:
            $ref: '#/components/schemas/Error'
        innererror:
          $ref: '#/components/schemas/InnerError'
      readOnly: true
    InnerError:
      title: InnerError
      description: 'Inner error as defined in the Microsoft REST guidelines

        (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).'
      type: object
      properties:
        code:
          $ref: '#/components/schemas/InnerErrorCode'
        innererror:
          $ref: '#/components/schemas/InnerError'
    InnerErrorCode:
      title: InnerErrorCode
      description: 'Inner error codes as defined in the Microsoft REST guidelines

        (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).'
      enum:
      - invalidPayload
      type: string
      x-ms-enum:
        name: InnerErrorCode
        modelAsString: true
        values:
        - value: invalidPayload
          description: The request data is invalid for this operation.
    FileImport:
      title: FileImport
      description: Defines a document to import from an external content url to be usable with Azure OpenAI.
      required:
      - content_url
      - filename
      - purpose
      type: object
      properties:
        purpose:
          $ref: '#/components/schemas/Purpose'
        filename:
          description: 'The name of the [JSON Lines](https://jsonlines.readthedocs.io/en/latest/) file to be uploaded.

            If the `purpose` is set to "fine-tune", each line is a JSON record with "prompt" and "completion" fields representing your training examples.'
          minLength: 1
          type: string
        content_url:
          format: url
          description: The url to download the document from (can be SAS url of a blob or any other external url accessible with a GET request).
          type: string
    FileList:
      title: FileList
      description: Represents a list of files.
      type: object
      properties:
        object:
          $ref: '#/components/schemas/TypeDiscriminator'
        data:
          description: The list of items.
          type: array
          items:
            $ref: '#/components/schemas/File'
  parameters:
    apiVersionQueryParameter:
      in: query
      name: api-version
      description: The requested API version.
      required: true
      x-ms-client-default: '2024-10-21'
      x-ms-parameter-location: client
      schema:
        type: string
  securitySchemes:
    api-key:
      type: apiKey
      name: api-key
      in: header
      description: Provide your Cognitive Services Azure OpenAI account key here.
x-ms-parameterized-host:
  hostTemplate: '{endpoint}/openai'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/endpoint'