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 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: 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 2 more

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 stage an upload for the authenticated user or workspace. Completing the upload does not add it to Knowledge; promote it separately through the agent or Knowledge workflow. Use contact_avatar for an image that will be set as a contact photo through the contact $profilePhotoUrl field. Not returned in responses.

ReturnsExpand Collapse

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.

Create a file upload session

lightfield file create \
  --api-key 'My API Key' \
  --filename x \
  --mime-type mimeType \
  --size-bytes 1

{
  "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"
}