Files

Delete a file by ID

File API

Version: 2.11.5

Request to delete a file. This will delete the file and all historic versions.

Parameters

authorizationstring

Required

Example: "355fa5a6-f37d-11ed-93c1-00155d19a71b"

UUID of a file.

Example: "00000000-0000-0000-0000-000000000000"

The customer's organisation ID.

Example: "00000000-0000-0000-0000-000000000000"

The ID of the workspace in the organization.

Returns

204

The file has been deleted.

Endpoint

DELETE

/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/{file_id}

Request

curl -X DELETE 'https://{service_host}/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/{file_id}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

No response body.

Download a file by ID

File API

Version: 2.11.5

Request file metadata and a delegated download link for a specified file by ID. The download link should be followed to download the file contents from blob storage. This link is pre-signed and will expire after 30 minutes. Set the include_versions query parameter to true to get the complete list of available versions. Set the version query parameter to request a download link for that specific version of the specified file. If version is not set, the latest version of the file will be returned.

Parameters

authorizationstring

Required

Example: "355fa5a6-f37d-11ed-93c1-00155d19a71b"

UUID of a file.

Example: "00000000-0000-0000-0000-000000000000"

The customer's organisation ID.

Example: "00000000-0000-0000-0000-000000000000"

The ID of the workspace in the organization.

Example: "1223372036854775807"

Optional version ID for the desired file version. By default, the response will return the latest version.

Optional inclusion of the DownloadFile.versions. By default, the response will return versions as null.

Optional flag to include deleted files. By default, the response will not include deleted files.

Returns

200

An object containing file metadata and at least one download link. Optionally, the object will also contain a link for each file version.

created_atdate-time

created_byUserInfo | null

deleted_atdate-time | null

deleted_byUserInfo | null

downloadstring

etagstring

file_iduuid

modified_atdate-time

modified_byUserInfo | null

namestring

pathstring

selfstring

sizeinteger

version_idint64

versionsFileVersionResponse[] | null

Endpoint

GET

/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/{file_id}

Request

curl -X GET 'https://{service_host}/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/{file_id}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "created_at": "2024-07-29T15:51:28.071Z",
  "created_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  },
  "deleted_at": "2024-07-29T15:51:28.071Z",
  "deleted_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  },
  "download": "string",
  "etag": "string",
  "file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "modified_at": "2024-07-29T15:51:28.071Z",
  "modified_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  },
  "name": "string",
  "path": "string",
  "self": "string",
  "size": 0,
  "version_id": "string",
  "versions": [
    {
      "created_at": "2024-07-29T15:51:28.071Z",
      "created_by": {
        "email": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      },
      "file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "link": "string",
      "name": "string",
      "path": "string",
      "size": 0,
      "version_id": "string"
    }
  ]
}

Update a file

File API

Version: 2.11.5

Preview

Request an upload link for a new version of the specified file. If the file does not exist an error will be returned. Follow up a successful request with a call to the returned pre-signed upload link. Specify a binary body containing the file to upload, with the addition of header key-value pair x-ms-blob-type: BlockBlob. The upload link is pre-signed and will expire after 30 minutes.

Including a version_id parameter allows creating a link to a blob with uncommitted blocks, i.e. the upload has not been completed properly, or the original pre-signed link has expired. Uncommitted blocks are valid for up to one week, after which they are automatically deleted.

Including a deleted parameter with a value of false will restore a deleted file.

Preview API

This API functionality is currently in preview. Preview APIs may be unstable within the preview period: they may change without notice. You must set the header API-Preview: opt-in to opt into using this functionality.

Parameters

authorizationstring

Required

Example: "355fa5a6-f37d-11ed-93c1-00155d19a71b"

UUID of a file.

Example: "00000000-0000-0000-0000-000000000000"

The customer's organisation ID.

Example: "00000000-0000-0000-0000-000000000000"

The ID of the workspace in the organization.

Example: "1223372036854775807"

(Optional) version ID to fetch a link for.

When set to false, the operation will attempt to restore a deleted file.

Returns

200

An object containing a pre-signed upload link. Submit the file content to the link.

file_iduuid

uploadstring

version_idint64

Endpoint

PUT

/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/{file_id}

Request

curl -X PUT 'https://{service_host}/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/{file_id}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "upload": "string",
  "version_id": "string"
}

Delete a file by path

File API

Version: 2.11.5

Request to delete a file. This will delete the file and all historic versions.

Parameters

authorizationstring

Required

Examples: "a/b/file.txt", "a/new%20file.txt"

Path to the file.

Example: "00000000-0000-0000-0000-000000000000"

The customer's organisation ID.

Example: "00000000-0000-0000-0000-000000000000"

The ID of the workspace in the organization.

Returns

204

The file has been deleted.

Endpoint

DELETE

/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/path/{file_path}

Request

curl -X DELETE 'https://{service_host}/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/path/{file_path}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

No response body.

Download a file by path

File API

Version: 2.11.5

Request file metadata and a delegated download link for a specified file by path. The download link should be followed to download the file contents. This link is pre-signed and will expire after 30 minutes. Set the include_versions query parameter to true to get the complete list of available versions. Set the version query parameter to request a download link for that specific version of the specified file. If version is not set, the latest version of the file will be returned.

Parameters

authorizationstring

Required

Examples: "a/b/file.txt", "a/new%20file.txt"

Path to the file.

Example: "00000000-0000-0000-0000-000000000000"

The customer's organisation ID.

Example: "00000000-0000-0000-0000-000000000000"

The ID of the workspace in the organization.

Example: "1223372036854775807"

Optional version ID for the desired file version. By default, the response will return the latest version.

Optional inclusion of the DownloadFile.versions. By default, the response will return versions as null.

Returns

200

An object containing file metadata and at least one download link. Optionally, the object will also contain a link for each file version.

created_atdate-time

created_byUserInfo | null

deleted_atdate-time | null

deleted_byUserInfo | null

downloadstring

etagstring

file_iduuid

modified_atdate-time

modified_byUserInfo | null

namestring

pathstring

selfstring

sizeinteger

version_idint64

versionsFileVersionResponse[] | null

Endpoint

GET

/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/path/{file_path}

Request

curl -X GET 'https://{service_host}/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/path/{file_path}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "created_at": "2024-07-29T15:51:28.071Z",
  "created_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  },
  "deleted_at": "2024-07-29T15:51:28.071Z",
  "deleted_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  },
  "download": "string",
  "etag": "string",
  "file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "modified_at": "2024-07-29T15:51:28.071Z",
  "modified_by": {
    "email": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  },
  "name": "string",
  "path": "string",
  "self": "string",
  "size": 0,
  "version_id": "string",
  "versions": [
    {
      "created_at": "2024-07-29T15:51:28.071Z",
      "created_by": {
        "email": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      },
      "file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "link": "string",
      "name": "string",
      "path": "string",
      "size": 0,
      "version_id": "string"
    }
  ]
}

Upload a file

File API

Version: 2.11.5

Preview

Request an upload link for a new version of the specified file. If the folders in the file path do not exist, they will be created. If the file already exists, a new version will be created with the updated file content. Follow up a successful request with a call to the returned pre-signed upload link. Specify a binary body containing the file to upload, with the addition of header key-value pair x-ms-blob-type: BlockBlob. The upload link is pre-signed and will expire after 30 minutes.

Including a version_id parameter allows creating a link to data with uncommitted blocks, i.e. the upload has not been completed properly, or the original pre-signed link has expired. Uncommitted blocks are valid for up to one week, after which they are automatically deleted.

Preview API

Parameters

authorizationstring

Required

Examples: "a/b/file.txt", "a/new%20file.txt"

Path to the file.

Example: "00000000-0000-0000-0000-000000000000"

The customer's organisation ID.

Example: "00000000-0000-0000-0000-000000000000"

The ID of the workspace in the organization.

Example: "1223372036854775807"

(Optional) version ID to fetch a link for.

Returns

200

An object containing a pre-signed upload link. Submit the file content to the link.

file_iduuid

uploadstring

version_idint64

Endpoint

PUT

/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/path/{file_path}

Request

curl -X PUT 'https://{service_host}/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files/path/{file_path}' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "upload": "string",
  "version_id": "string"
}

List folder contents

File API

Version: 2.11.5

Request to list files. The maximum number of results returned is limited to 5000.

Parameters

authorizationstring

Required

Example: "00000000-0000-0000-0000-000000000000"

The customer's organisation ID.

Example: "00000000-0000-0000-0000-000000000000"

The ID of the workspace in the organization.

Default: 5000

The number of results to return.

The number of results to skip.

When true, only files that have been deleted will be returned

Example: "00000000-0000-0000-0000-000000000000"

The ID of the author to filter on.

Example: "drilling_data"

The name of the file to filter on. Will perform a case insensitive partial match, so the query file_name=gold will match a file with the name allgoldcolumns.csv.

Example: "gte:2023-03-10T22:56:53Z"

A date or dates (max 2) to filter files by. Dates may contain operator prefixes, in the form <operator>:<datetime>. The following operators are available (lt=less than, lte=less than or equal to, gt=greater than, gte=greater than or equal to).If you omit the operator, then it is assumed the operator is 'equal to'. In this case you may only supply one date. The dates must also be in a valid ISO 8601 format.Dates may include a UTC offset. If the offset is omitted, the timezone is assumed to be UTC.

Example: "00000000-0000-0000-0000-000000000000"

The ID of the last person to modify the file to filter on.

Example: "gte:2023-03-10T22:56:53Z"

Example: "00000000-0000-0000-0000-000000000000"

The UUID of the user that deleted a file.

Example: "gte:2023-03-10T22:56:53Z"

Example: "order_by=modified_at,desc:created_at"

A comma separated list of fields to order by, where the default sort order is ascending. To specify the sort order, prefix the field name with either asc: or desc: for ascending or descending respectively. Field names can be one of the following known sort fields: created_at, modified_at, deleted_at

Returns

200

A list of files

countinteger

created_atdate-time

created_byUserInfo | null

deleted_atdate-time | null

deleted_byUserInfo | null

etagstring

file_iduuid

selfstring

modified_atdate-time

modified_byUserInfo | null

namestring

pathstring

sizeinteger

version_idint64

limitinteger

nextstring | null

prevstring | null

selfstring

offsetinteger

totalinteger

Endpoint

GET

/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files

Request

curl -X GET 'https://{service_host}/file/v2/orgs/{organisation_id}/workspaces/{workspace_id}/files' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

{
  "count": 0,
  "files": [
    {
      "created_at": "2024-07-29T15:51:28.071Z",
      "created_by": {
        "email": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      },
      "deleted_at": "2024-07-29T15:51:28.071Z",
      "deleted_by": {
        "email": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      },
      "etag": "string",
      "file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "links": {
        "self": "string"
      },
      "modified_at": "2024-07-29T15:51:28.071Z",
      "modified_by": {
        "email": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      },
      "name": "string",
      "path": "string",
      "size": 0,
      "version_id": "string"
    }
  ],
  "limit": 0,
  "links": {
    "next": "string",
    "prev": "string",
    "self": "string"
  },
  "offset": 0,
  "total": 0
}

Delete a file by ID​

Parameters

Request headers

Request headers

Path parameters

Path parameters

file_iduuidRequired

organisation_iduuidRequired

workspace_iduuidRequired

Returns

204

Endpoint

Request

Response

Download a file by ID​

Parameters

Request headers

Request headers

Path parameters

Path parameters

file_iduuidRequired

organisation_iduuidRequired

workspace_iduuidRequired

Query parameters

Query parameters

version_idint64 | null

include_versionsboolean

deletedboolean

Returns

200

Schema

Endpoint

Request

Response

Update a file​

Parameters

Request headers

Request headers

Path parameters

Path parameters

file_iduuidRequired

organisation_iduuidRequired

workspace_iduuidRequired

Query parameters

Query parameters

version_idint64 | null

deletedboolean

Returns

200

Schema

Endpoint

Request

Response

Delete a file by path​

Parameters

Request headers

Request headers

Path parameters

Path parameters

file_pathstringRequired

organisation_iduuidRequired

workspace_iduuidRequired

Returns

204

Endpoint

Request

Response

Download a file by path​

Parameters

Request headers

Request headers

Path parameters

Path parameters

file_pathstringRequired

organisation_iduuidRequired

workspace_iduuidRequired

Query parameters

Query parameters

version_idint64 | null

include_versionsboolean

Delete a file by ID

Download a file by ID

Update a file

Delete a file by path

Download a file by path

Upload a file

List folder contents