Box Files API

openapi: 3.1.0
info:
  title: Box Files API
  description: Needs a description.
paths:
  /files/{file_id}:
    get:
      operationId: get_files_id
      summary: Box Get file information
      tags:
        - Files
      x-box-tag: files
      x-box-enable-explorer: true
      description: Retrieves the details about a file.
      parameters:
        - name: file_id
          description: |-
            The unique identifier that represents a file.

            The ID for any file can be determined
            by visiting a file in the web application
            and copying the ID from the URL. For example,
            for the URL `https://*.app.box.com/files/123`
            the `file_id` is `123`.
          example: '12345'
          in: path
          required: true
          schema:
            type: string
        - name: fields
          description: |-
            A comma-separated list of attributes to include in the
            response. This can be used to request fields that are
            not normally returned in a standard response.

            Be aware that specifying this parameter will have the
            effect that none of the standard fields are returned in
            the response unless explicitly specified, instead only
            fields for the mini representation are returned, additional
            to the fields requested.

            Additionally this field can be used to query any metadata
            applied to the file by specifying the `metadata` field as well
            as the scope and key of the template to retrieve, for example
            `?field=metadata.enterprise_12345.contractTemplate`.
          in: query
          example:
            - id
            - type
            - name
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: if-none-match
          description: |-
            Ensures an item is only returned if it has changed.

            Pass in the item's last observed `etag` value
            into this header and the endpoint will fail
            with a `304 Not Modified` if the item has not
            changed since.
          in: header
          required: false
          example: '1'
          schema:
            type: string
        - name: boxapi
          description: >-
            The URL, and optional password, for the shared link of this item.


            This header can be used to access items that have not been

            explicitly shared with a user.


            Use the format `shared_link=[link]` or if a password is required
            then

            use `shared_link=[link]&shared_link_password=[password]`.


            This header can be used on the file or folder shared, as well as on
            any files

            or folders nested within the item.
          example: shared_link=[link]&shared_link_password=[password]
          in: header
          required: false
          schema:
            type: string
        - name: x-rep-hints
          description: |-
            A header required to request specific `representations`
            of a file. Use this in combination with the `fields` query
            parameter to request a specific file representation.

            The general format for these representations is
            `X-Rep-Hints: [...]` where `[...]` is one or many
            hints in the format `[fileType?query]`.

            For example, to request a `png` representation in `32x32`
            as well as `64x64` pixel dimensions provide the following
            hints.

            `x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64]`

            Additionally, a `text` representation is available for all
            document file types in Box using the `[extracted_text]`
            representation.

            `x-rep-hints: [extracted_text]`
          example: '[pdf]'
          in: header
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: |-
            Returns a file object.

            Not all available fields are returned by default. Use the
            [fields](#param-fields) query parameter to explicitly request
            any specific fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
        '304':
          description: >-
            Returns an empty response when the `If-None-Match` header matches

            the current `etag` value of the folder. This indicates that the
            folder

            has not changed since it was last requested.
        '401':
          description: >-
            Returned when the access token provided in the `Authorization`
            header

            is not recognized or not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: |-
            Returned if the file is not found, or the user does not
            have access to the file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `file_id` is not in a recognized format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '415':
          description: |-
            Returns an error if an action is performed on a file with an
            incorrect media type.

            * `unsupported_media_type` when requesting an `expiring_embed_link`
              for a file that is not supported by Box Embed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    post:
      operationId: post_files_id
      summary: Box Restore file
      tags:
        - Files
      x-box-tag: trashed_files
      description: >-
        Restores a file that has been moved to the trash.


        An optional new parent ID can be provided to restore the file to in case
        the

        original folder has been deleted.
      parameters:
        - name: file_id
          description: |-
            The unique identifier that represents a file.

            The ID for any file can be determined
            by visiting a file in the web application
            and copying the ID from the URL. For example,
            for the URL `https://*.app.box.com/files/123`
            the `file_id` is `123`.
          example: '12345'
          in: path
          required: true
          schema:
            type: string
        - name: fields
          description: |-
            A comma-separated list of attributes to include in the
            response. This can be used to request fields that are
            not normally returned in a standard response.

            Be aware that specifying this parameter will have the
            effect that none of the standard fields are returned in
            the response unless explicitly specified, instead only
            fields for the mini representation are returned, additional
            to the fields requested.
          in: query
          example:
            - id
            - type
            - name
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: An optional new name for the file.
                  example: Restored.docx
                  type: string
                parent:
                  allOf:
                    - type: object
                      description: The parent for this item
                      properties:
                        id:
                          type: string
                          description: The ID of parent item
                          example: '123'
                    - description: >-
                        Specifies an optional ID of a folder to restore the file
                        to

                        when the original folder no longer exists.


                        Please be aware that this ID will only be used if the
                        original

                        folder no longer exists. Use this ID to provide a
                        fallback

                        location to restore the file to if the original location

                        has been deleted.
      responses:
        '201':
          description: Returns a file object when the file has been restored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrashFileRestored'
        '403':
          description: |-
            Returns an error if the user does not have access to the folder
            the file is being restored to, or the user does not have permission
            to restore files from the trash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returns an error if the file is not in the trash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '409':
          description: |-
            Returns an error if there is an file with the same name
            in the folder the file is being restored to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_files_id
      summary: Box Update file
      tags:
        - Files
      x-box-tag: files
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: |-
        Updates a file. This can be used to rename or move a file,
        create a shared link, or lock a file.
      parameters:
        - name: file_id
          description: |-
            The unique identifier that represents a file.

            The ID for any file can be determined
            by visiting a file in the web application
            and copying the ID from the URL. For example,
            for the URL `https://*.app.box.com/files/123`
            the `file_id` is `123`.
          example: '12345'
          in: path
          required: true
          schema:
            type: string
        - name: fields
          description: |-
            A comma-separated list of attributes to include in the
            response. This can be used to request fields that are
            not normally returned in a standard response.

            Be aware that specifying this parameter will have the
            effect that none of the standard fields are returned in
            the response unless explicitly specified, instead only
            fields for the mini representation are returned, additional
            to the fields requested.
          in: query
          example:
            - id
            - type
            - name
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: if-match
          description: |-
            Ensures this item hasn't recently changed before
            making changes.

            Pass in the item's last observed `etag` value
            into this header and the endpoint will fail
            with a `412 Precondition Failed` if it
            has changed since.
          in: header
          required: false
          example: '1'
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: |-
                    An optional different name for the file. This can be used to
                    rename the file.
                  example: NewFile.txt
                description:
                  type: string
                  description: >-
                    The description for a file. This can be seen in the
                    right-hand sidebar panel

                    when viewing a file in the Box web app. Additionally, this
                    index is used in

                    the search index of the file, allowing users to find the
                    file by the content

                    in the description.
                  maxLength: 256
                  example: The latest reports. Automatically updated
                parent:
                  allOf:
                    - type: object
                      description: The parent for this item
                      properties:
                        id:
                          type: string
                          description: The ID of parent item
                          example: '123'
                    - description: >-
                        An optional new parent folder for the file. This can be
                        used

                        to move the file to a new folder.
                shared_link:
                  allOf:
                    - description: >-
                        Defines a shared link for an item. Set this to `null` to
                        remove

                        the shared link.
                      type: object
                      properties:
                        access:
                          type: string
                          description: >-
                            The level of access for the shared link. This can be

                            restricted to anyone with the link (`open`), only
                            people

                            within the company (`company`) and only those who

                            have been invited to the folder (`collaborators`).


                            If not set, this field defaults to the access level
                            specified

                            by the enterprise admin. To create a shared link
                            with this

                            default setting pass the `shared_link` object with

                            no `access` field, for example `{ "shared_link": {}
                            }`.


                            The `company` access level is only available to paid

                            accounts.
                          enum:
                            - open
                            - company
                            - collaborators
                          example: open
                        password:
                          type: string
                          description: >-
                            The password required to access the shared link. Set
                            the

                            password to `null` to remove it.

                            Passwords must now be at least eight characters

                            long and include a number, upper case letter, or

                            a non-numeric or non-alphabetic character.

                            A password can only be set when `access` is set to
                            `open`.
                          example: do-n8t-use-this-Password
                        vanity_name:
                          type: string
                          description: >-
                            Defines a custom vanity name to use in the shared
                            link URL,

                            for example `https://app.box.com/v/my-shared-link`.


                            Custom URLs should not be used when sharing
                            sensitive content

                            as vanity URLs are a lot easier to guess than
                            regular shared links.
                          example: my-shared-link
                        unshared_at:
                          type: string
                          format: date-time
                          example: '2012-12-12T10:53:43-08:00'
                          description: |-
                            The timestamp at which this shared link will
                            expire. This field can only be set by
                            users with paid accounts.
                        permissions:
                          type: object
                          properties:
                            can_download:
                              type: boolean
                              example: true
                              description: >-
                                If the shared link allows for downloading of
                                files.

                                This can only be set when `access` is set to

                                `open` or `company`.
                    - description: >-
                        Defines a shared link for a file. Set this to `null` to
                        remove

                        the shared link.
                lock:
                  type: object
                  description: >-
                    Defines a lock on an item. This prevents the item from being

                    moved, renamed, or otherwise changed by anyone other than
                    the user

                    who created the lock.


                    Set this to `null` to remove the lock.
                  required:
                    - type
                  properties:
                    access:
                      type: string
                      description: The type of this object.
                      enum:
                        - lock
                      example: lock
                    expires_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: Defines the time at which the lock expires.
                    is_download_prevented:
                      type: boolean
                      example: true
                      description: >-
                        Defines if the file can be downloaded while it is
                        locked.
                disposition_at:
                  type: string
                  format: date-time
                  example: '2012-12-12T10:53:43-08:00'
                  description: |-
                    The retention expiration timestamp for the given file. This
                    date cannot be shortened once set on a file.
                permissions:
                  description: Defines who can download a file.
                  type: object
                  properties:
                    can_download:
                      description: >-
                        Defines who is allowed to download this file. The
                        possible

                        values are either `open` for everyone or `company` for

                        the other members of the user's enterprise.


                        This setting overrides the download permissions that are

                        normally part of the `role` of a collaboration. When set
                        to

                        `company`, this essentially removes the download option
                        for

                        external users with `viewer` or `editor` a roles.
                      type: string
                      example: open
                      enum:
                        - open
                        - company
                collections:
                  type: array
                  description: |-
                    An array of collections to make this file
                    a member of. Currently
                    we only support the `favorites` collection.

                    To get the ID for a collection, use the
                    [List all collections][1] endpoint.

                    Passing an empty array `[]` or `null` will remove
                    the file from all collections.

                    [1]: e://get-collections
                  items:
                    title: Reference
                    description: The bare basic reference for an object
                    type: object
                    properties:
                      id:
                        type: string
                        description: The unique identifier for this object
                        example: '11446498'
                      type:
                        type: string
                        description: The type for this object
                        example: file
                tags:
                  type: array
                  example:
                    - approved
                  items:
                    type: string
                  minItems: 1
                  maxItems: 100
                  description: |-
                    The tags for this item. These tags are shown in
                    the Box web app and mobile apps next to an item.

                    To add or remove a tag, retrieve the item's current tags,
                    modify them, and then update this field.

                    There is a limit of 100 tags per item, and 10,000
                    unique tags per enterprise.
      responses:
        '200':
          description: |-
            Returns a file object.

            Not all available fields are returned by default. Use the
            [fields](#param-fields) query parameter to explicitly request
            any specific fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
        '400':
          description: Returned when the new retention time > maximum retention length.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '401':
          description: >-
            Returned when the access token provided in the `Authorization`
            header

            is not recognized or not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: >-
            Returned if the user does not have all the permissions to complete
            the

            update.


            * `access_denied_insufficient_permissions` returned

            when the authenticated user does not have access

            to the destination folder to move the file to.

            * Returned when retention time is shorter or equal to current
            retention

            timestamp.

            * Returned when a `file_id` that is not under retention is entered.

            * Returned when a file that is retained but the disposition action
            is set

            to `remove_retention`

            * `forbidden_by_policy` is returned if copying a folder is

            forbidden due to information barrier restrictions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: |-
            Returned if the file is not found, or the user does not
            have access to the file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `file_id` is not in a recognized format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '412':
          description: |-
            Returns an error when the `If-Match` header does not match
            the current `etag` value of the file. This indicates that the file
            has changed since it was last requested.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_files_id
      summary: Box Delete file
      tags:
        - Files
      x-box-tag: files
      x-box-sanitized: true
      description: |-
        Deletes a file, either permanently or by moving it to
        the trash.

        The the enterprise settings determine whether the item will
        be permanently deleted from Box or moved to the trash.
      parameters:
        - name: file_id
          description: |-
            The unique identifier that represents a file.

            The ID for any file can be determined
            by visiting a file in the web application
            and copying the ID from the URL. For example,
            for the URL `https://*.app.box.com/files/123`
            the `file_id` is `123`.
          example: '12345'
          in: path
          required: true
          schema:
            type: string
        - name: if-match
          description: |-
            Ensures this item hasn't recently changed before
            making changes.

            Pass in the item's last observed `etag` value
            into this header and the endpoint will fail
            with a `412 Precondition Failed` if it
            has changed since.
          in: header
          required: false
          example: '1'
          schema:
            type: string
      responses:
        '204':
          description: |-
            Returns an empty response when the file has been successfully
            deleted.
        '401':
          description: >-
            Returned when the access token provided in the `Authorization`
            header

            is not recognized or not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: >-
            Returned if the file is not found or has already been deleted, or
            the user

            does not have access to the file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `file_id` is not in a recognized format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '412':
          description: |-
            Returns an error when the `If-Match` header does not match
            the current `etag` value of the file. This indicates that the file
            has changed since it was last requested.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/{file_id}/content:
    get:
      operationId: get_files_id_content
      summary: Box Download file
      tags:
        - Files
      x-box-tag: downloads
      description: Returns the contents of a file in binary format.
      parameters:
        - name: file_id
          description: |-
            The unique identifier that represents a file.

            The ID for any file can be determined
            by visiting a file in the web application
            and copying the ID from the URL. For example,
            for the URL `https://*.app.box.com/files/123`
            the `file_id` is `123`.
          example: '12345'
          in: path
          required: true
          schema:
            type: string
        - name: range
          description: |-
            The byte range of the content to download.

            The format `bytes={start_byte}-{end_byte}` can be used to specify
            what section of the file to download.
          example: bytes=0-1024
          in: header
          required: false
          schema:
            type: string
        - name: boxapi
          description: >-
            The URL, and optional password, for the shared link of this item.


            This header can be used to access items that have not been

            explicitly shared with a user.


            Use the format `shared_link=[link]` or if a password is required
            then

            use `shared_link=[link]&shared_link_password=[password]`.


            This header can be used on the file or folder shared, as well as on
            any files

            or folders nested within the item.
          example: shared_link=[link]&shared_link_password=[password]
          in: header
          required: false
          schema:
            type: string
        - name: version
          description: The file version to download
          example: '4'
          in: query
          required: false
          schema:
            type: string
        - name: access_token
          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 service without them needing to know how to
            handle the authentication.

            When using this parameter, please make sure that the access token is
            sufficiently scoped down to only allow read access to that file and
            no other files or folders.
          example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: |-
            Returns the requested file if the client has the **follow
            redirects** setting enabled to automatically
            follow HTTP `3xx` responses as redirects. If not, the request
            will return `302` instead.
            For details, see
            the [download file guide](g://downloads/file#download-url).
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: The binary content of the file
        '202':
          description: >-
            If the file is not ready to be downloaded yet `Retry-After` header
            will

            be returned indicating the time in seconds after which the file will

            be available for the client to download.


            This response can occur when the file was uploaded immediately
            before the

            download request.
          headers:
            Retry-After:
              description: The time in seconds after which to retry the download
              schema:
                type: integer
        '302':
          description: |-
            If the file is available for download the response will include a
            `Location` header for the file on `dl.boxcloud.com`.

            The `dl.boxcloud.com` URL is not persistent and clients will need
            to follow the redirect to actually download the file.
          headers:
            Location:
              description: A pointer to the download URL
              schema:
                type: string
                format: url
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    post:
      operationId: post_files_id_content
      tags:
        - Files
      x-box-tag: uploads
      summary: Box Upload file version
      description: |-
 

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