November 9, 2026

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:

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

{
  "@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.

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

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

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

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:

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:

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

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

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 for more information on listing payments.