Box

Box Shared Links (Files) API

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

Documentation GitHub OpenAPI

Operations 5

GET /shared_items Box Find file for shared link #

GET /files/{file_id}#get_shared_link Box Get shared link for file #

PUT /files/{file_id}#add_shared_link Box Add shared link to file #

PUT /files/{file_id}#update_shared_link Box Update shared link on file #

PUT /files/{file_id}#remove_shared_link Box Remove shared link from file #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/box-shared-links-files-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Box Platform Shared Links (Files) API
  description: '[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.'
  termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
  contact:
    name: Box, Inc
    url: https://box.dev
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: 2.0.0
  x-box-commit-hash: '5819125043'
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server
security:
- OAuth2Security: []
tags:
- name: Shared Links (Files)
  description: 'Files shared links are URLs that are generated for files stored in Box,

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


        A shared file can be represented by a shared link,

        which can originate within the current enterprise or within another.


        This endpoint allows an application to retrieve information about a

        shared file when only given a shared link.


        The `shared_link_permission_options` array field can be returned

        by requesting it in the `fields` query parameter.'
      parameters:
      - name: if-none-match
        description: 'Ensures an item is only returned if it has changed.


          Pass in the item''s last observed `etag` value

          into this header and the endpoint will fail

          with a `304 Not Modified` if the item has not

          changed since.'
        in: header
        required: false
        example: '1'
        schema:
          type: string
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: boxapi
        description: 'A header containing the shared link and optional password for the

          shared link.


          The format for this header is as follows.


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

            the user has access to it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
        '304':
          description: 'Returns an empty response when the `If-None-Match` header matches

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

            has not changed since it was last requested.'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/{file_id}#get_shared_link:
    get:
      operationId: get_files_id#get_shared_link
      summary: Box Get shared link for file
      tags:
      - Shared Links (Files)
      x-box-tag: shared_links_files
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Gets the information for a shared link on a file.
      parameters:
      - name: file_id
        description: 'The unique identifier that represents a file.


          The ID for any file can be determined

          by visiting a file in the web application

          and copying the ID from the URL. For example,

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

          the `file_id` is `123`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'Explicitly request the `shared_link` fields

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

            additional shared link information.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: file
                    etag: '1'
                    shared_link:
                      url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
                      download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
                      vanity_url: null
                      vanity_name: null
                      effective_access: open
                      effective_permission: can_download
                      is_password_enabled: false
                      unshared_at: '2020-09-21T10:34:41-07:00'
                      download_count: 0
                      preview_count: 0
                      access: open
                      permissions:
                        can_preview: true
                        can_download: true
                        can_edit: true
        '401':
          description: 'Returned when the access token provided in the `Authorization` header

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

            have access to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `file_id` is not in a recognized format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/{file_id}#add_shared_link:
    put:
      operationId: put_files_id#add_shared_link
      summary: Box Add shared link to file
      tags:
      - Shared Links (Files)
      x-box-tag: shared_links_files
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Adds a shared link to a file.
      parameters:
      - name: file_id
        description: 'The unique identifier that represents a file.


          The ID for any file can be determined

          by visiting a file in the web application

          and copying the ID from the URL. For example,

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

          the `file_id` is `123`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'Explicitly request the `shared_link` fields

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

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

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

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

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

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


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

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

                        default setting pass the `shared_link` object with

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


                        The `company` access level is only available to paid

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

                        password to `null` to remove it.

                        Passwords must now be at least eight characters

                        long and include a number, upper case letter, or

                        a non-numeric or non-alphabetic character.

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

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


                        Custom URLs should not be used when sharing sensitive content

                        as vanity URLs are a lot easier to guess than regular shared

                        links.'
                      minLength: 12
                      example: my-shared-link
                    unshared_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: 'The timestamp at which this shared link will

                        expire. This field can only be set by

                        users with paid accounts. The value must be greater than the

                        current date and time.'
                    permissions:
                      type: object
                      properties:
                        can_download:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for downloading of files.

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

                            `open` or `company`.'
                        can_preview:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for previewing of files.

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

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

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

                            `open` or `company`.

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

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

            link attached.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: file
                    etag: '1'
                    shared_link:
                      url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
                      download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
                      vanity_url: null
                      vanity_name: null
                      effective_access: open
                      effective_permission: can_download
                      is_password_enabled: false
                      unshared_at: '2020-09-21T10:34:41-07:00'
                      download_count: 0
                      preview_count: 0
                      access: open
                      permissions:
                        can_preview: true
                        can_download: true
                        can_edit: true
        '400':
          description: Returned when there is an incorrect permission combination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '401':
          description: 'Returned when the access token provided in the `Authorization` header

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

            update.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned if the file is not found, or the user does not

            have access to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `file_id` is not in a recognized format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '412':
          description: 'Returns an error when the `If-Match` header does not match

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

            has changed since it was last requested.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/{file_id}#update_shared_link:
    put:
      operationId: put_files_id#update_shared_link
      summary: Box Update shared link on file
      tags:
      - Shared Links (Files)
      x-box-tag: shared_links_files
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Updates a shared link on a file.
      parameters:
      - name: file_id
        description: 'The unique identifier that represents a file.


          The ID for any file can be determined

          by visiting a file in the web application

          and copying the ID from the URL. For example,

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

          the `file_id` is `123`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'Explicitly request the `shared_link` fields

          to be returned for this item.'
        example: shared_link
        in: query
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shared_link:
                  description: The settings for the shared link to update.
                  type: object
                  properties:
                    access:
                      type: string
                      description: 'The level of access for the shared link. This can be

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

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

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


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

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

                        default setting pass the `shared_link` object with

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


                        The `company` access level is only available to paid

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

                        password to `null` to remove it.

                        Passwords must now be at least eight characters

                        long and include a number, upper case letter, or

                        a non-numeric or non-alphabetic character.

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

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


                        Custom URLs should not be used when sharing sensitive content

                        as vanity URLs are a lot easier to guess than regular shared

                        links.'
                      minLength: 12
                      example: my-shared-link
                    unshared_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: 'The timestamp at which this shared link will

                        expire. This field can only be set by

                        users with paid accounts. The value must be greater than the

                        current date and time.'
                    permissions:
                      type: object
                      properties:
                        can_download:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for downloading of files.

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

                            `open` or `company`.'
                        can_preview:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for previewing of files.

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

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

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

                            `open` or `company`.

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

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

            link attached.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: file
                    etag: '1'
                    shared_link:
                      url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
                      download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
                      vanity_url: null
                      vanity_name: null
                      effective_access: open
                      effective_permission: can_download
                      is_password_enabled: false
                      unshared_at: '2020-09-21T10:34:41-07:00'
                      download_count: 0
                      preview_count: 0
                      access: open
                      permissions:
                        can_preview: true
                        can_download: true
                        can_edit: true
        '400':
          description: Returned when there is an incorrect permission combination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '401':
          description: 'Returned when the access token provided in the `Authorization` header

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

            update.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned if the file is not found, or the user does not

            have access to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `file_id` is not in a recognized format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '412':
          description: 'Returns an error when the `If-Match` header does not match

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

            has changed since it was last requested.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/{file_id}#remove_shared_link:
    put:
      operationId: put_files_id#remove_shared_link
      summary: Box Remove shared link from file
      tags:
      - Shared Links (Files)
      x-box-tag: shared_links_files
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Removes a shared link from a file.
      parameters:
      - name: file_id
        description: 'The unique identifier that represents a file.


          The ID for any file can be determined

          by visiting a file in the web application

          and copying the ID from the URL. For example,

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

          the `file_id` is `123`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'Explicitly request the `shared_link` fields

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

                    is removed from the file.'
                  type:
                  - object
                  - 'null'
                  example: null
      responses:
        '200':
          description: Returns a basic representation of a file, with the shared link removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File--Full'
              examples:
                default:
                  value:
                    id: '12345'
                    type: file
                    etag: '1'
                    shared_link: null
        '401':
          description: 'Returned when the access token provided in the `Authorization` header

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

            update.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned if the file is not found, or the user does not

            have access to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `file_id` is not in a recognized format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '412':
          description: 'Returns an error when the `If-Match` header does not match

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

            has changed since it was last requested.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    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
                  can_download:
                    type: boolean
                    description: Specifies if the current user can download this item.
                    example: true
                  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
                  can_rename:
                    type: boolean
                    description: Specifies if the user can rename this item.
                    example: true
                  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
                  can_share:
                    type: boolean
                    description: Specifies if the user can create a shared link for this item.
                    example: true
              - properties:
                  can_annotate:
                    type: boolean
                    description: Specifies if the user can place annotations on this file.
                    example: true
                  can_comment:
                    type: boolean
                    description: Specifies if the user can place comments on this file.
                    example: true
                  can_preview:
                    type: boolean
                    description: Specifies if the user can preview this file.
                    example: true
                  can_upload:
                    type: boolean
                    description: Specifies if the user can upload a new version of this file.
                    example: true
                  can_view_annotations_all:
                    type: boolean
                    description: Specifies if the user view all annotations placed on this file
                    example: true
                  can_view_annotations_self:
                    type: boolean
                    description: 'Specifies if the user view annotations placed by themselves

                      on this file'
                    example: true
            - description: 'Describes the permissions that the current user has

                for this file.'
            - {}
          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.'
            - {}
          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: s

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