# July 15, 2026 

** July 15, 2026 Karbon API release adds a Roles endpoint and a FileDetails endpoint for retrieving and downloading a file by key. **
---

## List Roles

`GET /v3/Roles` returns the active, non-default roles configured for your tenant.

```http
GET /v3/Roles
```

```json
{
  "@odata.count": 2,
  "value": [
    { "Key": "abc123", "Name": "Accountant" },
    { "Key": "def456", "Name": "Partner" }
  ]
}
```

Results are sorted by `Name` ascending. Filter by `Name` with the `eq` operator, and page results with `$top` and `$skip` (maximum page size 200).

```http
GET /v3/Roles?$filter=Name eq 'Partner'
```

## Retrieve file details and download by key

Two new endpoints let you look up a previously uploaded file and download it again using the `FileContextKey` returned by `GET /v3/FileList/{EntityType}`.

`GET /v3/FileDetails/{key}` returns the current details of a single file:

```http
GET /v3/FileDetails/S8bsBjvCRJ3
```

```json
{
  "FileContextKey": "S8bsBjvCRJ3",
  "FileName": "image.jpeg",
  "FileSize": 7316,
  "MimeType": "image/jpeg",
  "DownloadUrl": "/v3/Files?token=...",
  "DateCreated": "2024-07-18T23:44:26Z",
  "IsArchived": false
}
```

`DownloadUrl` is a download URL that includes a token valid for 15 minutes — this is the same token format `GET /v3/FileList/{EntityType}` returns.

`GET /v3/FileDetails/{key}/Download` returns a `302 Found` response with a `Location` header that points to a fresh download URL, so you can fetch the file from one stable address. You will need to include your API access credentials when following the redirect URL.

```http
GET /v3/FileDetails/S8bsBjvCRJ3/Download
```

Both endpoints return `404 Not Found` when the key doesn't exist or belongs to another tenant.