# File
## Create a file upload session
`file.create(FileCreateParams**kwargs) -> FileCreateResponse`
**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: str`
Original filename.
- `mime_type: str`
MIME type of the file. Must be allowed for the given purpose (if specified).
- `size_bytes: int`
Expected file size in bytes. Maximum 512 MB.
- `purpose: Optional[Literal["meeting_transcript", "knowledge_user", "knowledge_workspace"]]`
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.
- `"meeting_transcript"`
- `"knowledge_user"`
- `"knowledge_workspace"`
### Returns
- `class FileCreateResponse: …`
- `id: str`
Unique identifier for the file.
- `completed_at: Optional[str]`
When the file upload was completed.
- `created_at: str`
When the file upload session was created.
- `expires_at: Optional[str]`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: str`
Original filename.
- `mime_type: str`
MIME type of the file.
- `size_bytes: int`
File size in bytes.
- `status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
- `upload_headers: Dict[str, str]`
Headers to include in the upload request.
- `upload_url: str`
Upload URL. Upload the file bytes directly to this URL.
### Example
```python
from lightfield import Lightfield
client = Lightfield(
api_key="My API Key",
)
file_create_response = client.file.create(
filename="x",
mime_type="mimeType",
size_bytes=1,
)
print(file_create_response.id)
```
#### 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
`file.complete(strid, FileCompleteParams**kwargs) -> FileCompleteResponse`
**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: str`
Unique identifier of the file to complete.
- `md5: Optional[str]`
Optional MD5 hex digest of the uploaded file for checksum verification.
### Returns
- `class FileCompleteResponse: …`
- `id: str`
Unique identifier for the file.
- `completed_at: Optional[str]`
When the file upload was completed.
- `created_at: str`
When the file upload session was created.
- `expires_at: Optional[str]`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: str`
Original filename.
- `mime_type: str`
MIME type of the file.
- `size_bytes: int`
File size in bytes.
- `status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### Example
```python
from lightfield import Lightfield
client = Lightfield(
api_key="My API Key",
)
file_complete_response = client.file.complete(
id="id",
)
print(file_complete_response.id)
```
#### Response
```json
{
"id": "id",
"completedAt": "completedAt",
"createdAt": "createdAt",
"expiresAt": "expiresAt",
"filename": "filename",
"mimeType": "mimeType",
"sizeBytes": -9007199254740991,
"status": "PENDING"
}
```
## Retrieve a file
`file.retrieve(strid) -> FileRetrieveResponse`
**get** `/v1/files/{id}`
Retrieves a single file by its ID.
**[Required scope](/using-the-api/scopes/):** `files:read`
**[Rate limit category](/using-the-api/rate-limits/):** Read
### Parameters
- `id: str`
Unique identifier of the file to retrieve.
### Returns
- `class FileRetrieveResponse: …`
- `id: str`
Unique identifier for the file.
- `completed_at: Optional[str]`
When the file upload was completed.
- `created_at: str`
When the file upload session was created.
- `expires_at: Optional[str]`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: str`
Original filename.
- `mime_type: str`
MIME type of the file.
- `size_bytes: int`
File size in bytes.
- `status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### Example
```python
from lightfield import Lightfield
client = Lightfield(
api_key="My API Key",
)
file_retrieve_response = client.file.retrieve(
"id",
)
print(file_retrieve_response.id)
```
#### Response
```json
{
"id": "id",
"completedAt": "completedAt",
"createdAt": "createdAt",
"expiresAt": "expiresAt",
"filename": "filename",
"mimeType": "mimeType",
"sizeBytes": -9007199254740991,
"status": "PENDING"
}
```
## List files
`file.list(FileListParams**kwargs) -> FileListResponse`
**get** `/v1/files`
Returns a paginated list of files in your workspace. Use `offset` and `limit` to paginate through results. See [List endpoints](/using-the-api/list-endpoints/) for more information about pagination.
**[Required scope](/using-the-api/scopes/):** `files:read`
**[Rate limit category](/using-the-api/rate-limits/):** Search
### Parameters
- `limit: Optional[int]`
Maximum number of records to return. Defaults to 25, maximum 25.
- `offset: Optional[int]`
Number of records to skip for pagination. Defaults to 0.
### Returns
- `class FileListResponse: …`
- `data: List[Data]`
Array of file objects for the current page.
- `id: str`
Unique identifier for the file.
- `completed_at: Optional[str]`
When the file upload was completed.
- `created_at: str`
When the file upload session was created.
- `expires_at: Optional[str]`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: str`
Original filename.
- `mime_type: str`
MIME type of the file.
- `size_bytes: int`
File size in bytes.
- `status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
- `object: str`
The object type, always `"list"`.
- `total_count: int`
Total number of matching files.
### Example
```python
from lightfield import Lightfield
client = Lightfield(
api_key="My API Key",
)
file_list_response = client.file.list()
print(file_list_response.data)
```
#### 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
`file.url(strid) -> FileURLResponse`
**get** `/v1/files/{id}/url`
Returns a temporary download URL for the file. Only available for files in `COMPLETED` status.
**[Required scope](/using-the-api/scopes/):** `files:read`
**[Rate limit category](/using-the-api/rate-limits/):** Read
### Parameters
- `id: str`
Unique identifier of the file to download.
### Returns
- `class FileURLResponse: …`
- `expires_at: str`
When the download URL expires.
- `url: str`
Temporary download URL for the file.
### Example
```python
from lightfield import Lightfield
client = Lightfield(
api_key="My API Key",
)
file_url_response = client.file.url(
"id",
)
print(file_url_response.expires_at)
```
#### Response
```json
{
"expiresAt": "expiresAt",
"url": "url"
}
```
## Cancel a file upload
`file.cancel(strid, FileCancelParams**kwargs) -> FileCancelResponse`
**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: str`
Unique identifier of the file to cancel.
- `body: Optional[Body]`
### Returns
- `class FileCancelResponse: …`
- `id: str`
Unique identifier for the file.
- `completed_at: Optional[str]`
When the file upload was completed.
- `created_at: str`
When the file upload session was created.
- `expires_at: Optional[str]`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: str`
Original filename.
- `mime_type: str`
MIME type of the file.
- `size_bytes: int`
File size in bytes.
- `status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### Example
```python
from lightfield import Lightfield
client = Lightfield(
api_key="My API Key",
)
file_cancel_response = client.file.cancel(
id="id",
)
print(file_cancel_response.id)
```
#### Response
```json
{
"id": "id",
"completedAt": "completedAt",
"createdAt": "createdAt",
"expiresAt": "expiresAt",
"filename": "filename",
"mimeType": "mimeType",
"sizeBytes": -9007199254740991,
"status": "PENDING"
}
```
## Domain Types
### File Cancel Response
- `class FileCancelResponse: …`
- `id: str`
Unique identifier for the file.
- `completed_at: Optional[str]`
When the file upload was completed.
- `created_at: str`
When the file upload session was created.
- `expires_at: Optional[str]`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: str`
Original filename.
- `mime_type: str`
MIME type of the file.
- `size_bytes: int`
File size in bytes.
- `status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### File Complete Response
- `class FileCompleteResponse: …`
- `id: str`
Unique identifier for the file.
- `completed_at: Optional[str]`
When the file upload was completed.
- `created_at: str`
When the file upload session was created.
- `expires_at: Optional[str]`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: str`
Original filename.
- `mime_type: str`
MIME type of the file.
- `size_bytes: int`
File size in bytes.
- `status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### File Create Response
- `class FileCreateResponse: …`
- `id: str`
Unique identifier for the file.
- `completed_at: Optional[str]`
When the file upload was completed.
- `created_at: str`
When the file upload session was created.
- `expires_at: Optional[str]`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: str`
Original filename.
- `mime_type: str`
MIME type of the file.
- `size_bytes: int`
File size in bytes.
- `status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
- `upload_headers: Dict[str, str]`
Headers to include in the upload request.
- `upload_url: str`
Upload URL. Upload the file bytes directly to this URL.
### File List Response
- `class FileListResponse: …`
- `data: List[Data]`
Array of file objects for the current page.
- `id: str`
Unique identifier for the file.
- `completed_at: Optional[str]`
When the file upload was completed.
- `created_at: str`
When the file upload session was created.
- `expires_at: Optional[str]`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: str`
Original filename.
- `mime_type: str`
MIME type of the file.
- `size_bytes: int`
File size in bytes.
- `status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
- `object: str`
The object type, always `"list"`.
- `total_count: int`
Total number of matching files.
### File Retrieve Response
- `class FileRetrieveResponse: …`
- `id: str`
Unique identifier for the file.
- `completed_at: Optional[str]`
When the file upload was completed.
- `created_at: str`
When the file upload session was created.
- `expires_at: Optional[str]`
When the upload session expires. Null once completed, cancelled, or expired.
- `filename: str`
Original filename.
- `mime_type: str`
MIME type of the file.
- `size_bytes: int`
File size in bytes.
- `status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]`
Current upload status of the file.
- `"PENDING"`
- `"COMPLETED"`
- `"CANCELLED"`
- `"EXPIRED"`
### File URL Response
- `class FileURLResponse: …`
- `expires_at: str`
When the download URL expires.
- `url: str`
Temporary download URL for the file.