Get shared link for folder

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

folder_id

string

required

The unique identifier that represent a folder.

The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/folder/123 the folder_id is 123.

The root folder of a Box account is always represented by the ID 0.

Query Parameters

fields

string

required

Explicitly request the shared_link fields to be returned for this item.

Response

Returns the base representation of a folder with the additional shared link information.

A full representation of a folder, as can be returned from any folder API endpoints by default. A standard representation of a folder, as returned from any folder API endpoints by default. A mini representation of a file version, used when nested under another resource. The bare basic representation of a folder, the minimal amount of fields returned when using the fields query parameter.

string

required

The unique identifier that represent a folder.

The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/folders/123 the folder_id is 123.

Example:

"12345"

type

enum<string>

required

The value will always be folder.

Available options:

folder

Example:

"folder"

etag

string | null

The HTTP etag of this folder. This can be used within some API endpoints in the If-Match and If-None-Match headers to only perform changes on the folder if (no) changes have happened.

Example:

"1"

sequence_id

string | null

A numeric identifier that represents the most recent user event that has been applied to this item.

This can be used in combination with the GET /events-endpoint to filter out user events that would have occurred before this identifier was read.

An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the sequence_id in the event is smaller than or equal to the sequence_id in the originally fetched resource.

Example:

"3"

name

string

The name of the folder.

Example:

"Contracts"

created_at

string<date-time> | null

The date and time when the folder was created. This value may be null for some folders such as the root folder or the trash folder.

Example:

"2012-12-12T10:53:43-08:00"

modified_at

string<date-time> | null

The date and time when the folder was last updated. This value may be null for some folders such as the root folder or the trash folder.

Example:

"2012-12-12T10:53:43-08:00"

description

string

The optional description of this folder.

Maximum string length: 256

Example:

"Legal contracts for the new ACME deal"

size

integer<int64>

The folder size in bytes.

Be careful parsing this integer as its value can get very large.

Example:

629644

path_collection

Path collection · object

The tree of folders that this folder is contained in, starting at the root.

Show child attributes

created_by

User (Mini) · object

The user who created this folder.

Show child attributes

modified_by

User (Mini) · object

The user who last modified this folder.

Show child attributes

trashed_at

string<date-time> | null

The time at which this folder was put in the trash.

Example:

"2012-12-12T10:53:43-08:00"

purged_at

string<date-time> | null

The time at which this folder is expected to be purged from the trash.

Example:

"2012-12-12T10:53:43-08:00"

content_created_at

string<date-time> | null

The date and time at which this folder was originally created.

Example:

"2012-12-12T10:53:43-08:00"

content_modified_at

string<date-time> | null

The date and time at which this folder was last updated.

Example:

"2012-12-12T10:53:43-08:00"

owned_by

User (Mini) · object

The user who owns this folder.

Show child attributes

shared_link

Shared link · object

The shared link for this folder. This will be null if no shared link has been created for this folder.

Show child attributes

folder_upload_email

object

The folder_upload_email parameter is not null if one of the following options is true:

The Allow uploads to this folder via email and the Only allow email uploads from collaborators in this folder are enabled for a folder in the Admin Console, and the user has at least Upload permissions granted.
The Allow uploads to this folder via email setting is enabled for a folder in the Admin Console, and the Only allow email uploads from collaborators in this folder setting is deactivated (unchecked).

If the conditions are not met, the parameter will have the following value: folder_upload_email: null.

Show child attributes

parent

Folder (Mini) · object

The optional folder that this folder is located within.

This value may be null for some folders such as the root folder or the trash folder.

Show child attributes

item_status

enum<string>

Defines if this item has been deleted or not.

active when the item has is not in the trash
trashed when the item has been moved to the trash but not deleted
deleted when the item has been permanently deleted.

Available options:

active,

trashed,

deleted

Example:

"active"

item_collection

Items · object

A page of the items that are in the folder.

This field can only be requested when querying a folder's information, not when querying a folder's items.

Show child attributes

sync_state

enum<string>

Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.

Available options:

synced,

not_synced,

partially_synced

Example:

"synced"

has_collaborations

boolean

Specifies if this folder has any other collaborators.

Example:

true

permissions

object

Describes the permissions that the current user has for this folder.

Show child attributes

tags

string[]

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.

Required array length: 1 - 100 elements

Example:

["approved"]

can_non_owners_invite

boolean

Specifies if users who are not the owner of the folder can invite new collaborators to the folder.

Example:

true

is_externally_owned

boolean

Specifies if this folder is owned by a user outside of the authenticated enterprise.

Example:

true

metadata

Item metadata instances · object

An object containing the metadata instances that have been attached to this folder.

Each metadata instance is uniquely identified by its scope and templateKey. There can only be one instance of any metadata template attached to each folder. 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.

Show child attributes

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
    }
  }
}

is_collaboration_restricted_to_enterprise

boolean

Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations.

Example:

true

allowed_shared_link_access_levels

enum<string>[]

A list of access levels that are available for this folder.

For some folders, like the root folder, this will always be an empty list as sharing is not allowed at that level.

Available options:

open,

company,

collaborators

Example:

["open"]

allowed_invitee_roles

enum<string>[]

A list of the types of roles that user can be invited at when sharing this folder.

Available options:

editor,

viewer,

previewer,

uploader,

previewer uploader,

viewer uploader,

co-owner

Example:

["editor"]

watermark_info

object

Details about the watermark applied to this folder.

Show child attributes

is_accessible_via_shared_link

boolean

Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder.

Example:

true

can_non_owners_view_collaborators

boolean

Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder.

It also restricts non-owners from inviting new collaborators.

Example:

true

classification

object

Details about the classification applied to this folder.

Show child attributes

is_associated_with_app_item

boolean

This field will return true if the folder or any ancestor of the folder is associated with at least one app item. Note that this will return true even if the context user does not have access to the app item(s) associated with the folder.

Example:

true