Box
Box Shared Links (Files) API

Files shared links are URLs that are generated for files stored in Box, which provide direct, read-only access to the resource.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: Box Authorize Authorization Shared Links (Files) API
  description: Needs a description.
tags:
- name: Shared Links (Files)
  description: 'Files shared links are URLs that are generated for files stored in Box,

    which provide direct, read-only access to the resource.'
  x-box-tag: shared_links_files
paths:
  /shared_items:
    get:
      operationId: get_shared_items
      summary: Box Find file for shared link
      tags:
      - Shared Links (Files)
      x-box-tag: shared_links_files
      x-box-enable-explorer: true
      description: 'Returns the file represented by a shared link.


        A shared file can be represented by a shared link,

        which can originate within the current enterprise or within another.


        This endpoint allows an application to retrieve information about a

        shared file when only given a shared link.


        The `shared_link_permission_options` array field can be returned

        by requesting it in the `fields` query parameter.'
      parameters:
      - 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: 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: boxapi
        description: 'A header containing the shared link and optional password for the

          shared link.


          The format for this header is as follows.


          `shared_link=[link]&shared_link_password=[password]`'
        example: shared_link=[link]&shared_link_password=[password]
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns a full file resource if the shared link is valid and

            the user has access to it.'
          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.'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/{file_id}#get_shared_link:
    get:
      operationId: get_files_id#get_shared_link
      summary: Box Get shared link for file
      tags:
      - Shared Links (Files)
      x-box-tag: shared_links_files
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Gets the information for a shared link on 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: 'Explicitly request the `shared_link` fields

          to be returned for this item.'
        example: shared_link
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns the base representation of a file with the

            additional shared link information.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: file
                    etag: '1'
                    shared_link:
                      url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
                      download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
                      vanity_url: null
                      vanity_name: null
                      effective_access: open
                      effective_permission: can_download
                      is_password_enabled: false
                      unshared_at: '2020-09-21T10:34:41-07:00'
                      download_count: 0
                      preview_count: 0
                      access: open
                      permissions:
                        can_preview: true
                        can_download: true
                        can_edit: true
        '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'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/{file_id}#add_shared_link:
    put:
      operationId: put_files_id#add_shared_link
      summary: Box Add shared link to file
      tags:
      - Shared Links (Files)
      x-box-tag: shared_links_files
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Adds a shared link to 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: 'Explicitly request the `shared_link` fields

          to be returned for this item.'
        example: shared_link
        in: query
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shared_link:
                  description: 'The settings for the shared link to create on the file.

                    Use an empty object (`{}`) to use the default settings for shared

                    links.'
                  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 file (`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.'
                      minLength: 12
                      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. The value must be greater than the

                        current date and time.'
                    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`.'
                        can_preview:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for previewing of files.

                            This value is always `true`. For shared links on folders

                            this also applies to any items in the folder.'
                        can_edit:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for editing of files.

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

                            `open` or `company`.

                            This value can only be `true` is `can_download` is

                            also `true`.'
      responses:
        '200':
          description: 'Returns the base representation of a file with a new shared

            link attached.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: file
                    etag: '1'
                    shared_link:
                      url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
                      download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
                      vanity_url: null
                      vanity_name: null
                      effective_access: open
                      effective_permission: can_download
                      is_password_enabled: false
                      unshared_at: '2020-09-21T10:34:41-07:00'
                      download_count: 0
                      preview_count: 0
                      access: open
                      permissions:
                        can_preview: true
                        can_download: true
                        can_edit: true
        '400':
          description: Returned when there is an incorrect permission combination
          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.'
          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'
  /files/{file_id}#update_shared_link:
    put:
      operationId: put_files_id#update_shared_link
      summary: Box Update shared link on file
      tags:
      - Shared Links (Files)
      x-box-tag: shared_links_files
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Updates a shared link on 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: 'Explicitly request the `shared_link` fields

          to be returned for this item.'
        example: shared_link
        in: query
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shared_link:
                  description: The settings for the shared link to update.
                  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.'
                      minLength: 12
                      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. The value must be greater than the

                        current date and time.'
                    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`.'
                        can_preview:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for previewing of files.

                            This value is always `true`. For shared links on folders

                            this also applies to any items in the folder.'
                        can_edit:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for editing of files.

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

                            `open` or `company`.

                            This value can only be `true` is `can_download` is

                            also `true`.'
      responses:
        '200':
          description: 'Returns a basic representation of the file, with the updated shared

            link attached.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: file
                    etag: '1'
                    shared_link:
                      url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
                      download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
                      vanity_url: null
                      vanity_name: null
                      effective_access: open
                      effective_permission: can_download
                      is_password_enabled: false
                      unshared_at: '2020-09-21T10:34:41-07:00'
                      download_count: 0
                      preview_count: 0
                      access: open
                      permissions:
                        can_preview: true
                        can_download: true
                        can_edit: true
        '400':
          description: Returned when there is an incorrect permission combination
          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.'
          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'
  /files/{file_id}#remove_shared_link:
    put:
      operationId: put_files_id#remove_shared_link
      summary: Box Remove shared link from file
      tags:
      - Shared Links (Files)
      x-box-tag: shared_links_files
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Removes a shared link from 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: 'Explicitly request the `shared_link` fields

          to be returned for this item.'
        example: shared_link
        in: query
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shared_link:
                  description: 'By setting this value to `null`, the shared link

                    is removed from the file.'
                  type: object
                  example: null
                  nullable: true
      responses:
        '200':
          description: Returns a basic representation of a file, with the shared link removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: file
                    etag: '1'
                    shared_link: null
        '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.'
          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'
components:
  schemas:
    Folder--Base:
      title: Folder (Base)
      type: object
      x-box-resource-id: folder--base
      x-box-sanitized: true
      x-box-tag: folders
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a folder, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          description: 'The unique identifier that represent a folder.


            The ID for any folder can be determined

            by visiting a folder in the web application

            and copying the ID from the URL. For example,

            for the URL `https://*.app.box.com/folders/123`

            the `folder_id` is `123`.'
          example: '12345'
        etag:
          type: string
          nullable: true
          example: '1'
          description: 'The HTTP `etag` of this folder. This can be used within some API

            endpoints in the `If-Match` and `If-None-Match` headers to only

            perform changes on the folder if (no) changes have happened.'
        type:
          type: string
          description: '`folder`'
          example: folder
          enum:
          - folder
          nullable: false
    Metadata:
      title: Metadata instance
      type: object
      x-box-resource-id: metadata
      x-box-tag: file_metadata
      x-box-variant: standard
      description: 'An instance of a metadata template, which has been applied to a file or

        folder.'
      allOf:
      - $ref: '#/components/schemas/Metadata--Base'
    File:
      title: File
      type: object
      x-box-resource-id: file
      x-box-variant: standard
      description: 'A standard representation of a file, as returned from any

        file API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/File--Mini'
      - properties:
          description:
            type: string
            nullable: false
            description: The optional description of this file
            maxLength: 256
            example: Contract for Q1 renewal
          size:
            type: integer
            nullable: false
            description: 'The file size in bytes. Be careful parsing this integer as it can

              get very large and cause an integer overflow.'
            example: 629644
          path_collection:
            allOf:
            - title: Path collection
              description: A list of parent folders for an item.
              type: object
              required:
              - total_count
              - entries
              properties:
                total_count:
                  description: The number of folders in this list.
                  example: 1
                  type: integer
                  format: int64
                  nullable: false
                entries:
                  type: array
                  description: The parent folders for this item
                  nullable: false
                  items:
                    $ref: '#/components/schemas/Folder--Mini'
            - description: 'The tree of folders that this file is contained in,

                starting at the root.'
            - nullable: false
          created_at:
            type: string
            format: date-time
            nullable: false
            description: The date and time when the file was created on Box.
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            nullable: false
            description: The date and time when the file was last updated on Box.
            example: '2012-12-12T10:53:43-08:00'
          trashed_at:
            type: string
            format: date-time
            description: The time at which this file was put in the trash.
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          purged_at:
            type: string
            format: date-time
            description: 'The time at which this file is expected to be purged

              from the trash.'
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          content_created_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time at which this file was originally

              created, which might be before it was uploaded to Box.'
            example: '2012-12-12T10:53:43-08:00'
          content_modified_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time at which this file was last updated,

              which might be before it was uploaded to Box.'
            example: '2012-12-12T10:53:43-08:00'
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this file
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this file
            - nullable: false
          owned_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who owns this file
            - nullable: false
          shared_link:
            allOf:
            - title: Shared link
              description: 'Shared links provide direct, read-only access to files or folder on Box.


                Shared links with open access level allow anyone with the URL

                to access the item, while shared links with company or collaborators access

                levels can only be accessed by appropriately authenticated Box users.'
              type: object
              required:
              - url
              - accessed
              - effective_access
              - effective_permission
              - is_password_enabled
              - download_count
              - preview_count
              properties:
                url:
                  type: string
                  f

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-shared-links-files-api-openapi.yml
Box Shared Links (Files) API

Documentation

Specifications

Other Resources

OpenAPI Specification
