Box Shared Items API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Shared Items API
  description: Needs a description.
tags:
- name: Shared Items
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'
components:
  schemas:
    ClientError:
      title: Client error
      type: object
      x-box-resource-id: client_error
      description: A generic error
      properties:
        type:
          description: error
          example: error
          type: string
          enum:
          - error
          nullable: false
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
          nullable: false
        code:
          description: A Box-specific error code
          example: item_name_invalid
          type: string
          enum:
          - created
          - accepted
          - no_content
          - redirect
          - not_modified
          - bad_request
          - unauthorized
          - forbidden
          - not_found
          - method_not_allowed
          - conflict
          - precondition_failed
          - too_many_requests
          - internal_server_error
          - unavailable
          - item_name_invalid
          - insufficient_scope
        message:
          description: A short message describing the error.
          example: Method Not Allowed
          type: string
          nullable: false
        context_info:
          description: 'A free-form object that contains additional context

            about the error. The possible fields are defined on

            a per-endpoint basis. `message` is only one example.'
          type: object
          nullable: true
          properties:
            message:
              type: string
              description: More details on the error.
              example: Something went wrong.
        help_url:
          description: A URL that links to more information about why this error occurred.
          example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
          type: string
          nullable: false
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
          nullable: false
    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.\nMake sure to make an authenticated API call to this endpoint.\n\nThis URL is a template and will require the `{+asset_path}` to\nbe replaced by a path. In general, for unpaged representations\nit can be replaced by an empty string.\n\nFor paged representations, replace the `{+asset_path}` with the\npage to request plus the extension for the file, for example\n`1.pdf`.\n\nWhen requesting the download URL the following additional\nquery params can be passed along.\n\n* `set_content_disposition_type` - Sets the\n`Content-Disposition` header in the API response with the\nspecified disposition type of either `inline` or `attachment`.\nIf not supplied, the `Content-Disposition` header is not\nincluded in the response.\n\n* `set_content_disposition_filename` - Allows the application to\n  define the representation's file name used in the\n  `Content-Disposition` header.  If not defined, the filename\n  is derived from the source file name in Box combined with the\n  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:
                        type: string
                        example: png
                        description: Indicates the file type of the returned representation.
                      status:
                        type: object
                        description: An object containing the status of this representation.
                        properties:
                          state:
                            type: string
                            example: success
                            enum:
                            - success
                            - viewable
                            - pending
                            - none
                            description: "The status of the representation.\n\n* `success` defines the representation as ready to be viewed.\n* `viewable` defines a video to be ready for viewing.\n* `pending` defines the representation as to be generated. Retry\n  this endpoint to re-check the status.\n* `none` defines that the representation will be created when\n  requested. Request the URL defined in the `info` object to\n  trigger this generation."
            - description: 'A list of representations for a file that can be used to

                display a placeholder of the file in your application. By default

                this returns all representations and we recommend using the

                `x-rep-hints` header to further customize the desired

                representations.'
          classification:
            allOf:
            - type: object
              description: The classification applied to an item
              properties:
                name:
                  type: string
                  example: Top Secret
                  description: The name of the classification
                definition:
                  type: string
                  example: Content that should not be shared outside the company.
                  description: An explanation of the meaning of this classification.
                color:
                  type: string
                  example: '#FF0000'
                  description: 'The color that is used to display the

                    classification label in a user-interface. Colors are defined by the admin

                    or co-admin who created the classification in the Box web app.'
            - description: Details about the classification applied to this file.
            - nullable: true
          uploader_display_name:
            allOf:
            - title: Uploader display name
              type: string
              example: Ellis Wiggins
              nullable: false
              description: 'The display name of the user that uploaded the file. In most cases this is the

                name of the user logged in at the time of the upload.


                If the file was uploaded using a File Request form that requires the user to

                provide an email address, this field is populated with that email address. If

                an email address was not required in the File Request form, this field is set

                to return a value of `File Request`.


                In all other anonymous cases where no email was provided this field

                will default to a value of `Someone`.'
          disposition_at:
            type: string
            format: date-time
            nullable: true
            description: The retention expiration timestamp for the given file
            example: '2012-12-12T10:53:43-08:00'
          shared_link_permission_options:
            type: array
            example:
            - can_preview
            nullable: true
            description: 'A list of the types of roles that user can be invited at

              when sharing this file.'
            items:
              type: string
              enum:
              - can_preview
              - can_download
              - can_edit