Box Shared Links (Folders) API

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

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


        A shared folder 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 folder when only given a shared link.'
      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 folder resource if the shared link is valid and

            the user has access to it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder--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'
  /folders/{folder_id}#get_shared_link:
    get:
      operationId: get_folders_id#get_shared_link
      summary: Box Get shared link for folder
      tags:
      - Shared Links (Folders)
      x-box-tag: shared_links_folders
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Gets the information for a shared link on a folder.
      parameters:
      - name: folder_id
        description: 'The unique identifier that represent a folder.


          The ID for any folder can be determined

          by visiting this folder in the web application

          and copying the ID from the URL. For example,

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

          the `folder_id` is `123`.


          The root folder of a Box account is

          always represented by the ID `0`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
          nullable: false
      - 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 folder with the

            additional shared link information.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: folder
                    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: false
        '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 folder is not found, or the user does not

            have access to the folder.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `folder_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'
  /folders/{folder_id}#add_shared_link:
    put:
      operationId: put_folders_id#add_shared_link
      summary: Box Add shared link to folder
      tags:
      - Shared Links (Folders)
      x-box-tag: shared_links_folders
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Adds a shared link to a folder.
      parameters:
      - name: folder_id
        description: 'The unique identifier that represent a folder.


          The ID for any folder can be determined

          by visiting this folder in the web application

          and copying the ID from the URL. For example,

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

          the `folder_id` is `123`.


          The root folder of a Box account is

          always represented by the ID `0`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
          nullable: false
      - 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 folder.


                    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 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: false
                          description: 'This value can only be `false` for items

                            with a `type` of `folder`.'
      responses:
        '200':
          description: 'Returns the base representation of a folder with a new shared

            link attached.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: folder
                    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: false
        '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 folder is not found, or the user does not

            have access to the folder.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `folder_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 folder. This indicates that the folder

            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'
  /folders/{folder_id}#update_shared_link:
    put:
      operationId: put_folders_id#update_shared_link
      summary: Box Update shared link on folder
      tags:
      - Shared Links (Folders)
      x-box-tag: shared_links_folders
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Updates a shared link on a folder.
      parameters:
      - name: folder_id
        description: 'The unique identifier that represent a folder.


          The ID for any folder can be determined

          by visiting this folder in the web application

          and copying the ID from the URL. For example,

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

          the `folder_id` is `123`.


          The root folder of a Box account is

          always represented by the ID `0`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
          nullable: false
      - 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: false
                          description: 'This value can only be `false` for items

                            with a `type` of `folder`.'
      responses:
        '200':
          description: 'Returns a basic representation of the folder, with the updated shared

            link attached.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: folder
                    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: false
        '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 folder is not found, or the user does not

            have access to the folder.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `folder_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 folder. This indicates that the folder

            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'
  /folders/{folder_id}#remove_shared_link:
    put:
      operationId: put_folders_id#remove_shared_link
      summary: Box Remove shared link from folder
      tags:
      - Shared Links (Folders)
      x-box-tag: shared_links_folders
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Removes a shared link from a folder.
      parameters:
      - name: folder_id
        description: 'The unique identifier that represent a folder.


          The ID for any folder can be determined

          by visiting this folder in the web application

          and copying the ID from the URL. For example,

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

          the `folder_id` is `123`.


          The root folder of a Box account is

          always represented by the ID `0`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
          nullable: false
      - 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 folder.'
                  type: object
                  example: null
                  nullable: true
      responses:
        '200':
          description: Returns a basic representation of a folder, with the shared link removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: folder
                    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 folder is not found, or the user does not

            have access to the folder.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `folder_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 folder. This indicates that the folder

            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:
      title: Folder
      type: object
      x-box-resource-id: folder
      x-box-variant: standard
      description: 'A standard representation of a folder, as returned from any

        folder API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/Folder--Mini'
      - properties:
          created_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time when the folder was created. This value may

              be `null` for some folders such as the root folder or the trash

              folder.'
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            description: 'The date and time when the folder was last updated. This value may

              be `null` for some folders such as the root folder or the trash

              folder.'
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          description:
            allOf:
            - type: string
              description: The optional description of this folder
              maxLength: 256
              example: Legal contracts for the new ACME deal
              nullable: false
            - nullable: false
          size:
            type: integer
            format: int64
            description: 'The folder size in bytes.


              Be careful parsing this integer as its

              value can get very large.'
            example: 629644
            nullable: false
          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 folder is contained in,

                starting at the root.'
            - nullable: false
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this folder
            - nullable: false
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this folder.
            - nullable: false
          trashed_at:
            type: string
            format: date-time
            description: The time at which this folder 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 folder 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 folder was originally

              created.'
            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 folder was last updated.
            example: '2012-12-12T10:53:43-08:00'
          owned_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who owns this folder.
            - 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
                  format: url
                  description: 'The URL that can be used to access the item on Box.


                    This URL will display the item in Box''s preview UI where the file

                    can be downloaded if allowed.


                    This URL will continue to work even when a custom `vanity_url`

                    has been set for this shared link.'
                  example: https://www.box.com/s/vspke7y05sb214wjokpk
                  nullable: false
                download_url:
                  type: string
                  format: url
                  x-box-premium-feature: true
                  description: 'A URL that can be used to download the file. This URL can be used in

                    a browser to download the file. This URL includes the file

                    extension so that the file will be saved with the right file type.


                    This property will be `null` for folders.'
                  example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
                  nullable: true
                vanity_url:
                  type: string
                  format: url
                  description: 'The "Custom URL" that can also be used to preview the item on Box.  Custom

               

# --- truncated at 32 KB (112 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-shared-links-folders-api-openapi.yml