Find file for shared link | Sample

3 parameters

fieldsarray<string>optional

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.

if-none-matchstringoptional

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.

boxapistringrequired

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]`.

3 status codes

200Returns a full file resource if the shared link is valid and the user has access to it.

idstringrequired

The unique identifier that represent 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`.

etagstringoptional

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

typestringrequired

The value will always be `file`.

Allowed:file

sequence_idobjectoptional

namestringoptional

The name of the file.

sha1stringoptional

The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.

file_versionobjectoptional

descriptionstringoptional

The optional description of this file. If the description exceeds 255 characters, the first 255 characters are set as a file description and the rest of it is ignored.

sizeintegeroptional

The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.

path_collectionobjectoptional

created_atstringoptional

The date and time when the file was created on Box.

modified_atstringoptional

The date and time when the file was last updated on Box.

trashed_atstringoptional

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

purged_atstringoptional

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

content_created_atstringoptional

The date and time at which this file was originally created, which might be before it was uploaded to Box.

content_modified_atstringoptional

The date and time at which this file was last updated, which might be before it was uploaded to Box.

created_byobjectoptional

modified_byobjectoptional

owned_byobjectoptional

shared_linkobjectoptional

parentobjectoptional

item_statusstringoptional

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.

Allowed:activetrasheddeleted

version_numberstringoptional

The version number of this file.

comment_countintegeroptional

The number of comments on this file.

permissionsobjectoptional

tagsobjectoptional

lockobjectoptional

extensionstringoptional

Indicates the (optional) file extension for this file. By default, this is set to an empty string.

is_packagebooleanoptional

Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files.

expiring_embed_linkobjectoptional

watermark_infoobjectoptional

is_accessible_via_shared_linkbooleanoptional

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

allowed_invitee_rolesarray<string>optional

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

is_externally_ownedbooleanoptional

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

has_collaborationsbooleanoptional

Specifies if this file has any other collaborators.

metadataobjectoptional

expires_atstringoptional

When the file will automatically be deleted.

representationsobjectoptional

classificationobjectoptional

uploader_display_nameobjectoptional

disposition_atstringoptional

The retention expiration timestamp for the given file.

shared_link_permission_optionsarray<string>optional

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

is_associated_with_app_itembooleanoptional

This field will return true if the file or any ancestor of the file 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 file.

collectionsarray<Collection>optional

The collections that this file belongs to. For more information, see the [collections guide](https://developer.box.com/guides/collections).

is_download_availablebooleanoptional

Whether the file's binary content is eligible to be downloaded. This is a content-level flag and does not reflect whether the current user is authorized to download the file. Use `permissions.can_download`, when available, for that.

download_urlstringoptional

A pre-authorized, expiring URL for directly downloading the file's content. Requires authentication and is valid only for the current session. This field is only returned for files, not folders or web links.

authenticated_download_urlstringoptional

A stable API URL for the file content endpoint, `/2.0/files/{id}/content`. Unlike `download_url`, authorization is evaluated when the URL is requested with a valid access token. This field is only returned for files, not folders or web links.

allowed_shared_link_access_levelsarray<SharedLinkAccessLevel>optional

The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this file. The list depends on item policy and user authorization, so it may be narrower than the levels available to the owner. An empty array means no access level is available to this user.

304Returns 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.

defaultAn unexpected client error.

typestringoptional

The value will always be `error`.

Allowed:error

statusintegeroptional

The HTTP status of the response.

codestringoptional

A Box-specific error code.

Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed

messagestringoptional

A short message describing the error.

context_infoobjectoptional

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.

help_urlstringoptional

A URL that links to more information about why this error occurred.

request_idstringoptional

A unique identifier for this response, which can be used when contacting Box support.

Error handling

Any other status is an error: An unexpected client error.

import { Client } from "acme-sdk";

const client = new Client({
  baseUrl: "https://api.acme.com",
  auth: {
    clientId: process.env.CLIENT_ID,
    clientSecret: process.env.CLIENT_SECRET,
  },
  retry: {
    maxAttempts: 3,
    retryOn: [
      408,
      425,
      429,
      500,
      502,
      503,
      504,
    ],
    backoffMs: 500,
    maxBackoffMs: 8000,
  },
  timeoutMs: 30000,
});

const result = await client.sharedItems.list({ fields: "example" });

{
  "id": "12345",
  "etag": "1",
  "type": "file",
  "sequence_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Contract.pdf",
  "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
  "file_version": {
    "id": null,
    "type": null,
    "sha1": null
  },
  "description": "Contract for Q1 renewal",
  "size": 629644,
  "path_collection": {
    "total_count": 1,
    "entries": [
      {}
    ]
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "trashed_at": "2012-12-12T10:53:43-08:00",
  "purged_at": "2012-12-12T10:53:43-08:00",
  "content_created_at": "2012-12-12T10:53:43-08:00",
  "content_modified_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "modified_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "owned_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "shared_link": {
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
    "vanity_url": "https://acme.app.box.com/v/my_url/",
    "vanity_name": "my_url",
    "access": "open",
    "effective_access": "company",
    "effective_permission": "can_download",
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "is_password_enabled": true,
    "permissions": {
      "can_download": true,
      "can_preview": true,
      "can_edit": false
    },
    "download_count": 3,
    "preview_count": 3
  },
  "parent": {
    "id": "12345",
    "etag": "1",
    "type": "folder",
    "sequence_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Contracts"
  },
  "item_status": "active",
  "version_number": "1",
  "comment_count": 10,
  "permissions": {
    "can_delete": true,
    "can_download": true,
    "can_invite_collaborator": true,
    "can_rename": true,
    "can_set_share_access": true,
    "can_share": true,
    "can_annotate": true,
    "can_comment": true,
    "can_preview": true,
    "can_upload": true,
    "can_view_annotations_all": true,
    "can_view_annotations_self": true,
    "can_apply_watermark": true
  },
  "tags": "example_value",
  "lock": {
    "id": "11446498",
    "type": "lock",
    "created_by": {
      "id": null,
      "type": null,
      "name": null,
      "login": null
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "expired_at": "2012-12-12T10:53:43-08:00",
    "is_download_prevented": true,
    "app_type": "office_wopiplus"
  },
  "extension": "pdf",
  "is_package": true,
  "expiring_embed_link": {
    "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
    "expires_in": 3600,
    "token_type": "bearer",
    "restricted_to": [
      {
        "scope": null,
        "object": null
      }
    ],
    "url": "https://cloud.app.box.com/preview/expiring_embed/..."
  },
  "watermark_info": {
    "is_watermarked": true,
    "is_watermark_inherited": false,
    "is_watermarked_by_access_policy": false
  },
  "is_accessible_via_shared_link": true,
  "allowed_invitee_roles": [
    "editor"
  ],
  "is_externally_owned": true,
  "has_collaborations": 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
      }
    }
  },
  "expires_at": "2012-12-12T10:53:43-08:00",
  "representations": {
    "entries": [
      {
        "content": {
          "url_template": null
        },
        "info": {
          "url": null
        },
        "properties": {
          "dimensions": null,
          "paged": null,
          "thumb": null
        },
        "representation": "png",
        "status": {
          "state": null
        }
      }
    ]
  },
  "classification": {
    "name": "Top Secret",
    "definition": "Content that should not be shared outside the company.",
    "color": "#FF0000"
  },
  "uploader_display_name": "Example Name",
  "disposition_at": "2012-12-12T10:53:43-08:00",
  "shared_link_permission_options": [
    "can_preview"
  ],
  "is_associated_with_app_item": true,
  "collections": [
    {
      "id": "11446498",
      "type": "collection",
      "name": "Favorites",
      "collection_type": "favorites"
    }
  ],
  "is_download_available": true,
  "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
  "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
  "allowed_shared_link_access_levels": [
    "open"
  ]
}

Request

Response

Errors