Box Files API — Files

naftiko: 1.0.0-alpha2
info:
  label: Box Files API — Files
  description: 'Box Files API — Files. 47 operations. Lead operation: Box Preflight check before upload. Self-contained Naftiko
    capability covering one Box business surface.'
  tags:
  - Box
  - Files
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    BOX_API_KEY: BOX_API_KEY
capability:
  consumes:
  - type: http
    namespace: files-files
    baseUri: ''
    description: Box Files API — Files business capability. Self-contained, no shared references.
    resources:
    - name: files-content
      path: /files/content
      operations:
      - name: optionsfilescontent
        method: OPTIONS
        description: Box Preflight check before upload
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: postfilescontent
        method: POST
        description: Box Upload file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: content-md5
          in: header
          type: string
          description: An optional header containing the SHA1 hash of the file to
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-upload_sessions
      path: /files/upload_sessions
      operations:
      - name: postfilesuploadsessions
        method: POST
        description: Box Create upload session
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-upload_sessions-upload_session_id
      path: /files/upload_sessions/{upload_session_id}
      operations:
      - name: getfilesuploadsessionsid
        method: GET
        description: Box Get upload session
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: upload_session_id
          in: path
          type: string
          description: The ID of the upload session.
          required: true
      - name: putfilesuploadsessionsid
        method: PUT
        description: Box Upload part of file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: upload_session_id
          in: path
          type: string
          description: The ID of the upload session.
          required: true
        - name: digest
          in: header
          type: string
          description: The [RFC3230][1] message digest of the chunk uploaded.
          required: true
        - name: content-range
          in: header
          type: string
          description: The byte range of the chunk.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: deletefilesuploadsessionsid
        method: DELETE
        description: Box Remove upload session
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: upload_session_id
          in: path
          type: string
          description: The ID of the upload session.
          required: true
    - name: files-upload_sessions-upload_session_id-commit
      path: /files/upload_sessions/{upload_session_id}/commit
      operations:
      - name: postfilesuploadsessionsidcommit
        method: POST
        description: Box Commit upload session
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: upload_session_id
          in: path
          type: string
          description: The ID of the upload session.
          required: true
        - name: digest
          in: header
          type: string
          description: The [RFC3230][1] message digest of the whole file.
          required: true
        - name: if-match
          in: header
          type: string
          description: Ensures this item hasn't recently changed before
        - name: if-none-match
          in: header
          type: string
          description: Ensures an item is only returned if it has changed.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-upload_sessions-upload_session_id-parts
      path: /files/upload_sessions/{upload_session_id}/parts
      operations:
      - name: getfilesuploadsessionsidparts
        method: GET
        description: Box List parts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: upload_session_id
          in: path
          type: string
          description: The ID of the upload session.
          required: true
        - name: offset
          in: query
          type: integer
          description: The offset of the item at which to begin the response.
        - name: limit
          in: query
          type: integer
          description: The maximum number of items to return per page.
    - name: files-file_id
      path: /files/{file_id}
      operations:
      - name: getfilesid
        method: GET
        description: Box Get file information
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: if-none-match
          in: header
          type: string
          description: Ensures an item is only returned if it has changed.
        - name: boxapi
          in: header
          type: string
          description: The URL, and optional password, for the shared link of this item.
        - name: x-rep-hints
          in: header
          type: string
          description: A header required to request specific `representations`
      - name: postfilesid
        method: POST
        description: Box Restore file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: putfilesid
        method: PUT
        description: Box Update file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: if-match
          in: header
          type: string
          description: Ensures this item hasn't recently changed before
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: deletefilesid
        method: DELETE
        description: Box Delete file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: if-match
          in: header
          type: string
          description: Ensures this item hasn't recently changed before
    - name: files-file_id}#add_shared_link
      path: /files/{file_id}#add_shared_link
      operations:
      - name: putfilesidaddsharedlink
        method: PUT
        description: Box Add shared link to file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: string
          description: Explicitly request the `shared_link` fields
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-file_id}#get_shared_link
      path: /files/{file_id}#get_shared_link
      operations:
      - name: getfilesidgetsharedlink
        method: GET
        description: Box Get shared link for file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: string
          description: Explicitly request the `shared_link` fields
          required: true
    - name: files-file_id}#remove_shared_link
      path: /files/{file_id}#remove_shared_link
      operations:
      - name: putfilesidremovesharedlink
        method: PUT
        description: Box Remove shared link from file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: string
          description: Explicitly request the `shared_link` fields
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-file_id}#update_shared_link
      path: /files/{file_id}#update_shared_link
      operations:
      - name: putfilesidupdatesharedlink
        method: PUT
        description: Box Update shared link on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: string
          description: Explicitly request the `shared_link` fields
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-file_id-collaborations
      path: /files/{file_id}/collaborations
      operations:
      - name: getfilesidcollaborations
        method: GET
        description: Box List file collaborations
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: limit
          in: query
          type: integer
          description: The maximum number of items to return per page.
        - name: marker
          in: query
          type: string
          description: Defines the position marker at which to begin returning results. This is
    - name: files-file_id-comments
      path: /files/{file_id}/comments
      operations:
      - name: getfilesidcomments
        method: GET
        description: Box List file comments
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: limit
          in: query
          type: integer
          description: The maximum number of items to return per page.
        - name: offset
          in: query
          type: integer
          description: The offset of the item at which to begin the response.
    - name: files-file_id-content
      path: /files/{file_id}/content
      operations:
      - name: getfilesidcontent
        method: GET
        description: Box Download file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: range
          in: header
          type: string
          description: The byte range of the content to download.
        - name: boxapi
          in: header
          type: string
          description: The URL, and optional password, for the shared link of this item.
        - name: version
          in: query
          type: string
          description: The file version to download
        - name: access_token
          in: query
          type: string
          description: An optional access token that can be used to pre-authenticate this request, which means that a download
            link can be shared with a browser or a third party servi
      - name: postfilesidcontent
        method: POST
        description: Box Upload file version
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: if-match
          in: header
          type: string
          description: Ensures this item hasn't recently changed before
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: content-md5
          in: header
          type: string
          description: An optional header containing the SHA1 hash of the file to
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-file_id-copy
      path: /files/{file_id}/copy
      operations:
      - name: postfilesidcopy
        method: POST
        description: Box Copy file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-file_id-metadata
      path: /files/{file_id}/metadata
      operations:
      - name: getfilesidmetadata
        method: GET
        description: Box List metadata instances on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
    - name: files-file_id-metadata-enterprise-securityClassification-6VMVochwUWo
      path: /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo
      operations:
      - name: getfilesidmetadataenterprisesecurityclassification6vmvochwuwo
        method: GET
        description: Box Get classification on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
      - name: postfilesidmetadataenterprisesecurityclassification6vmvochwuwo
        method: POST
        description: Box Add classification to file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: putfilesidmetadataenterprisesecurityclassification6vmvochwuwo
        method: PUT
        description: Box Update classification on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: deletefilesidmetadataenterprisesecurityclassification6vmvochwuwo
        method: DELETE
        description: Box Remove classification from file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
    - name: files-file_id-metadata-global-boxSkillsCards
      path: /files/{file_id}/metadata/global/boxSkillsCards
      operations:
      - name: getfilesidmetadataglobalboxskillscards
        method: GET
        description: List Box Skill cards on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
      - name: postfilesidmetadataglobalboxskillscards
        method: POST
        description: Create Box Skill cards on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: putfilesidmetadataglobalboxskillscards
        method: PUT
        description: Update Box Skill cards on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: deletefilesidmetadataglobalboxskillscards
        method: DELETE
        description: Remove Box Skill cards from file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
    - name: files-file_id-metadata-scope-template_key
      path: /files/{file_id}/metadata/{scope}/{template_key}
      operations:
      - name: getfilesidmetadataidid
        method: GET
        description: Box Get metadata instance on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: scope
          in: path
          type: string
          description: The scope of the metadata template
          required: true
        - name: template_key
          in: path
          type: string
          description: The name of the metadata template
          required: true
      - name: postfilesidmetadataidid
        method: POST
        description: Box Create metadata instance on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: scope
          in: path
          type: string
          description: The scope of the metadata template
          required: true
        - name: template_key
          in: path
          type: string
          description: The name of the metadata template
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: putfilesidmetadataidid
        method: PUT
        description: Box Update metadata instance on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: scope
          in: path
          type: string
          description: The scope of the metadata template
          required: true
        - name: template_key
          in: path
          type: string
          description: The name of the metadata template
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: deletefilesidmetadataidid
        method: DELETE
        description: Box Remove metadata instance from file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: scope
          in: path
          type: string
          description: The scope of the metadata template
          required: true
        - name: template_key
          in: path
          type: string
          description: The name of the metadata template
          required: true
    - name: files-file_id-tasks
      path: /files/{file_id}/tasks
      operations:
      - name: getfilesidtasks
        method: GET
        description: Box List tasks on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
    - name: files-file_id-thumbnail.{extension}
      path: /files/{file_id}/thumbnail.{extension}
      operations:
      - name: getfilesidthumbnailid
        method: GET
        description: Box Get file thumbnail
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: extension
          in: path
          type: string
          description: The file format for the thumbnail
          required: true
        - name: min_height
          in: query
          type: integer
          description: The minimum height of the thumbnail
        - name: min_width
          in: query
          type: integer
          description: The minimum width of the thumbnail
        - name: max_height
          in: query
          type: integer
          description: The maximum height of the thumbnail
        - name: max_width
          in: query
          type: integer
          description: The maximum width of the thumbnail
    - name: files-file_id-trash
      path: /files/{file_id}/trash
      operations:
      - name: getfilesidtrash
        method: GET
        description: Box Get trashed file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
      - name: deletefilesidtrash
        method: DELETE
        description: Box Permanently remove file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
    - name: files-file_id-upload_sessions
      path: /files/{file_id}/upload_sessions
      operations:
      - name: postfilesiduploadsessions
        method: POST
        description: Box Create upload session for existing file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-file_id-versions
      path: /files/{file_id}/versions
      operations:
      - name: getfilesidversions
        method: GET
        description: Box List all file versions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: limit
          in: query
          type: integer
          description: The maximum number of items to return per page.
        - name: offset
          in: query
          type: integer
          description: The offset of the item at which to begin the response.
    - name: files-file_id-versions-current
      path: /files/{file_id}/versions/current
      operations:
      - name: postfilesidversionscurrent
        method: POST
        description: Box Promote file version
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-file_id-versions-file_version_id
      path: /files/{file_id}/versions/{file_version_id}
      operations:
      - name: getfilesidversionsid
        method: GET
        description: Box Get file version
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: fields
          in: query
          type: array
          description: A comma-separated list of attributes to include in the
        - name: file_version_id
          in: path
          type: string
          description: The ID of the file version
          required: true
      - name: deletefilesidversionsid
        method: DELETE
        description: Box Remove file version
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: file_version_id
          in: path
          type: string
          description: The ID of the file version
          required: true
        - name: if-match
          in: header
          type: string
          description: Ensures this item hasn't recently changed before
      - name: putfilesidversionsid
        method: PUT
        description: Box Restore file version
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: file_id
          in: path
          type: string
          description: The unique identifier that represents a file.
          required: true
        - name: file_version_id
          in: path
          type: string
          description: The ID of the file version
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: files-file_id-watermark
      path: /files/{file_id}/watermark
      operations:
      - name: getfilesidwatermark
        method: GET
        description: Box Get watermark on file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: o

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/capabilities/files-files.yaml