# File
## Create a file upload session
`$ lightfield file create`
**post** `/v1/files`
Creates a new file upload session and returns an upload URL.
After uploading the file bytes to `uploadUrl`, call `POST /v1/files/{id}/complete` to finalize the upload. Optionally pass `purpose` to validate MIME type and size constraints at creation time. See [File uploads](/using-the-api/file-uploads/) for the full upload flow, supported purposes, and size limits. If you are uploading a meeting transcript, see [Uploading meeting transcripts](/using-the-api/uploading-meeting-transcripts/) for the follow-up meeting attachment flow.
**[Required scope](/using-the-api/scopes/):** `files:create`
**[Rate limit category](/using-the-api/rate-limits/):** Write
### Parameters
- `--filename: string`
Original filename.
- `--mime-type: string`
MIME type of the file. Must be allowed for the given purpose (if specified).
- `--size-bytes: number`
Expected file size in bytes. Maximum 512 MB.
- `--purpose: optional "meeting_transcript" or "knowledge_user" or "knowledge_workspace" or "email_attachment"`
Optional validation hint. When provided, the server enforces purpose-specific MIME type and file size constraints. Use `meeting_transcript` for files that will be attached to a meeting as its transcript. Use `knowledge_user` or `knowledge_workspace` to add the file to the authenticated user's or workspace's Knowledge, making it available to the AI assistant. Not persisted or returned in responses.
### Returns
- `file_create_response: object { id, completedAt, createdAt, 7 more }`
- `id: string`
Unique identifier for the file.
- `completedAt: string`
When the file upload was completed.
- `createdAt: string`
When the file upload session was created.
- `expiresAt: string`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: string`
Original filename.
- `mimeType: string`
MIME type of the file.
- `sizeBytes: number`
File size in bytes.
- `status: "PENDING" or "COMPLETED" or "CANCELLED" or "EXPIRED"`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
- `uploadHeaders: map[string]`
Headers to include in the upload request.
- `uploadUrl: string`
Upload URL. Upload the file bytes directly to this URL.
### Example
```cli
lightfield file create \
--api-key 'My API Key' \
--filename x \
--mime-type mimeType \
--size-bytes 1
```
#### Response
```json
{
"id": "id",
"completedAt": "completedAt",
"createdAt": "createdAt",
"expiresAt": "expiresAt",
"filename": "filename",
"mimeType": "mimeType",
"sizeBytes": -9007199254740991,
"status": "PENDING",
"uploadHeaders": {
"foo": "string"
},
"uploadUrl": "uploadUrl"
}
```
## Complete a file upload
`$ lightfield file complete`
**post** `/v1/files/{id}/complete`
Finalizes an upload after the file bytes have been uploaded.
If an optional `md5` hex digest is provided, the server validates the checksum before marking the file as completed.
**[Required scope](/using-the-api/scopes/):** `files:create`
**[Rate limit category](/using-the-api/rate-limits/):** Write
### Parameters
- `--id: string`
Unique identifier of the file to complete.
- `--md5: optional string`
Optional MD5 hex digest of the uploaded file for checksum verification.
### Returns
- `file_complete_response: object { id, completedAt, createdAt, 5 more }`
- `id: string`
Unique identifier for the file.
- `completedAt: string`
When the file upload was completed.
- `createdAt: string`
When the file upload session was created.
- `expiresAt: string`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: string`
Original filename.
- `mimeType: string`
MIME type of the file.
- `sizeBytes: number`
File size in bytes.
- `status: "PENDING" or "COMPLETED" or "CANCELLED" or "EXPIRED"`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### Example
```cli
lightfield file complete \
--api-key 'My API Key' \
--id id
```
#### Response
```json
{
"id": "id",
"completedAt": "completedAt",
"createdAt": "createdAt",
"expiresAt": "expiresAt",
"filename": "filename",
"mimeType": "mimeType",
"sizeBytes": -9007199254740991,
"status": "PENDING"
}
```
## Retrieve a file
`$ lightfield file retrieve`
**get** `/v1/files/{id}`
Retrieves a single file by its ID.
This works for any file id you already hold, including ones returned in a CRM record's `$files` relationship — not only files created through `POST /v1/files`. See [File uploads](/using-the-api/file-uploads/) for which document classes are retrievable by id versus enumerable through `GET /v1/files`.
**[Required scope](/using-the-api/scopes/):** `files:read`
**[Rate limit category](/using-the-api/rate-limits/):** Read
### Parameters
- `--id: string`
Unique identifier of the file to retrieve.
### Returns
- `file_retrieve_response: object { id, completedAt, createdAt, 5 more }`
- `id: string`
Unique identifier for the file.
- `completedAt: string`
When the file upload was completed.
- `createdAt: string`
When the file upload session was created.
- `expiresAt: string`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: string`
Original filename.
- `mimeType: string`
MIME type of the file.
- `sizeBytes: number`
File size in bytes.
- `status: "PENDING" or "COMPLETED" or "CANCELLED" or "EXPIRED"`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### Example
```cli
lightfield file retrieve \
--api-key 'My API Key' \
--id id
```
#### Response
```json
{
"id": "id",
"completedAt": "completedAt",
"createdAt": "createdAt",
"expiresAt": "expiresAt",
"filename": "filename",
"mimeType": "mimeType",
"sizeBytes": -9007199254740991,
"status": "PENDING"
}
```
## List files
`$ lightfield file list`
**get** `/v1/files`
Returns a paginated list of files in your workspace. Results are sorted by when the record was created in Lightfield (`createdAt`), newest first. Use `offset` and `limit` to paginate through results. See [List endpoints](/using-the-api/list-endpoints/) for more information about pagination.
Omits files uploaded through the app and synced chat attachments — both are still retrievable by id. See [File uploads](/using-the-api/file-uploads/) for which document classes are listable versus retrievable-only.
**[Required scope](/using-the-api/scopes/):** `files:read`
**[Rate limit category](/using-the-api/rate-limits/):** Search
### Parameters
- `--limit: optional number`
Maximum number of records to return. Defaults to 25, maximum 25.
- `--offset: optional number`
Number of records to skip for pagination. Defaults to 0.
### Returns
- `file_list_response: object { data, object, totalCount }`
- `data: array of object { id, completedAt, createdAt, 5 more }`
Array of file objects for the current page.
- `id: string`
Unique identifier for the file.
- `completedAt: string`
When the file upload was completed.
- `createdAt: string`
When the file upload session was created.
- `expiresAt: string`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: string`
Original filename.
- `mimeType: string`
MIME type of the file.
- `sizeBytes: number`
File size in bytes.
- `status: "PENDING" or "COMPLETED" or "CANCELLED" or "EXPIRED"`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
- `object: string`
The object type, always `"list"`.
- `totalCount: number`
Total number of matching files.
### Example
```cli
lightfield file list \
--api-key 'My API Key'
```
#### Response
```json
{
"data": [
{
"id": "id",
"completedAt": "completedAt",
"createdAt": "createdAt",
"expiresAt": "expiresAt",
"filename": "filename",
"mimeType": "mimeType",
"sizeBytes": -9007199254740991,
"status": "PENDING"
}
],
"object": "object",
"totalCount": 0
}
```
## Get a file download URL
`$ lightfield file url`
**get** `/v1/files/{id}/url`
Returns a temporary download URL for the file. Only available for files in `COMPLETED` status. Works for any retrievable file id, including files uploaded through the app.
**[Required scope](/using-the-api/scopes/):** `files:read`
**[Rate limit category](/using-the-api/rate-limits/):** Read
### Parameters
- `--id: string`
Unique identifier of the file to download.
### Returns
- `file_url_response: object { expiresAt, url }`
- `expiresAt: string`
When the download URL expires.
- `url: string`
Temporary download URL for the file.
### Example
```cli
lightfield file url \
--api-key 'My API Key' \
--id id
```
#### Response
```json
{
"expiresAt": "expiresAt",
"url": "url"
}
```
## Cancel a file upload
`$ lightfield file cancel`
**post** `/v1/files/{id}/cancel`
Cancels a pending upload by transitioning the file to `CANCELLED`. Only files in `PENDING` status can be cancelled. **[Required scope](/using-the-api/scopes/):** `files:create`
**[Rate limit category](/using-the-api/rate-limits/):** Write
### Parameters
- `--id: string`
Unique identifier of the file to cancel.
- `--body: optional object { }`
### Returns
- `file_cancel_response: object { id, completedAt, createdAt, 5 more }`
- `id: string`
Unique identifier for the file.
- `completedAt: string`
When the file upload was completed.
- `createdAt: string`
When the file upload session was created.
- `expiresAt: string`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: string`
Original filename.
- `mimeType: string`
MIME type of the file.
- `sizeBytes: number`
File size in bytes.
- `status: "PENDING" or "COMPLETED" or "CANCELLED" or "EXPIRED"`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### Example
```cli
lightfield file cancel \
--api-key 'My API Key' \
--id id
```
#### Response
```json
{
"id": "id",
"completedAt": "completedAt",
"createdAt": "createdAt",
"expiresAt": "expiresAt",
"filename": "filename",
"mimeType": "mimeType",
"sizeBytes": -9007199254740991,
"status": "PENDING"
}
```
## Domain Types
### File Cancel Response
- `file_cancel_response: object { id, completedAt, createdAt, 5 more }`
- `id: string`
Unique identifier for the file.
- `completedAt: string`
When the file upload was completed.
- `createdAt: string`
When the file upload session was created.
- `expiresAt: string`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: string`
Original filename.
- `mimeType: string`
MIME type of the file.
- `sizeBytes: number`
File size in bytes.
- `status: "PENDING" or "COMPLETED" or "CANCELLED" or "EXPIRED"`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### File Complete Response
- `file_complete_response: object { id, completedAt, createdAt, 5 more }`
- `id: string`
Unique identifier for the file.
- `completedAt: string`
When the file upload was completed.
- `createdAt: string`
When the file upload session was created.
- `expiresAt: string`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: string`
Original filename.
- `mimeType: string`
MIME type of the file.
- `sizeBytes: number`
File size in bytes.
- `status: "PENDING" or "COMPLETED" or "CANCELLED" or "EXPIRED"`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### File Create Response
- `file_create_response: object { id, completedAt, createdAt, 7 more }`
- `id: string`
Unique identifier for the file.
- `completedAt: string`
When the file upload was completed.
- `createdAt: string`
When the file upload session was created.
- `expiresAt: string`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: string`
Original filename.
- `mimeType: string`
MIME type of the file.
- `sizeBytes: number`
File size in bytes.
- `status: "PENDING" or "COMPLETED" or "CANCELLED" or "EXPIRED"`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
- `uploadHeaders: map[string]`
Headers to include in the upload request.
- `uploadUrl: string`
Upload URL. Upload the file bytes directly to this URL.
### File List Response
- `file_list_response: object { data, object, totalCount }`
- `data: array of object { id, completedAt, createdAt, 5 more }`
Array of file objects for the current page.
- `id: string`
Unique identifier for the file.
- `completedAt: string`
When the file upload was completed.
- `createdAt: string`
When the file upload session was created.
- `expiresAt: string`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: string`
Original filename.
- `mimeType: string`
MIME type of the file.
- `sizeBytes: number`
File size in bytes.
- `status: "PENDING" or "COMPLETED" or "CANCELLED" or "EXPIRED"`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
- `object: string`
The object type, always `"list"`.
- `totalCount: number`
Total number of matching files.
### File Retrieve Response
- `file_retrieve_response: object { id, completedAt, createdAt, 5 more }`
- `id: string`
Unique identifier for the file.
- `completedAt: string`
When the file upload was completed.
- `createdAt: string`
When the file upload session was created.
- `expiresAt: string`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: string`
Original filename.
- `mimeType: string`
MIME type of the file.
- `sizeBytes: number`
File size in bytes.
- `status: "PENDING" or "COMPLETED" or "CANCELLED" or "EXPIRED"`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### File URL Response
- `file_url_response: object { expiresAt, url }`
- `expiresAt: string`
When the download URL expires.
- `url: string`
Temporary download URL for the file.