Find item for shared link

get
https://api.box.com/2.0
/shared_items

Return the file or folder represented by a shared link.

Shared items are any files or folders that are represented by a shared link, which can originate within the current enterprise or within another one.

This endpoint allows an application to retrieve information about a shared item when only given a shared link.

Request

Bearer [ACCESS_TOKEN]
application/json

Query Parameters

string arrayin queryoptional
id,type,name

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.

Request Headers

stringin header
required
shared_link=[link]&shared_link_password=[password]

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]

stringin header
optional
1

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.

Response

Returns a full file or folder object if the shared link is valid and the user has access to it.

none

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.

application/jsonClient error

An unexpected client error.

get
Find item for shared link
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -X GET https://api.box.com/2.0/shared_items \
     -H 'Authorization: Bearer <ACCESS_TOKEN>'
     -H "BoxApi: shared_link=https://cloud.box.com/shared/static/gjasdasjhasd&shared_link_password=letmein"
Java
String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456";
String password = "foo";
BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink, password);
Node
client.sharedItems.get(
    'https://app.box.com/s/1a2b3c4d5e',
    null,
    {fields: 'type,id,parent,extension,shared_link'},
    callback
);
iOS
client.sharedItems.get(
    sharedLinkURL: "https://app.box.com/s/qqwertyuiopasdfghjklzxcvbnm123456"
) { (result: Result<SharedItem, BoxSDKError>) in
    guard case let .success(item) = result else {
        print("Error resolving shared item")
        return
    }

    print("The shared link resolves to item:")
    switch item {
    case let .file(file):
        print("- File \(file.name) (ID: \(file.id))")
    case let .folder(folder):
        print("- Folder \(file.name) (ID: \(file.id))")
    case let .webLink(webLink):
        print("- Web Link \(file.name) (ID: \(file.id))")
    }
}

Response Example

{
  "id": 12345,
  "type": "file",
  "allowed_invitee_roles": [
    "editor"
  ],
  "content_created_at": "2012-12-12T10:53:43-08:00",
  "content_modified_at": "2012-12-12T10:53:43-08:00",
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": 11446498,
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "description": "Contract for Q1 renewal",
  "etag": 1,
  "file_version": {
    "id": 12345,
    "type": "file_version",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
  },
  "has_collaborations": true,
  "is_externally_owned": true,
  "item_status": "active",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "modified_by": {
    "id": 11446498,
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "name": "Contract.pdf",
  "owned_by": {
    "id": 11446498,
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "parent": {
    "id": 12345,
    "type": "folder",
    "etag": 1,
    "name": "Contracts",
    "sequence_id": 3
  },
  "path_collection": {
    "entries": [
      {
        "id": 12345,
        "etag": 1,
        "type": "folder",
        "sequence_id": 3,
        "name": "Contracts"
      }
    ],
    "total_count": 1
  },
  "purged_at": "2012-12-12T10:53:43-08:00",
  "sequence_id": 3,
  "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
  "shared_link": {
    "access": "open",
    "download_count": 3,
    "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
    "effective_access": "company",
    "effective_permission": "can_download",
    "is_password_enabled": true,
    "permissions": {
      "can_download": true,
      "can_preview": true
    },
    "preview_count": 3,
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "vanity_url": "https://acme.app.box.com/v/my_url/"
  },
  "size": 629644,
  "trashed_at": "2012-12-12T10:53:43-08:00"
}