Box Developer Documentation
Log in
Latest version

Find file for shared link

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

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

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.

Related Guides

Request

bearer [ACCESS_TOKEN]
application/json

Request Headers

stringin headerrequired
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 headeroptional
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.

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.

Response

application/jsonFile (Full)

Returns a full file resource 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 file. This indicates that the file has not changed since it was last requested.

application/jsonClient error

An unexpected client error.

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

Request Example

Learn more about Box SDK versioning strategy.


cURL
curl -i -X GET "https://api.box.com/2.0/shared_items" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "boxapi: shared_link=https://app.box.com/s/gjasdasjhasd&shared_link_password=letmein"
Node/TypeScript v10
await userClient.sharedLinksFiles.findFileForSharedLink(
  {} satisfies FindFileForSharedLinkQueryParams,
  {
    boxapi: ''.concat(
      'shared_link=',
      fileFromApi.sharedLink!.url,
      '&shared_link_password=Secret123@',
    ) as string,
  } satisfies FindFileForSharedLinkHeadersInput,
);
Python v10
user_client.shared_links_files.find_file_for_shared_link(
    "".join(
        [
            "shared_link=",
            file_from_api.shared_link.url,
            "&shared_link_password=Secret123@",
        ]
    )
)
.NET v10
await userClient.SharedLinksFiles.FindFileForSharedLinkAsync(queryParams: new FindFileForSharedLinkQueryParams(), headers: new FindFileForSharedLinkHeaders(boxapi: string.Concat("shared_link=", NullableUtils.Unwrap(fileFromApi.SharedLink).Url, "&shared_link_password=Secret123@")));
Swift v10
try await userClient.sharedLinksFiles.findFileForSharedLink(queryParams: FindFileForSharedLinkQueryParams(), headers: FindFileForSharedLinkHeaders(boxapi: "\("shared_link=")\(fileFromApi.sharedLink!.url)\("&shared_link_password=Secret123@")"))
Java v10
userClient.getSharedLinksFiles().findFileForSharedLink(new FindFileForSharedLinkQueryParams(), new FindFileForSharedLinkHeaders(String.join("", "shared_link=", fileFromApi.getSharedLink().getUrl(), "&shared_link_password=Secret123@")))
Java v5
String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456";
String password = "foo";
BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink, password);
Python v4
file = client.get_shared_item('https://app.box.com/s/gjasdasjhasd', password='letmein')
Node v4
client.sharedItems.get(
    'https://app.box.com/s/1a2b3c4d5e',
    null,
    {fields: 'type,id,parent,extension,shared_link'},
    callback
);

Response Example

{
  "id": "12345",
  "type": "file",
  "allowed_invitee_roles": [
    "editor"
  ],
  "classification": {
    "color": "#FF0000",
    "definition": "Content that should not be shared outside the company.",
    "name": "Top Secret"
  },
  "comment_count": 10,
  "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",
  "disposition_at": "2012-12-12T10:53:43-08:00",
  "etag": "1",
  "expires_at": "2012-12-12T10:53:43-08:00",
  "expiring_embed_link": {
    "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
    "expires_in": 3600,
    "restricted_to": [
      {
        "object": {
          "etag": "1",
          "id": "12345",
          "type": "folder",
          "name": "Contracts",
          "sequence_id": "3"
        },
        "scope": "item_download"
      }
    ],
    "token_type": "bearer",
    "url": "https://cloud.app.box.com/preview/expiring_embed/..."
  },
  "extension": "pdf",
  "file_version": {
    "id": "12345",
    "type": "file_version",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
  },
  "has_collaborations": true,
  "is_accessible_via_shared_link": true,
  "is_associated_with_app_item": true,
  "is_externally_owned": true,
  "is_package": true,
  "item_status": "active",
  "lock": {
    "id": "11446498",
    "type": "lock",
    "app_type": "office_wopiplus",
    "created_at": "2012-12-12T10:53:43-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "login": "ceo@example.com",
      "name": "Aaron Levie"
    },
    "expired_at": "2012-12-12T10:53:43-08:00",
    "is_download_prevented": true
  },
  "metadata": {
    "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
      }
    }
  },
  "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": [
      {
        "etag": "1",
        "id": "12345",
        "type": "folder",
        "name": "Contracts",
        "sequence_id": "3"
      }
    ],
    "total_count": 1
  },
  "permissions": {
    "can_annotate": true,
    "can_comment": true,
    "can_delete": true,
    "can_download": true,
    "can_invite_collaborator": true,
    "can_preview": true,
    "can_rename": true,
    "can_set_share_access": true,
    "can_share": true,
    "can_upload": true,
    "can_view_annotations_all": true,
    "can_view_annotations_self": true
  },
  "purged_at": "2012-12-12T10:53:43-08:00",
  "representations": {
    "entries": [
      {
        "content": {
          "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
        },
        "info": {
          "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
        },
        "properties": {
          "dimensions": "2048x2048",
          "paged": "true",
          "thumb": "true"
        },
        "representation": "png",
        "status": {
          "state": "success"
        }
      }
    ]
  },
  "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_edit": false,
      "can_preview": true
    },
    "preview_count": 3,
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "vanity_name": "my_url",
    "vanity_url": "https://acme.app.box.com/v/my_url/"
  },
  "shared_link_permission_options": [
    "can_preview"
  ],
  "size": 629644,
  "tags": [
    "approved"
  ],
  "trashed_at": "2012-12-12T10:53:43-08:00",
  "uploader_display_name": "Ellis Wiggins",
  "version_number": "1",
  "watermark_info": {
    "is_watermarked": true
  }
}