Items

Get HomeFolder for Current User

GET https://account.sf-api.com/sf/v3/Items 

Returns home folder for current user. Note that home folders are not available for client users, or if the account doesn't have the "My Files & Folders" feature enabled.

Returns: home folder for current user

Get Item by ID or TreeView

GET https://account.sf-api.com/sf/v3/Items(id)?includeDeleted=false&treemode=mode&sourceId=id&canCreateRootFolder=false 

Returns a single Item or a folder list structure tailored for TreeView navigation - used by clients to create folder trees for specific operations. If a TreeMode is entered then a treeview is returned, otherwise a single item is returned. Special Id's:home, favorites, allshared, connectors, box, top. home - Return home folder. favorites - Return parent favorite item; use .../Items(favorites)/Children to get the favorite folders. allshared - Return parent Shared Folders item; use .../Items(allshared)/Children to get the shared folders. connectors - Return parent Connectors item; use .../Items(connectors)/Children to get indiviual connectors. box - Return the FileBox folder. top - Returns the Top item; use .../Items(top)/Children to get the home, favorites, and shared folders as well as the connectors

Returns:

Get Item by ID

GET https://account.sf-api.com/sf/v3/Items(id)?includeDeleted=false 

Returns a single Item. Special Id's:home, favorites, allshared, connectors, box, top. home - Return home folder. favorites - Return parent favorite item; use .../Items(favorites)/Children to get the favorite folders. allshared - Return parent Shared Folders item; use .../Items(allshared)/Children to get the shared folders. connectors - Return parent Connectors item; use .../Items(connectors)/Children to get indiviual connectors. box - Return the FileBox folder. top - Returns the Top item; use .../Items(top)/Children to get the home, favorites, and shared folders as well as the connectors

Returns: a single Item

Get TreeView

GET https://account.sf-api.com/sf/v3/Items(id)?treemode=mode&sourceId=id&canCreateRootFolder=false 

Retrieves a folder list structure tailored for TreeView navigation - used by clients to create folder trees for specific operations. This operation will enforce a specific $select and $expand operators. You can provide additional $expand, for example Children, which is not added by default. The $select operator will apply to the expanded objects as well. You can also specify additional $select elements.

Returns: A tree root element.

Get TreeView

GET https://account.sf-api.com/sf/v3/Items(id)/TreeView?treemode=mode&sourceId=id&canCreateRootFolder=false 

Retrieves a folder list structure tailored for TreeView navigation - used by clients to create folder trees for specific operations. This operation will enforce a specific $select and $expand operators. You can provide additional $expand, for example Children, which is not added by default. The $select operator will apply to the expanded objects as well. You can also specify additional $select elements. [swagger-compliant]

Returns: A tree root element.

Get Symbolic Links of a Connector Group

GET https://account.sf-api.com/sf/v3/ConnectorGroups(id)/Children 

Retrieves the Symbolic Links of the provided Connector Group type. Connector Groups define classes of external data connectors - such as SharePoint, Network Shares. Symbolic Links represent a single Connector point to such classes - for example, a single SharePoint site, or a network share drive.

Returns: The list of Symbolic Links associated with the given connector group.

Get Stream

GET https://account.sf-api.com/sf/v3/Items(id)/Stream?includeDeleted=false 

Retrieves the versions of a given Stream. The ID parameter must be a StreamID, otherwise an empty list is returned. StreamID is a property of all Items, representing the "Stream", ie., the collection of all versions of a file. In contrast, an Item ID represents a single version of a file. For example, when users upload or modify an existing file, a new Item is created with the same StreamID. All default Item enumerations return only the latest version of a given stream. Use this method to retrieve previous versions of a given stream. This method carries a default OData $top parameter of 20. If more versions are required, specify the $top query option with the desired parameter.

Returns:

Get Item by Path

GET https://account.sf-api.com/sf/v3/Items/ByPath?path=/folder1/folder2/folder3 

Retrieves an item from its path. The path is of format /foldername/foldername/filename This call may redirect the client to another API provider, if the path contains a symbolic link.

Returns: An item identified by a path

Get Item by relative Path from ID

GET https://account.sf-api.com/sf/v3/Items(id)/ByPath?path=/folder1/folder2/folder3 

Retrieves an item from its path, relative to the provided ID. The path is of format /foldername/foldername/filename This call may redirect the client to another API provider, if the path contains a symbolic link.

Returns: An item identified by a path

Get Parent Item

GET https://account.sf-api.com/sf/v3/Items(id)/Parent 

Retrieves the Parent navigation property of a single Item.

Returns: the Parent Item of the give object ID.

Get Children

GET https://account.sf-api.com/sf/v3/Items(id)/Children?includeDeleted=false 

Handler for the Children navigation property of a given Item. A 302 redirection is returned if the folder is a SymbolicLink. The redirection will enumerate the children of the remote connector

Returns: the list of children under the given object ID

Get Folder Access Info

GET https://account.sf-api.com/sf/v3/Items(id)/Info 

Returns the effective Access Controls for the current authenticated user for the selected folder - i.e., the resulting set of Access Controls for the Item/User context.

This operation applies to Folders only, will return an error for other Item types.

Returns: The Folder Access Control Information

Download Item Content

GET https://account.sf-api.com/sf/v3/Items(id)/Download?includeallversions=false&includeDeleted=false&forQurantinedFiles=false 

Initiate the download operation for an item. It will return 302 redirection to the actual download link. For Folders, the download link will retrieve a ZIP archive with the contents of the Folder.

Returns: the download link for the provided item content.

Download Multiple Items

POST https://account.sf-api.com/sf/v3/Items(id)/BulkDownload?redirect=true 
            ["id1","id2"] 

Initiate the download operation for items. It will return 302 redirection to the actual download link.

Returns: the download link for the provided item content.

Create Folder

POST https://account.sf-api.com/sf/v3/Items(parentid)/Folder?overwrite=false&passthrough=false 
            { 
              "Name":"Folder Name", 
              "Description":"Description", 
              "Zone":{ "Id":"ZoneId" }, 
              "ExpirationDate": "9999-12-31T23:59:59.9999999Z" 
            } 

Creates a new Folder. The POST body must contain the serialized object. For top-level folders, use Items/Folder. The Zone object may only be provided for top-level folders. The Zone object must contain a zone ID.

Returns: the new Folder

Create Note

POST https://account.sf-api.com/sf/v3/Items(parentid)/Note 
            { 
              "Name":"Note Name", 
              "Description":"Description" 
            } 

Creates a new Note.

Returns: the new Note

Create Link

POST https://account.sf-api.com/sf/v3/Items(parentid)/Link 
            { 
              "Name":"Link Name", 
              "Description":"Description", 
              "Uri":"https://server/path" 
            } 

Creates a new Link

Returns: the new Link

Create SymbolicLink

POST https://account.sf-api.com/sf/v3/Items(accountid)/SymbolicLink 
            { 
              "Name":"RemoteFileName", 
              "Description":"Description", 
              "Zone":{ "Id":"z014766e-8e96-4615-86aa-57132a69843c" }, 
              "ConnectorGroup": { "Id":"1" } 
            } 

Creates a Symbolic Link

The body must contain either a "Link" parameter with a fully qualified URI; or use FileName + Zone to have sharefile.com attempt to convert the Connector path to an URI using a call to the Zone - using ShareFile Hash authentication mode. For active clients, it's recommended to make the convertion call to the Zone directly, using Items/ByPath=name, retriving the resulting URL, and calling this method with the Link parameter.

SymbolicLinks must be created as top-level folders - i.e., this call requires the parent to be the Item(accountid) element.

Zone defines the location of the SymbolicLink target - for example, for Network Shares connectors, the SymbolicLink will point to the StorageZone Controller that will serve the file browsing requests.

The ConnectorGroup parameter indicates the kind of symbolic link - e.g., Network Share, or SharePoint.

Returns: the new SymbolicLink

Creates SymbolicLink

POST https://account.sf-api.com/sf/v3/ConnectorGroups(id)/Children 
            { 
              "Name":"RemoteFileName", 
              "Description":"Description", 
              "Link":"https://server/provider/version/Items(id)", 
              "Zone":{ "Id":"z014766e-8e96-4615-86aa-57132a69843c" }, 
              "ConnectorGroup": { "Id":"1" } 
            } 

Returns: the new SymbolicLink

Update Item

PATCH https://account.sf-api.com/sf/v3/Items(id)?overwrite=false 
            { 
              "Name":"Name", 
              "FileName":"FileName", 
              "Description":"Description", 
              "ExpirationDate": "date", 
              "Parent": { "Id": "parentid" }, 
              "Zone": { "Id": "zoneid" } 
            } 

Updates an Item object. Please note that for a Folder, the Name and FileName properties must be consistent. If a new Name is provided, the FileName will also be updated with the new name, and viceversa. If both Name and FileName are provided, FileName is disregarded and Name will be used to update both properties.

Returns: A modified Item object. If the item Zone or Parent Zone is modified, then this method will return an Asynchronous operation record instead. Note: the parameters listed in the body of the request are the only parameters that can be updated through this call.

Update Link

PATCH https://account.sf-api.com/sf/v3/Items/Link(id)?notify=false 
            { 
              "Name":"Name", 
              "Uri":"https://server/path", 
              "Description":"Description", 
              "Parent": { "Id": "parentid" } 
            } 

Updates a Link object

Returns: A modified Link object

Update Note

PATCH https://account.sf-api.com/sf/v3/Items/Note(id)?notify=false 
            { 
              "Name":"Name", 
              "Description":"Description", 
              "Parent": { "Id": "parentid" } 
            } 

Updates a Note object

Returns: The modified Note object

Update SymbolicLink

PATCH https://account.sf-api.com/sf/v3/Items/SymbolicLink(id) 
            { 
              "Name":"Name", 
              "Description":"Description", 
              "Link": "https://server/path" 
            } 

Updates a Symbolic Link object

Returns: The modified SymbolicLink object

Delete Item

DELETE https://account.sf-api.com/sf/v3/Items(id)?singleversion=false&forceSync=false 

Removes an item

Delete Multiple Items

POST https://account.sf-api.com/sf/v3/Items(parentid)/BulkDelete?forcesync=false&deletePermanently=false 
            ["id1","id2"] 

All items in bulk delete must be children of the same parent, identified in the URI

Get Thumbnail

GET https://account.sf-api.com/sf/v3/Items(id)/Thumbnail?size=75&redirect=true 

Retrieve a thumbnail link from the specified Item.

Returns: A 302 redirection to the Thumbnail link

Get Breadcrumbs

GET https://account.sf-api.com/sf/v3/Items(id)/Breadcrumbs?path=path&bubbleSharedPassthroughs=false 

Retrieves the path from an item from the root. The return list is a Feed of Items, with the top-level folder at the first position. If this item is in a Connection path, the breadcrumbs may contain URL reference back to the parent account - and the Item in the feed will contain just the URL reference.

Returns: A feed containing the path of folders from the specified root to the item, in order

Copy Item

POST https://account.sf-api.com/sf/v3/Items(id)/Copy?targetid=itemid&overwrite=true 

Copies an item to a new target Folder. If the target folder is in another zone, the operation will return an AsyncOperation record instead. Clients may query the /AsyncOperation Entity to determine operation progress and result.

Returns: the modified source object

Unlock File

POST https://account.sf-api.com/sf/v3/Items(id)/CheckIn 

Unlock a locked file. This operation is only implemented in Sharepoint providers (/sp)

Lock File

POST https://account.sf-api.com/sf/v3/Items(id)/CheckOut 

Locks a file. This operation is only implemented in Sharepoint providers (/sp)

Discard CheckOut

POST https://account.sf-api.com/sf/v3/Items(id)/DiscardCheckOut 

Discards the existing lock on the file This operation is only implemented in Sharepoint providers (/sp)

Search

GET https://account.sf-api.com/sf/v3/Items/Search?query=abc&homefolderonly=false 

Search for Items matching the criteria of the query parameter

Returns: SearchResults

Search

GET https://account.sf-api.com/sf/v3/Items(id)/Search?query=abc&homefolderonly=false 

Search for Items matching the criteria of the query parameter

Returns: SearchResults

Advanced Simple Search

POST https://account.sf-api.com/sf/v3/Items/AdvancedSimpleSearch 
            { 
                "Query":{ 
                    "ItemType":"", 
                    "ParentID":"", 
                    "CreatorID":"", 
                    "SearchQuery":"", 
                    "CreateStartDate":"", 
                    "CreateEndDate":"", 
                    "ItemNameOnly":false 
                }, 
                "Paging":{ 
                    "Count": 50, 
                    "Skip": 0 
                }, 
                "Sort":{ 
                    "SortBy":"", 
                    "Ascending":false 
                }, 
                "TimeoutInSeconds":10 
            } 

Search for Items matching the criteria of the query parameter. Paging.PageNumber and Paging.PageSize are deprecated.

Returns: AdvancedSearchResults

Advanced Search

POST https://account.sf-api.com/sf/v3/Items/AdvancedSearch 
            { 
                "Query":{ 
                    "ItemTypes":["type1", "type2"], 
                    "ParentID":["id1", "id2"], 
                    "CreatorID":["id1", "id2"], 
                    "SearchQuery":"", 
                    "CreateStartDate":"", 
                    "CreateEndDate":"", 
                    "ItemNameOnly":false 
                }, 
                "Paging":{ 
                    "Count":50, 
                    "Skip":0 
                }, 
                "Sort":{ 
                    "SortBy":"", 
                    "Ascending":false 
                }, 
                "TimeoutInSeconds":10 
            } 

Search for Items matching the criteria of the query parameter. Paging.PageNumber and Paging.PageSize are deprecated. Default values for Paging.Count is 50 and Paging.Skip is 0.

Returns: AdvancedSearchResults

Get Web Preview Link

GET https://account.sf-api.com/sf/v3/Items(id)/WebView 

Redirects the caller to the Web Edit application for the selected item.

Returns: A redirection message to the Web Edit app for this item. It returns 404 (Not Found) if the Web Preview app doesn't support the file type.

Get List of Item Protocol Links

GET https://account.sf-api.com/sf/v3/Items(id)/ProtocolLinks(platform) 

Returns: A list of protocol links depending on the input parameter 'platform', 404 (Not Found) if not supported by the item

Get Redirection endpoint Information

GET https://account.sf-api.com/sf/v3/Items(id)/Redirection 

Returns the redirection endpoint for this Item.

This operation applies to Folders and SymbolicLinks only, will return an error for other Item types.

Returns: The Redirection endpoint Information

Get a collection of recoverable/deleted items in a folder

GET https://account.sf-api.com/sf/v3/Items(parentid)/DeletedChildren 

Get a collection of recoverable/deleted items for a user

GET https://account.sf-api.com/sf/v3/Items/UserDeletedItems?userid=xxxxx&zone=zxxxxx 

Restore expired items to their original locations

POST https://account.sf-api.com/sf/v3/Items/BulkRestore 

Permanently delete multiple items

POST https://account.sf-api.com/sf/v3/Items/BulkDeletePermanently 

Create a one-time use login Uri for the Web App.

POST https://account.sf-api.com/sf/v3/Items(id)/WebAppLink 

The user will be logged in and routed to the parent folder of the Item.

If the Item is a Folder, the user will be routed to that Folder.

Returns: Redirection populated with link in Uri field

Remove folder template association from folder

POST https://account.sf-api.com/sf/v3/Items(parentid)/RemoveTemplateAssociation 

Check if template is already part of an existing template structure

POST https://account.sf-api.com/sf/v3/Items(parentid)/CheckTemplateOwned 

Check if a versioning change would result in file deletions

POST https://account.sf-api.com/sf/v3/Items(parentid)/CheckVersioningViolation 

Check if Items would be previewable when created with a specific Parent

POST https://account.sf-api.com/sf/v3/Items(parentid)/CheckIfPreviewable 
            [ { "FileName":"file01.txt", "FileSizeBytes":256 }, { "FileName":"file02.txt", "FileSizeBytes":256 } ] 

Get Items by Data Loss Prevention scan status

GET https://account.sf-api.com/sf/v3/Items/ByDlpStatus?status=Unscanned&zone=z3c74dec-166f-47b9-bac2-0d85b629e57a&enddate=2015-07-10T01:47:22.82Z 

Upload File

POST https://account.sf-api.com/sf/v3/Items(id)/Upload?method=method&various... 
            POST https://account.sf-api.com/sf/v3/Items(id)/Upload2 
            { 
                "Method":"Method", 
                "Raw": false, 
                "FileName":"FileName", 
                "FileSize": 2048 
            } 

Prepares the links for uploading files to the target Folder. This method returns an Upload Specification object. The fields are populated based on the upload method, provider, and canResume parameters passed to the upload call. The Method determines how the URLs must be called.

There are two different URLs for upload: /sf/v3/Items(id)/Upload accepts parameters through the URL query string, while /sf/v3/Items(id)/Upload2 uses the HTTP POST message body. If using 'Upload2', the parameters must be capitalized.

Standard uploads use a single HTTP POST message to the ChunkUri address provided in the response. All other fields will be empty. Standard uploads do not support Resume.

Streamed uploads use multiple HTTP POST calls to the ChunkUri address. For each call, the client must append the parameters index, byteOffset and hash to the ChunkUri address. Index is a sequential number (zero-based) identifying the position of the chunk relative to others; byteOffset represents how many bytes precede the chunk relative to the beginning of the file; and hash contains the MD5 hash of the chunk. The last HTTP POST must also include the parameters finish=true and filehash=[MD5 hash of entire file].

Threaded uploads use multiple HTTP POST calls to ChunkUri, and can have a number of threads issuing chunks in parallel. Clients must append index, byteOffset and hash to the end of ChunkUri, as explained for Streamed uploads. After all chunks are sent, the client must call the FinishUri provided in the Upload Specification response.

If using the Threaded Uploader, the client can add the parameter fmt=json to the ChunkUri to retrieve the Item ID of the file after the upload is completed.

For all uploaders, the contents of the POST Body can either be "raw" (if the parameter raw=true is provided to the Uploader) or use MIME multi-part form encoding otherwise. Raw uploads provide the chunk content directly in the POST body and the Content-Length header specifies the size. Multi-part form encoding requires passing the file as a Form parameter named "Filedata".

For Streamed and Threaded uploads, if the CanResume parameter is specified in the call to Upload, then the fields IsResume, ResumeIndex, ResumeOffset and ResumeFileHash may be populated in the Upload Specification response. If they are, it indicates that the server has identified a partial upload with that specification and is ready to resume the upload process. The client can verify the file has not been modified based on the value of ResumeFileHash, then continue issuing calls to the ChunkUri starting from the position represented by the values of ResumeIndex and ResumeOffset. If the client decides to restart the upload, it should simply ignore the resume fields and send chunks starting from Index 0.

For all upload methods, successful HTTP POST calls to ChunkUri and FinishUri will return response code 200 with either no Content Body or with a Body of 'OK'. The response code for failed calls can be 401, indicating authentication is required; 4xx/5xx, indicating some kind of error; or 200 with Content Body of format 'ERROR:[message]'.

Returns: an Upload Specification element, containing the links for uploading, and the parameters for resume. The caller must know the protocol for sending the prepare, chunk and finish URLs returned in the spec; as well as negotiate the resume upload.