• Register

File System API

The File System API allows you to perform the normal file system actions: create, update, move, copy, delete, download, and list information about files and folders. Since most use cases involve some basic file system operation, this is one of our core APIs.

URL Encoding

Note that the Path parameter in the API endpoints described below must be URL encoded in a special way. Each element of the path needs to be separately encoded. I.e. the forward slashes ('/') in the path must not be encoded, but the text in between must be. This is required because filesystem paths on Egnyte can contain characters which are not permitted in the path portion of a URL.

For example, this path: Shared/example?path/$file.txt should be encoded as Shared/example%3Fpath/%24file.txt

ID Based References

The URLs for each endpoint below uses paths to reference files and folders.  You may also reference files and folders using persistent IDs.

Files

  • For file details, the endpoint path would be /pubapi/v1/fs/ids/file/GROUP_ID
  • To download a file, the endpoint path would be /pubapi/v1/fs-content/ids/file/GROUP_ID
  • To download a specific version, the endpoint path would be /pubapi/v1/fs-content/ids/file/GROUP_ID?entry_id=ENTRY_ID
  • To delete a file, the endpoint path would be /pubapi/v1/fs/ids/file/{GROUP_ID}
  • To delete a specific version, the endpoint path would be /pubapi/v1/fs/ids/file/{Group ID}?entry_id={ENTRY_ID}
Note that in the Event API response, the entry_id is called the target_id and the group_id is called the target_group_id.

Folders

  • For folder details, the endpoint path would be /pubapi/v1/fs/ids/folder/FOLDER_ID

Listing Parameters (For a Folder)

ParameterTypeDescriptionPossible Values
name string Name of the folder Any name that is acceptable per characters and length of a folder path
uploaded epoch timestamp in milliseconds Time when the folder has been uploaded (created). An int value that is a valid epoch timestamp
lastModified epoch timestamp in milliseconds The latest time that any file in the folder (but not within subfolders) has been modified. An int value that is a valid epoch timestamp
count int The maximum number of items to return Any possible integer
offset int The zero-based index from which to start returning items. This is used for paginating the folder listing 0 or any positive integer
path string The full path of the folder as requested Any valid path in the domain
folder_id string The id of the folder requested The unique value as stored in Egnyte
parent_id string The id of the parent folder requested The unique value as stored in Egnyte
total_count int The total number of items actually available to return A valid positive integer
is_folder boolean Whether the resource is a folder A valid boolean
public_links string The folder option setting as to how "Allow public inks from this folder for" was set "files_folders", "files" or "disabled"
allow_links boolean The folder option setting as to whether "Allow users to share links in this folder" was set true or false
restrict_move_delete boolean Indication of how the "Who can delete or move this folder" setting is set true if set to 'Admins and Owners' and false if set to 'Admins, Owners and users with full permissions'
folders array The list of subfolder information A list of information about the subfolder of the current folder. The information contains the following fields with the same definitions as a folder: name, lastModified, path, folder_id, is_folder, and folder_id
files array The list of file resources Any valid file resource, excluding the list of version resources, as described above

File Resource

ParameterTypeDescriptionPossible Values
checksum string Checksum value of the current version of the file used to determine file changes Any valid checksum string
size int Size of the file in bytes of the version Any positive integer
path string Full path of the file Any valid path in the domain
name string Name of the file Any valid filename
locked boolean Status of the lock on the file true if the file is locked, false otherwise
is_folder boolean Whether the resource is a folder This value is always false for a file
entry_id string Unique id of the current version of the file A unique id of the specific version of a file
group_id string The id to reference the file as a whole A unique id identifying the file localed at the path
parent_id string The id of the parent folder requested The unique value as stored in Egnyte
last_modified string Last modified time of the current version of a file. If not passed during upload (e.g. when willing to preserve the original "last_modified" time for the file), the upload time will be used. A valid date and time
uploaded_by string Username of the user that uploaded the version A valid unique username in the domain
uploaded epoch timestamp in milliseconds Uploaded time of the current version of the file. It might be different from the "last_modified" time when the "last_modified" time has been passed during upload. An int value that is a valid epoch timestamp
num_versions int The total number of versions associated with the specific file path A valid positive int
versions array The list of all prior versions of the files (e.g. if there are 6 versions in num_versions, there should be 5 versions in the array) A list of valid version resources

File Version Resource

Parameter Type Description Possible Values
is_folder boolean Whether the resource is a folder This value should always be false for a file version
entry_id string The id of the specific version of the file A valid unique string identifying the file version
checksum string The checksum for the specific version of the file Any string checksum value
last_modified string Last modified time of the version of a file. If not passed during upload, the upload time will be used. A string of the date and time
uploaded_by string Username of the user that uploaded the specific version A valid username of the domain
uploaded epoch timestamp in milliseconds The date and time the version was uploaded An int value that is a valid epoch timestamp
size int Size in bytes of the specific version A positive integer

Common Response Codes

Error Description
200 or 201 Successful operation
401 Authentication failure
403 User not authorized (not enough permissions)
404 File or folder resource not found
409 Forbidden file or folder upload location (e.g. /, /Shared, /Private, etc)

API Methods

Create a Folder

POST /pubapi/v1/fs/{Full Path to Folder}

Parameters:

Parameter Description Required Possible Values
action Defines the action to be taken Yes Must be add_folder

Method-specific Response Codes

Error Code Error Message HTTP Code Troubleshooting
Forbidden The request could not be completed due to a conflict with the current state of the resource. 403 A file or folder with the same name already exists or you are creating a folder in an incorrect path.

Request Examples

POST /pubapi/v1/fs/Shared/test HTTP/1.1
    Host: apidemo.egnyte.com
    Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
    Content-Type: application/json
    {
      "action": "add_folder"
    }       
curl -v -X POST -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" -H "Content-Type: application/json" --data '{"action":"add_folder"}' https://apidemo.egnyte.com/pubapi/v1/fs/Shared/test

Sample Response

{
    "path" : "/Shared/test",
    "folder_id": "4abfdc36-2a1b-44b4-8792-01bf43c0d0f9"
}

Upload a File

Creates or updates a file.

When uploading files larger than 100 MB, consider using the Chunked Upload flow.

POST /pubapi/v1/fs-content/{Full Path to File}

Request Headers

Parameter Description RequiredPossible Values
X-Sha512-Checksum SHA512 hash of entire file that can be used for validating upload integrity. No 6cb2785692b05c5eff397109457031bde7ab236982364cc7b51e319c67c463d7721c82c024ef3f74b9dff d388be6dc8120edc214e7d0eadaaf2c5e0eb44845a3
Last-Modified Indicates last modified date for file. If omitted, the current time will be used as the last modified date. No Timestamp e.g. Sun, 26 Aug 2012 03:55:29 GMT

Method-specific Response Codes

Error Code Error Message HTTP Code Troubleshooting
Bad Request This request is invalid. 400 Missing parameters, file filtered out (e.g. .tmp file), or file is too large (larger than plan limit)

Request Examples

POST /pubapi/v1/fs-content/Shared/Documents/test.txt HTTP/1.1
    Host: apidemo.egnyte.com
    Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
    Content-Disposition: form-data; name="file"; filename="~/Desktop/test.txt"
    Content-Type: text/plain
curl -v -X POST -H "Authorization: Bearer 2v8q2bc6uvxtgghwmwvnvcp4" --upload-file ~/Desktop/test.txt https://acme.egnyte.com/pubapi/v1/fs-content/Shared/Documents/test.txt

Move File or Folder

Moves a file or folder.

POST /pubapi/v1/fs/{Full Path to File/Folder}
POST /pubapi/v1/fs/ids/{file or folder}/{ID}

Request Parameters

Parameter Description Required Possible Values
action Defines the action to be taken Yes Must be move
destination Determines where the file/folder will be moved Yes Full absolute destination path of file or folder
permissions Determines how permissions of moved file or folder are derived No keep_original, inherit_from_parent

Request Examples

POST /pubapi/v1/fs/Shared/fromFolder HTTP/1.1
    Host: apidemo.egnyte.com
    Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
    Content-Type: application/json
    {
      "action": "move",
      "destination": "/Shared/toFolder"
    }
curl -v -X POST -H "Authorization: Bearer 2v8q2bc6uvxtgghwmwvnvcp4" -H "Content-Type: application/json" --data '{"action":"move", "destination":"/Shared/toFolder"}' https://acme.egnyte.com/pubapi/v1/fs/Shared/fromFolder

Expected Response

The response is a HTTP 200 OK Code that confirms that the file (or folder) has been moved to the destination folder.

Sample Response When Moving a Folder

{
   "path":"/Shared/toFolder",
   "folder_id":"5919b927-13ef-4f74-a735-4dac2c4c6302"
}

Sample Response When Moving a File

{
  path: "/Shared/toFolder/sample.txt", 
  group_id: "8163f6a1-09e7-488c-b95f-094c9d75ff1b"
}

Delete a File or Folder

Deletes a file or folder.

DELETE /pubapi/v1/fs/{Full Path to File/Folder}
DELETE /pubapi/v1/fs/ids/{"file" or "folder"}/{Group ID}

Request Examples

Please select a format and resource type to get the corresponding sample requests.

DELETE /pubapi/v1/fs/Shared/test/mydocument.docx HTTP/1.1
    Host: apidemo.egnyte.com
    Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
DELETE /pubapi/v1/fs/Shared/test HTTP/1.1
    Host: apidemo.egnyte.com
    Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
curl -v -X DELETE -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" http://apidemo.egnyte.com/pubapi/v1/fs/Shared/test/mydocument.docx
          
curl -v -X DELETE -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" http://apidemo.egnyte.com/pubapi/v1/fs/Shared/test

Request Parameters

ParameterDescriptionRequiredPossible Values
entry_id Specifies the entry ID of the file version to delete. Entry IDs are shown in the detail listing for a file. No Entry id for a specific version of the desired file

Expected Response

The response is a HTTP 200 OK Code that confirms the file or folder has been moved to the trash.

Sample Response

        {
        "parent_folder_path": "/Shared/test"
        }

Copy File or Folder

Copies a file or folder.

POST /pubapi/v1/fs/{Full Path to File/Folder}
POST /pubapi/v1/fs/ids/{file or folder}/{ID}

Request Parameters

Parameter Description Required Possible Values
action Defines the action to be taken Yes Must be copy
destination Determines where the file/folder will be copied Yes Full absolute destination path of file or folder.  Note that if the destination path does not contain the original folder name only the subfolders and files within the folder will be copied.  For example, if the source folder is at "Shared/A" and you are copying to destination "Shared/B", all contents of folder A will be copied to "B"; however, if the destination is "Shared/B/A" the folder "A" will be created within "B" as well.
permissions Determines how permissions are handled as part of a folder copy. Permissions can either be copied (keep_original), or inherited from the destination folder (inherit_from_parent).

Please, note that if the destination folder already exists, then the value of the "permissions" parameter will be ignored and the existing permissions of the destination folder will not be changed.

For example, if the source folder is "Shared/A" and you are copying it to a destination "Shared/B/A" and this "Shared/B/A" folder already exists, the permissions set on the destionation folder will be preserved regardless of the value of the "permissions" parameter		 No keep_original, inherit_from_parent.  If neither is specified, the default behavior is to use the workgroup settings configuration, found at Configuration -> Security & Authentication -> Keep permissions on folder move & copy

Method-specific Response Codes

Error Description
413 File size exceeds limit or account storage quota exceeded

Request Examples

Please select a format and resource type to get the corresponding sample requests.

POST /pubapi/v1/fs/Shared/fromFolder/test.txt HTTP/1.1
    Host: apidemo.egnyte.com
    Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
    Content-Type: application/json
    {
      "action": "copy",
      "destination": "/Shared/toFolder/test.txt"
    }

Expected Response

The response is a HTTP 200 OK Code that confirms the file has been copied to the destination folder.

Sample Response

{
   "path":"/Shared/toFolder/test.txt",
   "group_id":"ac086094-d21f-44d7-9e54-ba7c7066542f"
}

POST /pubapi/v1/fs/Shared/fromFolder HTTP/1.1
    Host: apidemo.egnyte.com
    Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
    Content-Type: application/json
    {
      "action": "copy",
      "destination": "/Shared/toFolder",
      "permissions": "inherit_from_parent"
    }

Expected Response

The response is a HTTP 200 OK Code that confirms the folder has been copied to the destination folder.

Sample Response

{
   "path":"/Shared/toFolder",
   "folder_id":"5919b927-13ef-4f74-a735-4dac2c4c6302"
}

curl -v -X POST -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" -H "Content-Type: application/json" -d '{"action":"copy", "destination":"/Shared/toFolder/test.txt"}' https://acme.egnyte.com/pubapi/v1/fs/Shared/fromFolder/test.txt

Expected Response

The response is a HTTP 200 OK Code that confirms the file has been copied to the destination folder.

Sample Response

{
   "path":"/Shared/toFolder/test.txt",
   "group_id":"ac086094-d21f-44d7-9e54-ba7c7066542f"
}

curl -v -X POST -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" -H "Content-Type: application/json" -d '{"action":"copy", "destination":"/Shared/toFolder", "permissions": "inherit_from_parent"}' https://acme.egnyte.com/pubapi/v1/fs/Shared/fromFolder

Expected Response

The response is a HTTP 200 OK Code that confirms the folder has been copied to the destination folder.

Sample Response

{
   "path":"/Shared/toFolder",
   "folder_id":"5919b927-13ef-4f74-a735-4dac2c4c6302"
}

Download File

Downloads a file. This method also supports range downloads, which we recommend implementing as a best practice.

GET /pubapi/v1/fs-content/{Full Path to File}
GET /pubapi/v1/fs-content/ids/file/{ID}

Method-specific Request Header

Parameter Description Required Possible Values
Range The range of bytes to download. Best practice for downloading files, especially for large files (over 1GB), unstable internet connections, and faster download speeds since sections of the file are downloaded in parallel. No bytes={byte range} e.g. 0-999 will download first thousand bytes. For more information about byte ranges see section 14.36.1 of RFC 2068.

Request Parameters

Parameter Description Required Possible Values
entry_id Specifies the entry ID of the file version to download. Entry IDs are shown in the detail listing for a file. No Entry id for a specific version of the desired file

Method-specific Response Headers

Header Description Sample Value
X-Sha512-Checksum SHA512 hash of entire file that can be used for validating upload integrity. 6cb2785692b05c5eff397109457031bde7ab236982364cc7b51e319c67c463d7721c82c024ef3f74b9dff d388be6dc8120edc214e7d0eadaaf2c5e0eb44845a3
Last-Modified Indicates last modified date for file. Sun, 26 Aug 2012 03:55:29 GMT
ETag Current value of the entity tag that can be used to compare whether two versions of a resource are the same. 9c4c2443-5dbc-4afa-8d04-5620a778093c
Content-Type Specifies format of response body text/plain;charset=UTF-8
Content-Length Specifies length of response body 126

Method-specific Response Codes

Error Code Error Message HTTP Code Troubleshooting
Bad Request This request is invalid. 400 File is larger than what is allowed for this account

List File or Folder

List information about a file or folder (including folder contents).

GET /pubapi/v1/fs/{Full Path to File/Folder}
GET /pubapi/v1/fs/ids/{file or folder}/{ID}

Query String Parameters

These parameters can be used to paginate a folder list, sort by intrinsic and custom metadata fields, and fetch metadata values for each item in the folder. For more information on custom metadata, please refer to the Metadata API.

Parameter Description Required Possible Values
list_content For folders, this option determines whether the contents of the folder (files and subfolders) are included in the response. For files, when true, this will return a list of all of the versions of the file. No true or false
allowed_link_types If true, then show allowed_file_link_types, allowed_folder_link_types fields, and allow_upload_links fields. No true or false
count The maximum number of items to return No Any possible integer
offset The zero-based index from which to start returning items. This is used for paginating the folder listing. No Zero or any positive integer
sort_by The field that should be used for sorting No name or last_modified or uploaded_by or custom_metadata
key The custom metadata field to sort by Only when sort_by is set to custom_metadata The metadata field in the format: namespace.key
sort_direction The direction of the sort No ascending or descending
perms If true, the response includes a permissions key for the folder that lists the different users and groups who have permissions along with their permission level No true or false
include_perm If true, the response returns the current user's permission level on the folder and subfolders No true or false
list_custom_metadata Whether custom metadata for each item should be returned No true or false
include_locks If true, the response returns the information about the user who locked the file No true or false
include_collaboration If true, the response returns the information about the app and integration that should be used for collaboration. To take effect this requires that include_locks=true is set. No true or false

Sample cURL Call (For a Folder)

curl -v -H "Authorization: Bearer 2v8q2bc6uvxtgghwmwvnvcp4" \
https://apidemo.egnyte.com/pubapi/v1/fs/Shared/MyDocuments/MyFolder

Sample Response Body (For a Folder Resource as described above)

{
      "name": "MyFolder",
      "lastModified": 1554182069000,
      "uploaded": 1554178564015,
      "count": 0,
      "offset": 0,
      "path": "/Shared/MyDocuments/MyFolder",
      "folder_id": "d7d56ebc-ce31-4ba8-a6b3-292ffb43f215", 
      "parent_id": "b0sceebc-2edl-ab56-lapq-fb11def11123", 
      "total_count": 2,
      "is_folder": true,
      "public_links": "files_folders",
      "allow_links": true,
      "restrict_move_delete": false,
      "folders": [
          {
              "name": "subfolder1",
              "lastModified": 1554185307000,
              "uploaded": 1554185307326,
              "path": "/Shared/MyDocuments/MyFolder/subfolder1",
              "folder_id": "fc8cf940-1097-491e-bb9d-b55b5797331c",
              "is_folder": true,
              "parent_id": "d7d56ebc-ce31-4ba8-a6b3-292ffb43f215"
          }
      ],
      "files": [
          {
              "checksum": "244b99790dcc91ebc5862eb547c8179515b2369bb6db5aaa1ddd46bf0035e7ba3849ba1494b294b20b7c2a055a52d3a65ccab8a090f06cf40106528f6e23a91e",
              "size" :238428,
              "path": "/Shared/MyDocuments/MyFolder/info.pdf",
              "name": "info.pdf",
              "locked": false,
              "is_folder": false,
              "entry_id": "b563a343-184b-4bce-8331-25d2dfb8125a",
              "group_id": "01dd4abd-983b-4104-bff6-e2ad44bff357",
              "parent_id": "d7d56ebc-ce31-4ba8-a6b3-292ffb43f215",
              "last_modified": "Tue, 02 Apr 2019 05:12:44 GMT",
              "uploaded_by": "jsmith",
              "uploaded": 1554182069464,
              "num_versions": 1
          },
          {
              "checksum": "7b275cfc0650d8cdfae4e11a4d149ce72fd65654e9aa56ec475eb51cbad898bbd0413edd7e49198563757b29aff21ade1e848b33cf2da8a47af2652d88ccbfbf",
              "size": 9322,
              "path": "/Shared/MyDocuments/MyFolder/document.gdoc",
              "name": "document.gdoc",
              "locked": true,
              "is_folder": false,
              "entry_id": "d32d4628-5346-44ce-8ae6-bce367e84e60",
              "group_id": "7de6cdd8-2038-4a09-8935-9d07cf62197f",
              "parent_id": "1d12e243-0ddb-432f-820d-8b250c0c0fdc",
              "last_modified": "Mon, 23 Nov 2020 11:07:11 GMT",
              "uploaded_by": "jsmith",
              "uploaded": 1606129632000,
              "num_versions": 3,
              "lock_info": {
                    "collaboration": "ewogICJhcHBJZCIgOiAiZ2RvY3MiLAogICJpbnRlZ3JhdGlvbklkIiA6ICJnZG9jRWRpdGRvYyIKfQ==",
                    "owner_id": 1,
                    "first_name": "John",
                    "last_name": "Smith"
              }
          }
      ]
  }

Sample cURL Call (For a File)

curl -v -H "Authorization: Bearer 2v8q2bc6uvxtgghwmwvnvcp4" \
https://apidemo.egnyte.com/pubapi/v1/fs/Shared/MyDocuments/example.txt

Sample Response Body (For a File Resource as described above)

{
      "checksum": "32d919f9f96d6f8e92889e68eb2c9eb8079b2327d80a70e247a9c426f9fc5049a7a7978eb6f0ab6d129720b871637d8175e047199bcf77fe36d23d15e81886a8",
      "size": 1023,
      "path": "/Shared/MyDocuments/example.txt"
      "name": "example.txt",
      "locked": false
      "is_folder": false,
      "entry_id": "a4e2857e-9cf4-492f-9087-0a8cee324e4c",
      "group_id": "765f70fd-122f-47ed-b50d-b5e80662596b",
      "parent_id": "b0sceebc-2edl-ab56-lapq-fb11def11123",
      "last_modified": "Tue, 02 Apr 2019 05:12:44 GMT",
      "uploaded_by": "jsmith",
      "uploaded": 1554182069464,
      "num_versions": 3,
      "versions": [
          {
              "is_folder": false,
              "entry_id": "0ee550e4-854a-4ebc-a2d1-0de17714957f",
              "checksum": "2aca968ceb5452f797810a67ff283eb0b72dc334868c11f16e8cb9b8ab713e30f49a30245d16a9f187293b4971fd8a1d6c588d981799283ec1fbcc84c9fe44cb",
              "last_modified": "Fri, 29 Mar 2019 16:31:53 GMT",
              "uploaded_by": "mjohnson",
              "uploaded": 1554180282161,
              "size": 1378
          },
          {
              "is_folder": false,
              "entry_id": "1eb75cc1-af4f-4331-8e56-b2f7d1ebebe5",
              "checksum": "0a6a7ba5048971d4718da58ec0f9ba51a4bfc5691f11da4c0afa38244f474f7076bb6edf48d8bfb55bbbcf128c55918fbe96485ac1178e78ac2686a6fb4a0785",
              "last_modified": "Tue, 02 Apr 2019 04:50:14 GMT",
              "uploaded_by": "jsmith",
              "uploaded": 1554180634999,
              "size": 1108
          }
      ]
  }

Get Folder Statistics

Fetch information about folder size and item counts (for both file version and files inside the folder and all the subfolders). This information was available earlier only through the Folder Size Report.

GET /pubapi/v1/fs/ids/folder/{FOLDER_ID}/stats

Sample cURL Call For a Folder

curl -v -H "Authorization: Bearer 2v8q2bc6uvxtgghwmwvnvcp4" \
https://apidemo.egnyte.com/pubapi/v1/fs/ids/folder/f8091071-5d7b-47c9-8a33-9b9dce7397e4/stats

Sample Response Body

The "Size" is returned in Bytes: 
{
    "allVersionsSize":1732505,
    "allFilesSize":1721488,
    "filesCount":10,
    "fileVersionsCount":12,
    "foldersCount":9,
    "allVersionsSizeInKB":1691
}

Lock a File

POST /pubapi/v1/fs/{Full Path to File}
POST /pubapi/v1/fs/ids/file/{GROUP_ID}

Parameters:

Parameter Description Required Possible Values
action Defines the action to be taken Yes Must be lock
lock_token The token that must be used to unlock the file. If not provided when locking a file, a random token will be generated and returned in the response. No my lock token
lock_timeout The time in seconds that the file should be locked for. If omitted, a time of one hour will be used by default.

Note The time cannot exceed 7 days. After 7 days, all the (stale) locks will be cleared automatically.		 No 518400
collaboration Collaboration token received in the invocation call (for UI Integration Framework apps). No ZXhhbXBsZQ==

Sample Request Body

{
    "action": "lock",
    "lock_token": "my lock token",
    "lock_timeout": 7200,
    "collaboration": "ewogICJhcHBJZCIgOiAiZ2RvY3MiLAogICJpbnRlZ3JhdGlvbklkIiA6ICJnZG9jRWRpdGRvYyIKfQ=="
  }

Unlock a File

POST /pubapi/v1/fs/{Full Path to File}
POST /pubapi/v1/fs/ids/file/{GROUP_ID}

Parameters:

Parameter Description Required Possible Values
action Defines the action to be taken Yes Must be unlock
lock_token The lock_token used when locking the file must be presented to unlock the file. Yes my lock token

Sample Request Body

{
    "action": "unlock",
    "lock_token": "my lock token"
  }

Chunked Upload

The chunked upload flow provides a mechanism to upload large files.  Though not a firmly enforced requirement, we recommend using this flow for files larger than 100 MB. To upload files of smaller sizes, you can use the simpler upload flow.

POST /pubapi/v1/fs-content/{Full Path to File}
POST /pubapi/v1/fs-content/ids/file/{ID}

Chunked Upload process:

  1. Split file into chunks—recommended size is 104857600 bytes (100 MB) each.  The minimum chunk size is 10485760 (10 MB). The maximum chunk size is 1073741824 bytes (1GB).  All chunks should be the same size, except for the last chunk which can be any size.
  2. Start the process by uploading the first chunk. Save the X-Egnyte-Upload-Id header received in the response. Use the X-Egnyte-Chunk-Sha512-Checksum SHA512 hash in the response to confirm that each chunk was uploaded cleanly.
  3. Upload the rest of the chunks except the final one in any order. Use the X-Egnyte-Upload-Id identifier and X-Egnyte-Chunk-Num sequence numbers to uniquely identify each chunk. Upload chunks in parallel to get maximum throughput.
  4. When uploading the final chunk, indicate this by including the header “X-Egnyte-Last-Chunk: true”
  5. Chunks remain available for a period of 24 hours after the first chunk is uploaded.

Sample API Calls:

POST /pubapi/v1/fs-content-chunked/Shared/Documents/movie.mpeg

Common HTTP Headers:

HTTP Request Header:

Header Description Sample Value
X-Egnyte-Chunk-Num Chunk number being uploaded. The first chunk should have the number 1. 1
X-Egnyte-Chunk-Sha512-Checksum SHA512 hash of the chunk being uploaded 6cb2785692b05c5eff397109457031bde7ab236982364cc7b51e319c67c463d7721c82c024ef3f74b9dff d388be6dc8120edc214e7d0eadaaf2c5e0eb44845a3

HTTP Response Headers:

Header Description Sample Value
X-Egnyte-Upload-Id Upload identifier returned after uploading first chunk. To be used as a reference when uploading subsequent chunks. b2adfaf5-9f7d-49e5-a1ab-32389e1d1da6
X-Egnyte-Chunk-Num Chunk number being uploaded. 1
X-Egnyte-Chunk-Sha512-Checksum SHA512 hash of chunk data to be used for validating integrity of upload. cb2785692b05c5eff397109457031bde7ab236982364cc7b51e319c67c463d7721c82c024ef3f74b9dffd

Upload the first chunk

Sample Request Body

<body containing binary data for first chunk only>

Upload all but the last chunk:

Use the same X-Egnyte-Upload-Id as the first chunk.

Optionally, you can upload a specific chunk again by repeating that chunk request. This might be useful if data if the X-Egnyte-Chunk-Sha512-Checksum returned indicates that the chunk has not been uploaded properly.

Step-specific Request Headers:

Header Description Sample Value
X-Egnyte-Upload-Id Upload identifier returned after uploading first chunk. To be used as a reference when uploading subsequent chunks. b2adfaf5-9f7d-49e5-a1ab-32389e1d1da6

Sample Request Body

<body containing binary chunk data for chunk specified by X-Egnyte-Chunk-Num only>

Upload last chunk and commit file

Client must indicate that it is uploading the last chunk by passing header “X-Egnyte-Last-Chunk: true”. Server will respond with HTTP Status 200 and ETag plus SHA512 hash for the entire completed file. Client should check hash for entire file to validate uploaded content.  Details on how to compute checksums are provided below.

Optionally, you can send a final 0-byte chunk to close the chunked upload flow.  This allows you to verify the final chunk succeeded before committing the file.

Step-specific Request Header:

Header Description Value
X-Egnyte-Upload-Id Upload identifier returned after uploading first chunk. To be used as a reference when uploading subsequent chunks. b2adfaf5-9f7d-49e5-a1ab-32389e1d1da6
X-Egnyte-Last-Chunk Indicates that chunk being uploaded is the last chunk. Must be true
X-Sha512-Checksum SHA512 hash of entire file that can be used for validating upload integrity. 6cb2785692b05c5eff397109457031bde7ab236982364cc7b51e319c67c463d7721c82c024ef3f74b9dff d388be6dc8120edc214e7d0eadaaf2c5e0eb44845a3
Last-Modified Indicates last modified date for file. Sun, 26 Aug 2012 03:55:29 GMT

Sample Request Body

<body containing binary chunk data for last chunk only>

Calculating the Checksums:

Calculating Checksums for Individual Chunks:

So let's say I have a file that is split into three chunks with checksums computed as follows.

$ openssl dgst -sha512 chunk1 
  SHA512(chunk1)= 886a81ec5f9e4f66aaa77d95ccb58dc6ca4000bfb12d13351adf8cd6fb09933e0e16d057983eb8a81fffc71d71f6fc5c1649d08b20b0dc30d64ea449850b4f41

  $ openssl dgst -sha512 chunk2
  SHA512(chunk2)= 8ae7b487d9ad803e0ad85dee9320a1c3203f021e2fffe07573588e2869f097589eaa97923d75ada6f84a5eaeb7ad63f7f0a0ddc1e78053f570b8a6363abcd9f3

  $ openssl dgst -sha512 chunk3
  SHA512(chunk3)= eef77c3e9fef9277e0a3bbc8a4faaf2727481296b3d6e0143c5c661d2cd1441eeccc54d4bc086c29ea3ee918a79dcba122bd077fe3232f30f54afc7ed452cc8d

After you upload each chunk, Egnyte will compute a SHA512 checksum for that chunk and return it in the X-Egnyte-Chunk-Sha512-Checksum header.  If the checksum does not match the checksum you compute locally, the chunk was corrupted and should be sent again.

When you have sent the last chunk, we will return another checksum in the response body that looks like:
2-3-10485761-41e3a616682407fd721ef2843ac5f3966c73ae2ef0bc00fc3d8c27d69327fc3d326ce64b13163cbc7664be3e1bc1a9f8bf4c1d257fdfdab20919edbc6813f30f
This follows the form:
{Version#}-{#Chunks}-{Chunk Size}-{SHA512(SHA512 of Chunk Checksums)}
The final checksum comes in three parts which are separated by dashes ("-"):
  • Version #: This is the version of the checksum response.  This guide is written for version 2.
  • # Chunks: This is the total number of chunks provided.
  • Chunk Size: This is the size of each chunk uploaded (except for the last chunk).
  • SHA512(SHA512 of Chunk Checksums): This is the checksum of checksums computed for the full file.

Calculating the Checksum of Checksums

In addition to checking that each chunk committed properly, you can also check to see if the entire file was properly transferred.

Request Examples
$ CHECKSUM1="886a81ec5f9e4f66aaa77d95ccb58dc6ca4000bfb12d13351adf8cd6fb09933e0e16d057983eb8a81fffc71d71f6fc5c1649d08b20b0dc30d64ea449850b4f41"
  $ CHECKSUM2="8ae7b487d9ad803e0ad85dee9320a1c3203f021e2fffe07573588e2869f097589eaa97923d75ada6f84a5eaeb7ad63f7f0a0ddc1e78053f570b8a6363abcd9f3"
  $ CHECKSUM3="eef77c3e9fef9277e0a3bbc8a4faaf2727481296b3d6e0143c5c661d2cd1441eeccc54d4bc086c29ea3ee918a79dcba122bd077fe3232f30f54afc7ed452cc8d"
  $ echo -n $CHECKSUM1$CHECKSUM2$CHECKSUM3 | openssl dgst -sha512  
  
import hashlib
  m = hashlib.sha512()
  m.update("886a81ec5f9e4f66aaa77d95ccb58dc6ca4000bfb12d13351adf8cd6fb09933e0e16d057983eb8a81fffc71d71f6fc5c1649d08b20b0dc30d64ea449850b4f41")
  m.update("8ae7b487d9ad803e0ad85dee9320a1c3203f021e2fffe07573588e2869f097589eaa97923d75ada6f84a5eaeb7ad63f7f0a0ddc1e78053f570b8a6363abcd9f3")
  m.update("eef77c3e9fef9277e0a3bbc8a4faaf2727481296b3d6e0143c5c661d2cd1441eeccc54d4bc086c29ea3ee918a79dcba122bd077fe3232f30f54afc7ed452cc8d")
  m.hexdigest()
These samples should all evaluate to the final section of the checksum we return after the last chunk:
41e3a616682407fd721ef2843ac5f3966c73ae2ef0bc00fc3d8c27d69327fc3d326ce64b13163cbc7664be3e1bc1a9f8bf4c1d257fdfdab20919edbc6813f30f

version 149 as of 5 months ago by chapman