September 23, 2026

Paging, Sorting and Filtering on the File List

GET /v3/FileList/{EntityType} now accepts similar filtering options to other endpoints.

GET https://api.karbonhq.com/v3/FileList/WorkItem?EntityKey=3bXVhdMHgc9P&$filter=IsArchived eq false and MimeType eq 'application/pdf'&$orderby=DateCreated asc&$skip=50&$top=50

All options are optional. Omitting returns a list of files, with the most recently added first.

The response now includes a TotalCount — the number of files matching the filter, before paging — so you can build pagination controls without fetching every page:

{
  "EntityKey": "3bXVhdMHgc9P",
  "EntityType": "WorkItem",
  "TotalCount": 128,
  "Attachments": [ ... ]
}

Filtering or sorting on any other property, or using operators such as or or contains, returns a 400.

IsShared on the File List

Each file in the GET /v3/FileList/{EntityType} response now includes an IsShared boolean indicating whether the file is visible to the client. Files uploaded by a client, or attached to a Client Task, External Comment, Approval or eSignature, are always shared. Files shared through Karbon’s full-access sharing are also true.

Filter to client-visible files only:

GET https://api.karbonhq.com/v3/FileList/Contact?EntityKey=7wPqXnT4mBjK&$filter=IsShared eq true

IsShared is read-only. There is currently no way to change a file’s shared state through the API.

Patch UserRoleAssignments on a Work Item

PATCH /v3/WorkItems/{WorkItemKey} now accepts UserRoleAssignments, so you can reassign the users holding roles on a work item without a full PUT:

PATCH https://api.karbonhq.com/v3/WorkItems/{WorkItemKey}

{
  "UserRoleAssignments": [
    { "RoleKey": "2mYzTtly89Lq", "UserProfileKey": "2Qy48WVCRBcP" }
  ]
}

The array replaces the work item’s existing role assignments. Reassigning a role also moves any time estimates on that role to the new user, matching the behaviour of PUT. Retrieve role keys from GET /v3/Roles and user keys from GET /v3/Users.

$top=0 Returns a 400

Requesting $top=0 on any list endpoint now returns a 400 with the message $top must be greater than zero.