# September 23, 2026 

** September 23, 2026 Karbon API release adds paging, sorting, filtering and an IsShared flag to the file list endpoint, makes UserRoleAssignments patchable on Work Items, and rejects $top=0 with a 400. **
---

## Paging, Sorting and Filtering on the File List

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

```http
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
```

| Option | Supported values |
|---|---|
| `$filter` | `IsArchived`, `IsShared`, `Source`, `MimeType` — `eq` only, combined with `and` |
| `$orderby` | `DateCreated` or `DateCreated desc` |
| `$skip` | Number of files to skip after filtering and sorting |
| `$top` | Page size, maximum `100` |

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:

```json
{
  "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:

```http
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`:

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

```json
{
  "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.`