Box Shared Items API

openapi: 3.1.0
info:
  title: Box Shared Items API
  description: Needs a description.
paths:
  /shared_items:
    get:
      operationId: get_shared_items
      summary: Box Find file for shared link
      tags:
        - Shared Items
      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'
  /shared_items#folders:
    get:
      operationId: get_shared_items#folders
      summary: Box Find folder for shared link
      tags:
        - Shared Items#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'
  /shared_items#web_links:
    get:
      operationId: get_shared_items#web_links
      summary: Box Find web link for shared link
      tags:
        - Shared Items#web Links
      x-box-tag: shared_links_web_links
      x-box-enable-explorer: true
      description: |-
        Returns the web link represented by a shared link.

        A shared web link 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 web link 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 file resource if the shared link is valid and
            the user has access to it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebLink'
        '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'
components:
  schemas:
    File--Full:
      title: File (Full)
      type: object
      x-box-resource-id: file--full
      x-box-variant: full
      description: |-
        A full representation of a file, as can be returned from any
        file API endpoints by default
      allOf:
        - $ref: '#/components/schemas/File'
        - properties:
            version_number:
              type: string
              example: '1'
              description: The version number of this file
            comment_count:
              type: integer
              example: 10
              description: The number of comments on this file
            permissions:
              allOf:
                - type: object
                  description: The permissions that the authenticated user has for a file.
                  required:
                    - can_annotate
                    - can_comment
                    - can_preview
                    - can_upload
                    - can_view_annotations_all
                    - can_view_annotations_self
                  allOf:
                    - type: object
                      description: >-
                        The permissions that the authenticated user has for an
                        item.
                      required:
                        - can_delete
                        - can_download
                        - can_invite_collaborator
                        - can_rename
                        - can_set_share_access
                        - can_share
                      properties:
                        can_delete:
                          type: boolean
                          description: Specifies if the current user can delete this item.
                          example: true
                          nullable: false
                        can_download:
                          type: boolean
                          description: >-
                            Specifies if the current user can download this
                            item.
                          example: true
                          nullable: false
                        can_invite_collaborator:
                          type: boolean
                          description: >-
                            Specifies if the current user can invite new

                            users to collaborate on this item, and if the user
                            can

                            update the role of a user already collaborated on
                            this

                            item.
                          example: true
                          nullable: false
                        can_rename:
                          type: boolean
                          description: Specifies if the user can rename this item.
                          example: true
                          nullable: false
                        can_set_share_access:
                          type: boolean
                          description: >-
                            Specifies if the user can change the access level of
                            an

                            existing shared link on this item.
                          example: true
                          nullable: false
                        can_share:
                          type: boolean
                          description: >-
                            Specifies if the user can create a shared link for
                            this item.
                          example: true
                          nullable: false
                    - properties:
                        can_annotate:
                          type: boolean
                          description: >-
                            Specifies if the user can place annotations on this
                            file.
                          example: true
                          nullable: false
                        can_comment:
                          type: boolean
                          description: >-
                            Specifies if the user can place comments on this
                            file.
                          example: true
                          nullable: false
                        can_preview:
                          type: boolean
                          description: Specifies if the user can preview this file.
                          example: true
                          nullable: false
                        can_upload:
                          type: boolean
                          description: >-
                            Specifies if the user can upload a new version of
                            this file.
                          example: true
                          nullable: false
                        can_view_annotations_all:
                          type: boolean
                          description: >-
                            Specifies if the user view all annotations placed on
                            this file
                          example: true
                          nullable: false
                        can_view_annotations_self:
                          type: boolean
                          description: >-
                            Specifies if the user view annotations placed by
                            themselves

                            on this file
                          example: true
                          nullable: false
                - description: |-
                    Describes the permissions that the current user has
                    for this file.
                - nullable: false
            tags:
              allOf:
                - 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.
                - nullable: false
            lock:
              allOf:
                - title: Lock
                  type: object
                  description: >-
                    The lock held on a file. A lock prevents a file from being
                    moved,

                    renamed, or otherwise changed by anyone else than the user
                    who created the

                    lock.
                  properties:
                    id:
                      type: string
                      description: The unique identifier for this lock
                      example: '11446498'
                    type:
                      type: string
                      description: '`lock`'
                      example: lock
                      enum:
                        - lock
                    created_by:
                      allOf:
                        - $ref: '#/components/schemas/User--Mini'
                        - description: The user who created the lock.
                    created_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: The time this lock was created at.
                    expired_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: >-
                        The time this lock is to expire at, which might be in
                        the past.
                    is_download_prevented:
                      type: boolean
                      example: true
                      description: Whether or not the file can be downloaded while locked.
                    app_type:
                      type: string
                      description: >-
                        If the lock is managed by an application rather than a
                        user, this

                        field identifies the type of the application that holds
                        the lock.

                        This is an open enum and may be extended with additional
                        values in

                        the future.
                      enum:
                        - gsuite
                        - office_wopi
                        - office_wopiplus
                        - other
                      example: office_wopiplus
                      nullable: true
                - description: >-
                    The lock held on this file. If there is no lock, this can
                    either

                    be `null` or have a timestamp in the past.
              nullable: true
            extension:
              type: string
              example: pdf
              description: >-
                Indicates the (optional) file extension for this file. By
                default,

                this is set to an empty string.
            is_package:
              type: boolean
              example: true
              description: |-
                Indicates if the file is a package. Packages are commonly used
                by Mac Applications and can include iWork files.
            expiring_embed_link:
              allOf:
                - title: Expiring embed link
                  type: object
                  description: An expiring Box Embed Link.
                  allOf:
                    - type: object
                      description: The basics of an access token
                      properties:
                        access_token:
                          type: string
                          format: token
                          example: >-
                            c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
                          description: The requested access token.
                        expires_in:
                          type: integer
                          format: int64
                          example: 3600
                          description: The time in seconds by which this token will expire.
                        token_type:
                          type: string
                          enum:
                            - bearer
                          example: bearer
                          description: The type of access token returned.
                        restricted_to:
                          type: array
                          description: >-
                            The permissions that this access token permits,

                            providing a list of resources (files, folders, etc)

                            and the scopes permitted for each of those
                            resources.
                          items:
                            $ref: '#/components/schemas/FileOrFolderScope'
                    - properties:
                        url:
                          type: string
                          format: url
                          example: https://cloud.app.box.com/preview/expiring_embed/...
                          description: >-
                            The actual expiring embed URL for this file,
                            constructed

                            from the file ID and access tokens specified in this
                            object.
                - description: >-
                    Requesting this field creates an expiring Box Embed URL for
                    an

                    embedded preview session in an `iframe`.


                    This URL will expire after 60 seconds and the session will

                    expire after 60 minutes.


                    Not all file types are supported for these embed URLs. Box
                    Embed

                    is not optimized for mobile browsers and should not be used
                    in web

                    experiences designed for mobile devices. Many UI elements,
                    like

                    the **download** and **print** options might not show in
                    mobile

                    browsers.
            watermark_info:
              allOf:
                - type: object
                  description: Details about the watermark applied to this item
                  properties:
                    is_watermarked:
                      type: boolean
                      description: Specifies if this item has a watermark applied.
                      example: true
                      nullable: false
                - description: Details about the watermark applied to this file
            is_accessible_via_shared_link:
              type: boolean
              description: |-
                Specifies if the file can be accessed
                via the direct shared link or a shared link
                to a parent folder.
              example: true
              enum:
                - true
                - false
            allowed_invitee_roles:
              type: array
              example:
                - editor
              nullable: false
              description: |-
                A list of the types of roles that user can be invited at
                when sharing this file.
              items:
                type: string
                enum:
                  - editor
                  - viewer
                  - previewer
                  - uploader
                  - previewer uploader
                  - viewer uploader
                  - co-owner
            is_externally_owned:
              type: boolean
              example: true
              nullable: false
              description: |-
                Specifies if this file is owned by a user outside of the
                authenticated enterprise.
            has_collaborations:
              type: boolean
              example: true
              nullable: false
              description: Specifies if this file has any other collaborators.
            metadata:
              allOf:
                - title: Item metadata instances
                  type: object
                  description: >-
                    A list of metadata instances, nested within key-value pairs
                    of their `scope`

                    and `templateKey`.


                    To access the metadata for a file or folder, first use the

                    metadata endpoints to determine the metadata templates
                    available to your

                    enterprise.


                    Then use the `GET /files/:id` or `GET /folder/:id`

                    endpoint with the `fields` query parameter to get

                    the metadata by ID.


                    To request a metadata instance for a particular `scope` and
                    `templateKey`

                    use the following format for the `fields` parameter:

                    `metadata.<scope>.<templateKey>`


                    For example,
                    `?fields=metadata.enterprise_27335.marketingCollateral`.
                  example:
                    enterprise_27335:
                      marketingCollateral:
                        $canEdit: true
                        $id: 01234500-12f1-1234-aa12-b1d234cb567e
                        $parent: folder_59449484661
                        $scope: enterprise_27335
                        $template: marketingCollateral
                        $type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
                        $typeVersion: 2
                        $version: 1
                  additionalProperties:
                    type: object
                    description: >-
                      A list of metadata instances, nested within key-value
                      pairs of their `scope`

                      and `templateKey`.
                    example:
                      marketingCollateral:
                        $canEdit: true
                        $id: 01234500-12f1-1234-aa12-b1d234cb567e
                        $parent: folder_59449484661
                        $scope: enterprise_27335
                        $template: marketingCollateral
                        $type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
                        $typeVersion: 2
                        $version: 1
                    additionalProperties:
                      $ref: '#/components/schemas/Metadata'
                - description: >-
                    An object containing the metadata instances that have been

                    attached to this file.


                    Each metadata instance is uniquely identified by its `scope`
                    and

                    `templateKey`. There can only be one instance of any
                    metadata

                    template attached to each file. Each metadata instance is
                    nested

                    within an object with the `templateKey` as the key, which
                    again

                    itself is nested in an object with the `scope` as the key.
            expires_at:
              type: string
              format: date-time
              nullable: true
              description: When the file will automatically be deleted
              example: '2012-12-12T10:53:43-08:00'
            representations:
              allOf:
                - title: Representations
                  description: A list of file representations
                  type: object
                  properties:
                    entries:
                      type: array
                      description: A list of files
                      items:
                        type: object
                        description: A file representation
                        properties:
                          content:
                            type: object
                            description: >-
                              An object containing the URL that can be used to
                              actually fetch

                              the representation.
                            properties:
                              url_template:
                                type: string
                                example: >-
                                  https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567
                                description: >-
                                  The download URL that can be used to fetch the
                                  representation.

                                  Make sure to make an authenticated API call to
                                  this endpoint.


                                  This URL is a template and will require the
                                  `{+asset_path}` to

                                  be replaced by a path. In general, for unpaged
                                  representations

                                  it can be replaced by an empty string.


                                  For paged representations, replace the
                                  `{+asset_path}` with the

                                  page to request plus the extension for the
                                  file, for example

                                  `1.pdf`.


                                  When requesting the download URL the following
                                  additional

                                  query params can be passed along.


                                  * `set_content_disposition_type` - Sets the

                                  `Content-Disposition` header in the API
                                  response with the

                                  specified disposition type of either `inline`
                                  or `attachment`.

                                  If not supplied, the `Content-Disposition`
                                  header is not

                                  included in the response.


                                  * `set_content_disposition_filename` - Allows
                                  the application to
                                    define the representation's file name used in the
                                    `Content-Disposition` header.  If not defined, the filename
                                    is derived from the source file name in Box combined with the
                                    extension of the representation.
                          info:
                            type: object
                            description: >-
                              An object containing the URL that can be used to
                              fetch more info

                              on this representation.
                            properties:
                              url:
                                type: string
                                example: >-
                                  https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048
                                description: >-
                                  The API URL that can be used to get more info
                                  on this file

                                  representation. Make sure to make an
                                  authenticated API call

                                  to this endpoint.
                          properties:
                            type: object
                            description: >-
                              An object containing the size and type of this
                              presentation.
                            properties:
                              dimensions:
                                type: string
                                format: <width>x<height>
                                example: 2048x2048
                                description: >-
                                  The width by height size of this
                                  representation in pixels.
                              paged:
                                type: boolean
                                example: true
                                description: >-
                                  Indicates if the representation is build up
                                  out of multiple

                                  pages.
                              thumb:
                                type: boolean
                                example: true
                                description: >-
                                  Indicates if the representation can be used as
                                  a thumbnail of

                                  the file.
                          representation:


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