> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-api-spec-sync-1774445910.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Files API

> Upload, list, and delete files for your agents

# Files API

Manage files attached to your agents. You can upload files for an agent to access, list existing files, and delete them. All endpoints require session authentication.

## List files

```http theme={null}
GET /api/files?agentId=default
```

Returns all files for the authenticated user, optionally filtered by agent.

### Query parameters

| Parameter | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| `agentId` | string | No       | Filter files by agent ID |

### Response

```json theme={null}
{
  "files": [
    {
      "id": "clx1abc123",
      "filename": "training-data.csv",
      "url": "/api/files/download?id=clx1abc123",
      "size": 24576,
      "mimeType": "text/csv",
      "agentId": "default",
      "createdAt": "2026-03-25T10:00:00.000Z"
    }
  ],
  "totalSize": 24576,
  "count": 1
}
```

### File object

| Field       | Type   | Description                                   |
| ----------- | ------ | --------------------------------------------- |
| `id`        | string | Unique file identifier                        |
| `filename`  | string | Original filename                             |
| `url`       | string | Download URL for the file                     |
| `size`      | number | File size in bytes                            |
| `mimeType`  | string | MIME type of the file                         |
| `agentId`   | string | ID of the agent this file belongs to          |
| `createdAt` | string | ISO 8601 timestamp when the file was uploaded |

### Errors

| Code | Description          |
| ---- | -------------------- |
| 401  | Unauthorized         |
| 500  | Failed to list files |

## Upload a file

```http theme={null}
POST /api/files
```

Upload a file for an agent. The request must use `multipart/form-data` encoding.

### Request body (multipart/form-data)

| Field     | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| `file`    | File   | Yes      | The file to upload                    |
| `agentId` | string | Yes      | ID of the agent to attach the file to |

### Response (201)

```json theme={null}
{
  "success": true,
  "file": {
    "id": "clx1abc123",
    "name": "training-data.csv",
    "size": 24576,
    "type": "text/csv",
    "url": "/api/files/download?id=clx1abc123",
    "uploaded": "2026-03-25T10:00:00.000Z"
  }
}
```

### Upload response fields

| Field           | Type   | Description                                   |
| --------------- | ------ | --------------------------------------------- |
| `file.id`       | string | Unique file identifier                        |
| `file.name`     | string | Original filename                             |
| `file.size`     | number | File size in bytes                            |
| `file.type`     | string | MIME type of the file                         |
| `file.url`      | string | Download URL for the file                     |
| `file.uploaded` | string | ISO 8601 timestamp when the file was uploaded |

<Note>The GET endpoint returns `filename` while the POST response returns `name`. Both refer to the original filename of the uploaded file.</Note>

### Errors

| Code | Description                                                 |
| ---- | ----------------------------------------------------------- |
| 400  | No file provided or `agentId` required                      |
| 401  | Unauthorized                                                |
| 404  | Agent not found                                             |
| 413  | Storage limit exceeded — upgrade your plan for more storage |
| 500  | Upload failed                                               |

## Delete a file

```http theme={null}
DELETE /api/files
```

Delete a file by its ID.

### Request body

| Field    | Type   | Required | Description              |
| -------- | ------ | -------- | ------------------------ |
| `fileId` | string | Yes      | ID of the file to delete |

### Response

```json theme={null}
{
  "success": true,
  "fileId": "clx1abc123"
}
```

### Errors

| Code | Description       |
| ---- | ----------------- |
| 400  | `fileId` required |
| 401  | Unauthorized      |
| 404  | File not found    |
| 500  | Delete failed     |