## 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 <u>[File uploads](/using-the-api/file-uploads/)</u> for the full upload flow, supported purposes, and size limits. If you are uploading a meeting transcript, see <u>[Uploading meeting transcripts](/using-the-api/uploading-meeting-transcripts/)</u> for the follow-up meeting attachment flow.

**[Required scope](/using-the-api/scopes/):** `files:create`

**[Rate limit category](/using-the-api/rate-limits/):** Write

### Body Parameters

- `filename: string`

  Original filename.

- `mimeType: string`

  MIME type of the file. Must be allowed for the given purpose (if specified).

- `sizeBytes: number`

  Expected file size in bytes. Maximum 512 MB.

- `purpose: optional "meeting_transcript" or "knowledge_user" or "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

- `FileCreateResponse = 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

```http
curl https://api.lightfield.app/v1/files \
    -H 'Content-Type: application/json' \
    -H 'Lightfield-Version: 2026-03-01' \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
          "filename": "x",
          "mimeType": "mimeType",
          "sizeBytes": 1
        }'
```