# API Reference

## Request Parameters

### `case_token`
- **Type:** `uuid`  
- **Required:** Yes  
- **Description:** Globally unique identifier for the case.

### `starting_after`
- **Type:** `uuid`  
- **Description:** A cursor representing an item's token after which a page of results should begin. Used to retrieve the next page of results after this item.

### `ending_before`
- **Type:** `uuid`  
- **Description:** A cursor representing an item's token before which a page of results should end. Used to retrieve the previous page of results before this item.

### `page_size`
- **Type:** `integer`  
- **Default:** 50  
- **Description:** Page size (for pagination). Must be between 1 and 100.

# 200 Case files

**Response Object**

### `data`
- **Type:** `array of objects`  
- **Required:** Yes  
- **Description:** A file attached to a case. Status-dependent fields are always present but may be `null`:
  - `upload_url`, `upload_url_expires`, and `upload_constraints` are populated when `status` is `PENDING` or `REJECTED`
  - `download_url` and `download_url_expires` are populated when `status` is `READY`
  - `failure_reason` is populated when `status` is `REJECTED`

### File Object

- **token**
  - **Type:** `uuid`  
  - **Required:** Yes  
  - **Description:** Globally unique identifier for the file

- **name**
  - **Type:** `string`  
  - **Required:** Yes  
  - **Description:** Name of the file

- **mime_type**
  - **Type:** `string | null`  
  - **Required:** Yes  
  - **Description:** MIME type of the file, available once the file is ready

- **size_bytes**
  - **Type:** `int64 | null`  
  - **Required:** Yes  
  - **Description:** Size of the file in bytes, available once the file is ready

- **status**
  - **Type:** `string`  
  - **Required:** Yes  
  - **Description:** Lifecycle status of a case file:
    - `PENDING` - An upload URL has been issued and the file is awaiting upload
    - `READY` - The file has been uploaded and validated; a download URL is available
    - `REJECTED` - File validation failed; see `failure_reason` for details

### Status Enum: 
- `PENDING`
- `READY`
- `REJECTED`

- **upload_url**
  - **Type:** `string | null`  
  - **Required:** Yes  
  - **Description:** Presigned URL the client uses to upload the file

- **upload_url_expires**
  - **Type:** `date-time | null`  
  - **Required:** Yes  
  - **Description:** Date and time at which the upload URL expires

- **upload_constraints**
  - **Type:** `null`  
  - **Required:** Yes  
  - **Description:** Constraints that the uploaded file must satisfy

- **download_url**
  - **Type:** `string | null`  
  - **Required:** Yes  
  - **Description:** Presigned URL the client uses to download the file

- **download_url_expires**
  - **Type:** `date-time | null`  
  - **Required:** Yes  
  - **Description:** Date and time at which the download URL expires

- **failure_reason**
  - **Type:** `string | null`  
  - **Required:** Yes  
  - **Description:** Reason the file was rejected, when applicable

- **created**
  - **Type:** `date-time`  
  - **Required:** Yes  
  - **Description:** Date and time at which the file record was created

- **updated**
  - **Type:** `date-time`  
  - **Required:** Yes  
  - **Description:** Date and time at which the file record was last updated

### `has_more`
- **Type:** `boolean`  
- **Required:** Yes

```

# Example Response:

```json
{
  "data": [
    {
      "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "mime_type": "string",
      "size_bytes": 0,
      "status": "PENDING",
      "upload_url": "string",
      "upload_url_expires": "2026-07-18T00:25:56.304Z",
      "upload_constraints": {
        "accepted_mime_types": ["string"],
        "max_size_bytes": 0
      },
      "download_url": "string",
      "download_url_expires": "2026-07-18T00:25:56.304Z",
      "failure_reason": "string",
      "created": "2026-07-18T00:25:56.304Z",
      "updated": "2026-07-18T00:25:56.304Z"
    }
  ],
  "has_more": true
}
```