# November 9, 2026 

** November 9, 2026 Karbon API release lets you list every file on a work item in one call, adds work item folders so you can upload straight into a folder and move files between folders, and lets you sort GET /v3/Payments with $orderby. **
---

## List the Files on a Work Item

`GET /v3/WorkItems/{WorkItemKey}/Files` returns every file on a work item, ready to download, straight from the work item's key:

```http
GET https://api.karbonhq.com/v3/WorkItems/4jgPTtcXxwC2/Files?$filter=IsArchived eq false&$top=100
```

```json
{
  "@odata.count": 132,
  "@odata.nextLink": "https://api.karbonhq.com/v3/WorkItems/4jgPTtcXxwC2/Files?$filter=IsArchived eq false&$top=100&$skip=100",
  "value": [
    {
      "FileContextKey": "3kTq8wNpXb2R",
      "FileName": "2026 Tax Return.pdf",
      "FileSize": 482113,
      "MimeType": "application/pdf",
      "DateCreated": "2026-11-09T21:14:05Z",
      "IsArchived": false,
      "IsShared": true,
      "DownloadUrl": "/v3/Files?token=...",
      "FolderPath": "Final/Tax Returns"
    },
    ...
  ]
}
```

Each file comes with its `DownloadUrl`, so you can download it without looking it up first. Files are returned newest first; follow `@odata.nextLink` for the next page.

| Option | Supported |
|---|---|
| `$filter` | `eq` on `IsArchived`, `IsShared`, `Source`, `MimeType` and `FolderPath`, combined with `and`. `FolderPath` matches ignoring case. |
| `$orderby` | `DateCreated` |
| `$top` / `$skip` | Up to `500` per page |

It works on every account. `FolderPath` is `null` for files that aren't in a folder.

## Work Item Folders

On accounts that use work item folders, you can now see a work item's folders, list the files in a folder, and put files in them. A folder is identified by its `Path`: the folder names from the top-level folder down, joined with `/`, such as `Final/Tax Returns`.

### List a work item's folders

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

```json
{
  "value": [
    { "Name": "Received", "Parent": null, "Path": "Received" },
    { "Name": "API Uploads", "Parent": "Received", "Path": "Received/API Uploads" },
    { "Name": "Final", "Parent": null, "Path": "Final" },
    { "Name": "Tax Returns", "Parent": "Final", "Path": "Final/Tax Returns" }
  ]
}
```

`Parent` is the parent folder's `Path`, or `null` for a top-level folder. The endpoint doesn't support query options. It returns an empty list when work item folders aren't turned on for the account.

### List the files in a folder

Filter the work item's files on `FolderPath`:

```http
GET https://api.karbonhq.com/v3/WorkItems/{WorkItemKey}/Files?$filter=FolderPath eq 'Final/Tax Returns'
```

### Upload a file into a folder

`POST /v3/Files` accepts a new optional `folder_path` form field. Send it with exactly one `workitem_keys` value and no other keys:

```bash
curl -X POST https://api.karbonhq.com/v3/Files \
  -H "Authorization: Bearer {token}" \
  -H "AccessKey: {key}" \
  -F "file=@./tax-return.pdf;type=application/pdf" \
  -F "workitem_keys=4jgPTtcXxwC2" \
  -F "folder_path=Final/Tax Returns"
```

The `201` response includes the file's `FolderPath`. Leave `folder_path` out, or send it blank, to upload to the work item's root.

A `folder_path` that doesn't match exactly one of the work item's folders, a client portal folder, or an account without work item folders returns a `400`. If the folder changes while the file is uploading (for example, it's deleted), the upload is removed and the request returns a `409`.

### Move a file between folders

`PATCH /v3/FileDetails/{FileContextKey}` moves a work item file into one of its work item's folders:

```http
PATCH https://api.karbonhq.com/v3/FileDetails/{FileContextKey}
```

```json
{
  "FolderPath": "Final/Tax Returns"
}
```

Send `"FolderPath": null` to move the file back to the work item's root. `FolderPath` is the only property that can be patched, and it must be sent. The request returns a `204`, or a `200` with the file's details when you send `Prefer: return=representation`.

Files can be moved out of a client portal folder, but not into one. A `FolderPath` that doesn't match exactly one folder, a file that isn't on a work item, or an account without work item folders returns a `400`.

### FolderPath on file responses

`GET /v3/FileList/{EntityType}` and `GET /v3/FileDetails/{FileContextKey}` now return each file's `FolderPath`, or `null` when the file isn't in a folder.

## Sort Payments with $orderby

`GET /v3/Payments` now accepts `$orderby` on `PaymentDate`, `PaymentReference` or `GrossAmount`, ascending or descending:

```http
GET https://api.karbonhq.com/v3/Payments?$orderby=PaymentDate desc&$top=100
```

- Sort on one property at a time. Any other property, or more than one, returns a `400`.
- `PaymentReference` sorts as text, so `KPY-10000` comes before `KPY-9999`.

Refer to the [API documentation](https://karbonhq.github.io/karbon-api-reference/#get-/v3/Payments) for more information on listing payments.