# File

## Create

`client.file.create(FileCreateParamsbody, RequestOptionsoptions?): 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 <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

### Parameters

- `body: FileCreateParams`

  - `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?: "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

- `FileCreateResponse`

  - `id: string`

    Unique identifier for the file.

  - `completedAt: string | null`

    When the file upload was completed.

  - `createdAt: string`

    When the file upload session was created.

  - `expiresAt: string | null`

    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" | "COMPLETED" | "CANCELLED" | "EXPIRED"`

    Current upload status of the file.

    - `"PENDING"`

    - `"COMPLETED"`

    - `"CANCELLED"`

    - `"EXPIRED"`

  - `uploadHeaders: Record<string, string>`

    Headers to include in the upload request.

  - `uploadUrl: string`

    Upload URL. Upload the file bytes directly to this URL.

### Example

```typescript
import Lightfield from 'lightfield';

const client = new Lightfield({
  apiKey: 'My API Key',
});

const fileCreateResponse = await client.file.create({
  filename: 'x',
  mimeType: 'mimeType',
  sizeBytes: 1,
});

console.log(fileCreateResponse.id);
```

## Complete

`client.file.complete(stringid, FileCompleteParamsbody, RequestOptionsoptions?): 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: string`

  Unique identifier of the file to complete.

- `body: FileCompleteParams`

  - `md5?: string`

    Optional MD5 hex digest of the uploaded file for checksum verification.

### Returns

- `FileCompleteResponse`

  - `id: string`

    Unique identifier for the file.

  - `completedAt: string | null`

    When the file upload was completed.

  - `createdAt: string`

    When the file upload session was created.

  - `expiresAt: string | null`

    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" | "COMPLETED" | "CANCELLED" | "EXPIRED"`

    Current upload status of the file.

    - `"PENDING"`

    - `"COMPLETED"`

    - `"CANCELLED"`

    - `"EXPIRED"`

### Example

```typescript
import Lightfield from 'lightfield';

const client = new Lightfield({
  apiKey: 'My API Key',
});

const fileCompleteResponse = await client.file.complete('id');

console.log(fileCompleteResponse.id);
```

## Retrieve

`client.file.retrieve(stringid, RequestOptionsoptions?): 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: string`

  Unique identifier of the file to retrieve.

### Returns

- `FileRetrieveResponse`

  - `id: string`

    Unique identifier for the file.

  - `completedAt: string | null`

    When the file upload was completed.

  - `createdAt: string`

    When the file upload session was created.

  - `expiresAt: string | null`

    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" | "COMPLETED" | "CANCELLED" | "EXPIRED"`

    Current upload status of the file.

    - `"PENDING"`

    - `"COMPLETED"`

    - `"CANCELLED"`

    - `"EXPIRED"`

### Example

```typescript
import Lightfield from 'lightfield';

const client = new Lightfield({
  apiKey: 'My API Key',
});

const fileRetrieveResponse = await client.file.retrieve('id');

console.log(fileRetrieveResponse.id);
```

## List

`client.file.list(FileListParamsquery?, RequestOptionsoptions?): FileListResponse`

**get** `/v1/files`

Returns a paginated list of files in your workspace. Use `offset` and `limit` to paginate through results. See <u>[List endpoints](/using-the-api/list-endpoints/)</u> for more information about pagination.

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

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

### Parameters

- `query: FileListParams`

  - `limit?: number`

    Maximum number of records to return. Defaults to 25, maximum 25.

  - `offset?: number`

    Number of records to skip for pagination. Defaults to 0.

### Returns

- `FileListResponse`

  - `data: Array<Data>`

    Array of file objects for the current page.

    - `id: string`

      Unique identifier for the file.

    - `completedAt: string | null`

      When the file upload was completed.

    - `createdAt: string`

      When the file upload session was created.

    - `expiresAt: string | null`

      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" | "COMPLETED" | "CANCELLED" | "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

```typescript
import Lightfield from 'lightfield';

const client = new Lightfield({
  apiKey: 'My API Key',
});

const fileListResponse = await client.file.list();

console.log(fileListResponse.data);
```

## URL

`client.file.url(stringid, RequestOptionsoptions?): 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: string`

  Unique identifier of the file to download.

### Returns

- `FileURLResponse`

  - `expiresAt: string`

    When the download URL expires.

  - `url: string`

    Temporary download URL for the file.

### Example

```typescript
import Lightfield from 'lightfield';

const client = new Lightfield({
  apiKey: 'My API Key',
});

const fileURLResponse = await client.file.url('id');

console.log(fileURLResponse.expiresAt);
```

## Cancel

`client.file.cancel(stringid, FileCancelParamsparams?, RequestOptionsoptions?): 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: string`

  Unique identifier of the file to cancel.

- `params: FileCancelParams`

  - `body?: Body`

### Returns

- `FileCancelResponse`

  - `id: string`

    Unique identifier for the file.

  - `completedAt: string | null`

    When the file upload was completed.

  - `createdAt: string`

    When the file upload session was created.

  - `expiresAt: string | null`

    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" | "COMPLETED" | "CANCELLED" | "EXPIRED"`

    Current upload status of the file.

    - `"PENDING"`

    - `"COMPLETED"`

    - `"CANCELLED"`

    - `"EXPIRED"`

### Example

```typescript
import Lightfield from 'lightfield';

const client = new Lightfield({
  apiKey: 'My API Key',
});

const fileCancelResponse = await client.file.cancel('id');

console.log(fileCancelResponse.id);
```

## Domain Types

### File Cancel Response

- `FileCancelResponse`

  - `id: string`

    Unique identifier for the file.

  - `completedAt: string | null`

    When the file upload was completed.

  - `createdAt: string`

    When the file upload session was created.

  - `expiresAt: string | null`

    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" | "COMPLETED" | "CANCELLED" | "EXPIRED"`

    Current upload status of the file.

    - `"PENDING"`

    - `"COMPLETED"`

    - `"CANCELLED"`

    - `"EXPIRED"`

### File Complete Response

- `FileCompleteResponse`

  - `id: string`

    Unique identifier for the file.

  - `completedAt: string | null`

    When the file upload was completed.

  - `createdAt: string`

    When the file upload session was created.

  - `expiresAt: string | null`

    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" | "COMPLETED" | "CANCELLED" | "EXPIRED"`

    Current upload status of the file.

    - `"PENDING"`

    - `"COMPLETED"`

    - `"CANCELLED"`

    - `"EXPIRED"`

### File Create Response

- `FileCreateResponse`

  - `id: string`

    Unique identifier for the file.

  - `completedAt: string | null`

    When the file upload was completed.

  - `createdAt: string`

    When the file upload session was created.

  - `expiresAt: string | null`

    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" | "COMPLETED" | "CANCELLED" | "EXPIRED"`

    Current upload status of the file.

    - `"PENDING"`

    - `"COMPLETED"`

    - `"CANCELLED"`

    - `"EXPIRED"`

  - `uploadHeaders: Record<string, string>`

    Headers to include in the upload request.

  - `uploadUrl: string`

    Upload URL. Upload the file bytes directly to this URL.

### File List Response

- `FileListResponse`

  - `data: Array<Data>`

    Array of file objects for the current page.

    - `id: string`

      Unique identifier for the file.

    - `completedAt: string | null`

      When the file upload was completed.

    - `createdAt: string`

      When the file upload session was created.

    - `expiresAt: string | null`

      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" | "COMPLETED" | "CANCELLED" | "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

- `FileRetrieveResponse`

  - `id: string`

    Unique identifier for the file.

  - `completedAt: string | null`

    When the file upload was completed.

  - `createdAt: string`

    When the file upload session was created.

  - `expiresAt: string | null`

    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" | "COMPLETED" | "CANCELLED" | "EXPIRED"`

    Current upload status of the file.

    - `"PENDING"`

    - `"COMPLETED"`

    - `"CANCELLED"`

    - `"EXPIRED"`

### File URL Response

- `FileURLResponse`

  - `expiresAt: string`

    When the download URL expires.

  - `url: string`

    Temporary download URL for the file.