File API release notes

Supported API versions

The following File API versions are currently supported:

• 2.0.0
• 1.0.0

Changes

2.6.0

All created_at datetimes now include an explicit timezone

While all times returned from the API are in UTC, they were being returned as naive datetimes. This change makes them timezone aware, appending a Z to the timestamp.

{
-     "created_at": "2024-03-27T04:27:04"
+     "created_at": "2024-03-27T04:27:04Z"
}

File paths/names are now case-insensitive

Previously, two files with the same path and name could exist at the same time, as long as they were using different cases. This is no longer possible. For example, if you have a file at the path a/b/file.txt and you then upload a file at /a/b/FILE.txt, it will be treated as a new version of the existing file.

2.5.0

All version_id fields are now expected to be strings, and not integers

This change is to allow API consumers to avoid issues that come with handling large numbers. The version ID still represents a positive 64bit signed integer, but will always be handled as a string.

{
    "id": "05f93511-35fd-4e80-96a3-47d1cf102aee",
    "version_id": "1223372036854775807"
}

2.4.3, 1.3.1

• Route definitions that previously used a * suffix parameter now explicitly use a {file_path} parameter.

2.4.2

• Version 2 "list files" API now includes total parameter, indicating the total number of records that match query filters provided (outside of limit and offset).

2.4.0

Rename author to created_by in all responses

Each file upload results in a new file version, so there is only ever a created_by field on each version. Versions cannot be modified, hence no modified_by. The contents remain the same:

{
    "id": "05f93511-35fd-4e80-96a3-47d1cf102aee",
    "name": "Joe Bloggs",
    "email": "Joe.Bloggs@bentley.com"
}

2.0.0

New features

• Version 2 of the API is served at file/v2/...
• Files are now stored in workspaces. A workspace must be created before any files can be uploaded.

Uploading a file

PUT file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/path/{file_path}

File uploads now return a file_id, version_id, and an upload link.

Uploading a new file version

Files can now be uploaded via a path or file ID.

PUT /file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/path/{file_path}

PUT /file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/{file_id}

Download a file

Files can now be downloaded via a path or file ID.

GET .../file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/path/{file_path}

GET .../file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/{file_id}

Delete a file

Files can now be soft-deleted via a path or file ID.

DELETE .../file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/path/{file_path}

DELETE .../file/v2/orgs/{org_id}/workspaces/{workspace_id}/files/{file_id}

List files

GET .../file/v2/orgs/{org_id}/workspaces/{workspace_id}/files