Anthropic Files API

openapi: 3.2.0
info:
  title: Anthropic Files API
servers:
- url: https://api.anthropic.com
tags:
- name: Files
paths:
  /v1/files:
    post:
      summary: Upload File
      operationId: upload_file_v1_files_post
      parameters:
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
          description: 'The version of the Claude API you want to use.


            Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
          title: Anthropic-Version
        description: 'The version of the Claude API you want to use.


          Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileMetadataSchema'
        4XX:
          description: 'Error response.


            See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                expires_in_seconds:
                  type: integer
                  minimum: 3600
                  maximum: 7776000
                  description: Seconds from upload until the file expires and its bytes become permanently unavailable. Must be between 3600 (one hour) and 7776000 (ninety days).
              required:
              - file
        required: true
      tags:
      - Files
    get:
      summary: List Files
      operationId: list_files_v1_files_get
      parameters:
      - name: page
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Opaque page cursor returned in a prior list response's `next_page`. Prefixed `page_`.
          title: Page
        description: Opaque page cursor returned in a prior list response's `next_page`. Prefixed `page_`.
      - name: ids[]
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Restrict the result set to Files whose `id` is in this list. At most 100 entries (after de-duplication). Mutually exclusive with `page` and `limit`. When supplied, the response is always a single page (`next_page` is null). IDs that do not resolve to a visible File — including deleted Files — are silently omitted.
          title: Ids[]
        description: Restrict the result set to Files whose `id` is in this list. At most 100 entries (after de-duplication). Mutually exclusive with `page` and `limit`. When supplied, the response is always a single page (`next_page` is null). IDs that do not resolve to a visible File — including deleted Files — are silently omitted.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: 'Number of items to return per page.


            Defaults to `20`. Ranges from `1` to `1000`.'
          default: 20
          title: Limit
        description: 'Number of items to return per page.


          Defaults to `20`. Ranges from `1` to `1000`.'
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
          description: 'The version of the Claude API you want to use.


            Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
          title: Anthropic-Version
        description: 'The version of the Claude API you want to use.


          Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
      - name: x-api-key
        in: header
        required: false
        schema:
          type: string
          description: 'Your unique API key for authentication.


            This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
          title: X-Api-Key
        description: 'Your unique API key for authentication.


          This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListResponse'
        4XX:
          description: 'Error response.


            See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Files
  /v1/files/{file_id}:
    get:
      summary: Get File Metadata
      operationId: get_file_metadata_v1_files__file_id__get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          description: ID of the File.
          title: File Id
        description: ID of the File.
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
          description: 'The version of the Claude API you want to use.


            Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
          title: Anthropic-Version
        description: 'The version of the Claude API you want to use.


          Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
      - name: x-api-key
        in: header
        required: false
        schema:
          type: string
          description: 'Your unique API key for authentication.


            This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
          title: X-Api-Key
        description: 'Your unique API key for authentication.


          This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileMetadataSchema'
        4XX:
          description: 'Error response.


            See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Files
    delete:
      summary: Delete File
      operationId: delete_file_v1_files__file_id__delete
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          description: ID of the File.
          title: File Id
        description: ID of the File.
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
          description: 'The version of the Claude API you want to use.


            Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
          title: Anthropic-Version
        description: 'The version of the Claude API you want to use.


          Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
      - name: x-api-key
        in: header
        required: false
        schema:
          type: string
          description: 'Your unique API key for authentication.


            This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
          title: X-Api-Key
        description: 'Your unique API key for authentication.


          This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDeleteResponse'
        4XX:
          description: 'Error response.


            See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Files
  /v1/files/{file_id}/content:
    get:
      summary: Download File
      operationId: download_file_v1_files__file_id__content_get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          description: ID of the File.
          title: File Id
        description: ID of the File.
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
          description: 'The version of the Claude API you want to use.


            Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
          title: Anthropic-Version
        description: 'The version of the Claude API you want to use.


          Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
      - name: x-api-key
        in: header
        required: false
        schema:
          type: string
          description: 'Your unique API key for authentication.


            This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
          title: X-Api-Key
        description: 'Your unique API key for authentication.


          This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
      responses:
        '200':
          description: Successful Response
          content:
            application/octet-stream:
              schema:
                type: string
        4XX:
          description: 'Error response.


            See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.'
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Files
  /v1/files/{file_id}/content?beta=true:
    get:
      summary: Download File
      operationId: beta_download_file_v1_files__file_id__content_get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          description: ID of the File.
          title: File Id
        description: ID of the File.
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
          items:
            type: string
          description: 'Optional header to specify the beta version(s) you want to use.


            To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.'
          title: Anthropic-Beta
          x-stainless-override-schema:
            x-stainless-param: betas
            x-stainless-extend-default: true
            type: array
            description: Optional header to specify the beta version(s) you want to use.
            items:
              $ref: '#/components/schemas/AnthropicBeta'
        description: 'Optional header to specify the beta version(s) you want to use.


          To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.'
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
          description: 'The version of the Claude API you want to use.


            Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
          title: Anthropic-Version
        description: 'The version of the Claude API you want to use.


          Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
      - name: x-api-key
        in: header
        required: false
        schema:
          type: string
          description: 'Your unique API key for authentication.


            This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
          title: X-Api-Key
        description: 'Your unique API key for authentication.


          This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
      responses:
        '200':
          description: Successful Response
          content:
            application/octet-stream:
              schema:
                type: string
        4XX:
          description: 'Error response.


            See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.'
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
      tags:
      - Files
  /v1/files/{file_id}?beta=true:
    get:
      summary: Get File Metadata
      operationId: beta_get_file_metadata_v1_files__file_id__get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          description: ID of the File.
          title: File Id
        description: ID of the File.
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
          items:
            type: string
          description: 'Optional header to specify the beta version(s) you want to use.


            To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.'
          title: Anthropic-Beta
          x-stainless-override-schema:
            x-stainless-param: betas
            x-stainless-extend-default: true
            type: array
            description: Optional header to specify the beta version(s) you want to use.
            items:
              $ref: '#/components/schemas/AnthropicBeta'
        description: 'Optional header to specify the beta version(s) you want to use.


          To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.'
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
          description: 'The version of the Claude API you want to use.


            Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
          title: Anthropic-Version
        description: 'The version of the Claude API you want to use.


          Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
      - name: x-api-key
        in: header
        required: false
        schema:
          type: string
          description: 'Your unique API key for authentication.


            This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
          title: X-Api-Key
        description: 'Your unique API key for authentication.


          This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaFileMetadataSchema'
        4XX:
          description: 'Error response.


            See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
      tags:
      - Files
    delete:
      summary: Delete File
      operationId: beta_delete_file_v1_files__file_id__delete
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          description: ID of the File.
          title: File Id
        description: ID of the File.
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
          items:
            type: string
          description: 'Optional header to specify the beta version(s) you want to use.


            To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.'
          title: Anthropic-Beta
          x-stainless-override-schema:
            x-stainless-param: betas
            x-stainless-extend-default: true
            type: array
            description: Optional header to specify the beta version(s) you want to use.
            items:
              $ref: '#/components/schemas/AnthropicBeta'
        description: 'Optional header to specify the beta version(s) you want to use.


          To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.'
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
          description: 'The version of the Claude API you want to use.


            Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
          title: Anthropic-Version
        description: 'The version of the Claude API you want to use.


          Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).'
      - name: x-api-key
        in: header
        required: false
        schema:
          type: string
          description: 'Your unique API key for authentication.


            This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
          title: X-Api-Key
        description: 'Your unique API key for authentication.


          This key is required in the header of all API requests, to authenticate your account and access Anthropic''s services. Get your API key through the [Console](https://console.anthropic.com/settings/keys). Each key is scoped to a Workspace.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaFileDeleteResponse'
        4XX:
          description: 'Error response.


            See our [errors documentation](https://platform.claude.com/docs/en/api/errors) for more details.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
      tags:
      - Files
components:
  schemas:
    BetaGatewayTimeoutError:
      properties:
        message:
          default: Request timeout
          title: Message
          type: string
        type:
          const: timeout_error
          default: timeout_error
          title: Type
          type: string
      required:
      - message
      - type
      title: GatewayTimeoutError
      type: object
    FileMetadataSchema:
      properties:
        created_at:
          description: RFC 3339 datetime string representing when the file was created.
          examples:
          - '2025-04-15T18:37:24.100435Z'
          format: date-time
          title: Created At
          type: string
        downloadable:
          default: false
          description: Whether the file can be downloaded.
          examples:
          - false
          title: Downloadable
          type: boolean
        expires_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.
          examples:
          - '2025-05-15T18:37:24.100435Z'
          title: Expires At
        filename:
          description: Original filename of the uploaded file.
          examples:
          - document.pdf
          maxLength: 500
          minLength: 1
          title: Filename
          type: string
        id:
          description: 'Unique object identifier.


            The format and length of IDs may change over time.'
          examples:
          - file_011CNha8iCJcU1wXNR6q4V8w
          title: Id
          type: string
        mime_type:
          description: MIME type of the file.
          examples:
          - application/pdf
          maxLength: 255
          minLength: 1
          title: Mime Type
          type: string
        size_bytes:
          description: Size of the file in bytes.
          examples:
          - 102400
          minimum: 0
          title: Size Bytes
          type: integer
        type:
          const: file
          description: 'Object type.


            For files, this is always `"file"`.'
          title: Type
          type: string
      required:
      - created_at
      - filename
      - id
      - mime_type
      - size_bytes
      - type
      title: FileMetadataSchema
      type: object
    BetaOverloadedError:
      properties:
        message:
          default: Overloaded
          title: Message
          type: string
        type:
          const: overloaded_error
          default: overloaded_error
          title: Type
          type: string
      required:
      - message
      - type
      title: OverloadedError
      type: object
    BetaBillingError:
      properties:
        message:
          default: Billing error
          title: Message
          type: string
        type:
          const: billing_error
          default: billing_error
          title: Type
          type: string
      required:
      - message
      - type
      title: BillingError
      type: object
    FileDeleteResponse:
      properties:
        id:
          type: string
          title: Id
          description: ID of the deleted file.
          examples:
          - file_011CNha8iCJcU1wXNR6q4V8w
        type:
          type: string
          const: file_deleted
          title: Type
          description: 'Deleted object type.


            For file deletion, this is always `"file_deleted"`.'
          default: file_deleted
      type: object
      required:
      - id
      title: FileDeleteResponse
    PermissionError:
      properties:
        message:
          default: Permission denied
          title: Message
          type: string
        type:
          const: permission_error
          default: permission_error
          title: Type
          type: string
      required:
      - message
      - type
      title: PermissionError
      type: object
    NotFoundError:
      properties:
        message:
          default: Not found
          title: Message
          type: string
        type:
          const: not_found_error
          default: not_found_error
          title: Type
          type: string
      required:
      - message
      - type
      title: NotFoundError
      type: object
    BetaAuthenticationError:
      properties:
        message:
          default: Authentication error
          title: Message
          type: string
        type:
          const: authentication_error
          default: authentication_error
          title: Type
          type: string
      required:
      - message
      - type
      title: AuthenticationError
      type: object
    BillingError:
      properties:
        message:
          default: Billing error
          title: Message
          type: string
        type:
          const: billing_error
          default: billing_error
          title: Type
          type: string
      required:
      - message
      - type
      title: BillingError
      type: object
    BetaNotFoundError:
      properties:
        message:
          default: Not found
          title: Message
          type: string
        type:
          const: not_found_error
          default: not_found_error
          title: Type
          type: string
      required:
      - message
      - type
      title: NotFoundError
      type: object
    ErrorResponse:
      properties:
        error:
          discriminator:
            mapping:
              api_error: '#/components/schemas/APIError'
              authentication_error: '#/components/schemas/AuthenticationError'
              billing_error: '#/components/schemas/BillingError'
              invalid_request_error: '#/components/schemas/InvalidRequestError'
              not_found_error: '#/components/schemas/NotFoundError'
              overloaded_error: '#/components/schemas/OverloadedError'
              permission_error: '#/components/schemas/PermissionError'
              rate_limit_error: '#/components/schemas/RateLimitError'
              timeout_error: '#/components/schemas/GatewayTimeoutError'
            propertyName: type
          oneOf:
          - $ref: '#/components/schemas/InvalidRequestError'
          - $ref: '#/components/schemas/AuthenticationError'
          - $ref: '#/components/schemas/BillingError'
          - $ref: '#/components/schemas/PermissionError'
          - $ref: '#/components/schemas/NotFoundError'
          - $ref: '#/components/schemas/RateLimitError'
          - $ref: '#/components/schemas/GatewayTimeoutError'
          - $ref: '#/components/schemas/APIError'
          - $ref: '#/components/schemas/OverloadedError'
          title: Error
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Request Id
        type:
          const: error
          default: error
          title: Type
          type: string
      required:
      - error
      - request_id
      - type
      title: ErrorResponse
      type: object
    GatewayTimeoutError:
      properties:
        message:
          default: Request timeout
          title: Message
          type: string
        type:
          const: timeout_error
          default: timeout_error
          title: Type
          type: string
      required:
      - message
      - type
      title: GatewayTimeoutError
      type: object
    BetaInvalidRequestError:
      properties:
        message:
          default: Invalid request
          title: Message
          type: string
        type:
          const: invalid_request_error
          default: invalid_request_error
          title: Type
          type: string
      required:
      - message
      - type
      title: InvalidRequestError
      type: object
    BetaPermissionError:
      properties:
        message:
          default: Permission denied
          title: Message
          type: string
        type:
          const: permission_error
          default: permission_error
          title: Type
          type: string
      required:
      - message
      - type
      title: PermissionError
      type: object
    BetaFileScope:
      properties:
        id:
          description: The ID of the scoping resource (e.g., the session ID).
          title: Id
          type: string
        type:
          const: session
          description: The type of scope (e.g., `"session"`).
          title: Type
          type: string
      required:
      - id
      - type
      title: FileScope
      type: object
    APIError:
      properties:
        message:
          default: Internal server error
          title: Message
          type: string
        type:
          const: api_error
          default: api_error
          title: Type
          type: string
      required:
      - message
      - type
      title: APIError
      type: object
    BetaFileMetadataSchema:
      properties:
        created_at:
          description: RFC 3339 datetime string representing when the file was created.
          examples:
          - '2025-04-15T18:37:24.100435Z'
          format: date-time
          title: Created At
          type: string
        downloadable:
          default: false
          description: Whether the file can be downloaded.
          examples:
          - false
          title: Downloadable
          type: boolean
        filename:
          description: Original filename of the uploaded file.
          examples:
          - document.pdf
          maxLength: 500
          minLength: 1
          title: Filename
          type: string
        id:
          description: 'Unique object identifier.


            The format and length of IDs may change over time.'
          examples:
          - file_011CNha8iCJcU1wXNR6q4V8w
          title: Id
          type: string
        mime_type:
          description: MIME type of the file.
          examples:
          - application/pdf
          maxLength: 255
          minLength: 1
          title: Mime Type
          type: string
        scope:
          anyOf:
          - $ref: '#/components/schemas/BetaFileScope'
          - type: 'null'
          default: null
          description: The scope of this file, indicating the context in which it was created (e.g., a session).
        size_bytes:
          description: Size of the file in bytes.
          examples:
          - 102400
          minimum: 0
          title: Size Bytes
          type: integer
        type:
          const: file
          description: 'Object type.


            For files, this is always `"file"`.'
          title: Type
          type: string
      required:
      - created_at
      - filename
      - id
      - mime_type
      - size_bytes
      - type
      title: FileMetadataSchema
      type: object
    FileListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/FileMetadataSchema'
          type: array
          title: Data
          description: List of file metadata objects.
        next_page:
          anyOf:
          - type: string
     

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/anthropic/refs/heads/main/openapi/anthropic-files-api-openapi.yml