Skip to content
Lightfield Lightfield
API Reference
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 for the full upload flow, supported purposes, and size limits. If you are uploading a meeting transcript, see Uploading meeting transcripts for the follow-up meeting attachment flow.

Required scope: files:create

Rate limit category: Write

ParametersExpand Collapse
filename: str

Original filename.

minLength1
maxLength255
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.

minimum1
maximum536870912
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.

One of the following:
"meeting_transcript"
"knowledge_user"
"knowledge_workspace"
ReturnsExpand Collapse
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.

minimum-9007199254740991
maximum9007199254740991
status: Literal["PENDING", "COMPLETED", "CANCELLED", "EXPIRED"]

Current upload status of the file.

One of the following:
"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.

Create a file upload session

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)
{
  "id": "id",
  "completedAt": "completedAt",
  "createdAt": "createdAt",
  "expiresAt": "expiresAt",
  "filename": "filename",
  "mimeType": "mimeType",
  "sizeBytes": -9007199254740991,
  "status": "PENDING",
  "uploadHeaders": {
    "foo": "string"
  },
  "uploadUrl": "uploadUrl"
}
Returns Examples
{
  "id": "id",
  "completedAt": "completedAt",
  "createdAt": "createdAt",
  "expiresAt": "expiresAt",
  "filename": "filename",
  "mimeType": "mimeType",
  "sizeBytes": -9007199254740991,
  "status": "PENDING",
  "uploadHeaders": {
    "foo": "string"
  },
  "uploadUrl": "uploadUrl"
}