> ## Documentation Index > Fetch the complete documentation index at: https://developers.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # TypeScript SDK reference > Every public class, method, and type in @lighton-ai/sdk 1.0.0. Generated from [`@lighton-ai/sdk`](https://github.com/lightonai/lighton-typescript-sdk) **1.0.0**. Install it and see runnable examples in the [quick start](/sdks/typescript/quickstart). ## Client ### LightOn ```typescript theme={null} new LightOn(apiKey?: string, config?: LightOnConfiguration) ``` | Name | Type | Description | | --------- | ---------------------- | --------------------------------------------------- | | `apiKey?` | `string` | Falls back to `LIGHTON_API_KEY` in the environment. | | `config?` | `LightOnConfiguration` | Optional client knobs, see `LightOnConfiguration`. | | Error | When | | ------- | ------------------------------------------------------ | | `Error` | If no API key is given and none is in the environment. | #### `LightOn.ask()` ```typescript theme={null} ask(query: string, options?: AskOptions & { stream?: false; }): Promise ask(query: string, options: AskOptions & { stream: true; }): AsyncGenerator ``` **Arguments** | Name | Type | Description | | --------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | `string` | | | `options?` | `AskOptions & { stream?: false; }` | | | `options.maxResults?` | `number` | Chunks to retrieve for context (1 to 50; server default 10). | | `options.relevanceScoring?` | `RelevanceScoring` | Defaults to `scoringAndFiltering` server-side. | | `options.model?` | `string` | LLM for answer generation; platform default if omitted. | | `options.schema?` | `SchemaInput` | Constrain the answer to structured output: a Zod schema or a plain JSON Schema object (the same inputs `extract` takes, sent as the API's `response_format`; it must describe an object). The answer then comes back as JSON *text* in `.answer`. The SDK does not parse it back for you, so that a schema mismatch surfaces where you can see it. | | `options.workspaces?` | `readonly IdRef[]` | Restrict to these workspaces. Excludes `files`. | | `options.tags?` | `readonly TagRef[]` | Restrict to documents carrying any of these tags (OR-matched). Accepts `Tag` objects, ids, or names; names are resolved via the tags endpoint and must exist. Excludes `files`. | | `options.files?` | `readonly IdRef[]` | Restrict to these files. Excludes `workspaces` and `tags`. | | `options.contentType?` | `readonly PathRef[]` | Restrict to these content-type paths (OR-matched, exact-or-subtree, so `legal` also matches `legal:contract`). Wildcards: `legal:contract*`, `*nda*`. | | `options.attribute?` | `readonly string[]` | Restrict by attribute value, e.g. `["fiscal_year:2024\|2025", "status:active"]`. Entries are ANDed, `\|` ORs within one entry. Also `name` (has any value), `name:>value`, `name:prefix*`, `name:*text*`. | | `options.signal?` | `AbortSignal` | Caller cancellation. | | `options.stream?` | `false` | | **Returns** | Type | Description | | ------------------------------------------------------------------- | ----------- | | `Promise \| AsyncGenerator` | | #### `LightOn.close()` ```typescript theme={null} close(): void ``` Abort every in-flight request. The client is not reusable afterwards. #### `LightOn.extract()` ```typescript theme={null} extract(schema: SchemaInput, options: ExtractOptions & { mode?: "sync"; }): Promise extract(schema: SchemaInput, options: ExtractAsyncOptions): Promise ``` **Arguments** | Name | Type | Description | | ------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `schema` | `SchemaInput` | | | `options` | `ExtractOptions & { mode?: "sync"; }` | | | `options.file?` | `FileSource` | A local path, `File`, or `{filename, blob}` to upload. | | `options.url?` | `string` | A publicly accessible URL for the server to fetch. | | `options.ingested?` | `IdRef` | An already-ingested file (a `File` or its id). No re-upload: the server reads the document it already has, which is the cheapest of the three sources. | | `options.options?` | `Record` | Free-form request options, merged into the body. | | `options.signal?` | `AbortSignal` | Caller cancellation. | | `options.mode?` | `"sync"` | | **Returns** | Type | Description | | ---------------------------------------------------- | ----------- | | `Promise \| Promise` | | #### `LightOn.parse()` ```typescript theme={null} parse(options: ParseOptions & { mode?: "sync"; }): Promise parse(options: ParseAsyncOptions): Promise ``` **Arguments** | Name | Type | Description | | ----------------- | ----------------------------------- | ---------------------------------------------------------------------- | | `options` | `ParseOptions & { mode?: "sync"; }` | | | `options.file?` | `FileSource` | A local path, `File`, or `{filename, blob}` to upload. Excludes `url`. | | `options.url?` | `string` | A publicly accessible URL for the server to fetch. Excludes `file`. | | `options.signal?` | `AbortSignal` | Caller cancellation. | | `options.mode?` | `"sync"` | | **Returns** | Type | Description | | --------------------------------------------- | ----------- | | `Promise \| Promise` | | #### `LightOn.search()` ```typescript theme={null} search(query: string, options?: SearchOptions): Promise ``` **Arguments** | Name | Type | Description | | --------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | `string` | | | `options?` | `SearchOptions` | | | `options.maxResults?` | `number` | Chunks to return after reranking (1 to 100; server default 10). | | `options.mode?` | `SearchMode` | `text` (hybrid keyword + vector) or `vision` (page image). | | `options.relevanceScoring?` | `RelevanceScoring` | Defaults to `scoringAndFiltering` server-side. | | `options.includeImage?` | `boolean` | Attach a base64 page image to each result. | | `options.includeBboxes?` | `boolean` | Attach chunk bounding boxes (PDF text-mode only). | | `options.workspaces?` | `readonly IdRef[]` | Restrict to these workspaces. Excludes `files`. | | `options.tags?` | `readonly TagRef[]` | Restrict to documents carrying any of these tags (OR-matched). Accepts `Tag` objects, ids, or names; names are resolved via the tags endpoint and must exist. Excludes `files`. | | `options.files?` | `readonly IdRef[]` | Restrict to these files. Excludes `workspaces` and `tags`. | | `options.contentType?` | `readonly PathRef[]` | Restrict to these content-type paths (OR-matched, exact-or-subtree, so `legal` also matches `legal:contract`). Wildcards: `legal:contract*`, `*nda*`. | | `options.attribute?` | `readonly string[]` | Restrict by attribute value, e.g. `["fiscal_year:2024\|2025", "status:active"]`. Entries are ANDed, `\|` ORs within one entry. Also `name` (has any value), `name:>value`, `name:prefix*`, `name:*text*`. | | `options.signal?` | `AbortSignal` | Caller cancellation. | **Returns** | Type | Description | | ------------------------- | ----------- | | `Promise` | | ### LightOnConfiguration Non-essential client knobs. `apiKey` stays a direct `LightOn()` argument, so a config object can be shared or logged without carrying a secret. | Field | Type | Description | | ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `baseUrl?` | `string` | API root, host only. The SDK appends `/api/v3/...` itself. | | `timeout?` | `number` | Whole-request timeout in milliseconds. Default 120\_000. ponytail: one timeout, where the Python SDK splits connect (5s) from read (120s). `fetch` cannot express the split, and `AbortSignal.timeout` covers the case that actually hurts. Move to a custom dispatcher if a connect-only deadline is needed. | | `retries?` | `number` | Connection-level retries, with exponential backoff. Does not cover HTTP errors. | | `fetch?` | `typeof globalThis.fetch` | The `fetch` to send through. Defaults to the global one. This is the seam tests use to answer requests without a network, the way the Python SDK injects an `httpx.MockTransport`. It is also where a proxy dispatcher goes. | | `maxRequestsPerMinute?` | `number \| null` | Pace ALL requests to stay under this per-minute cap (a min-interval gate in `request`). Defaults to 1000, the API's limit for most endpoints; override if your account differs. Set null to disable pacing entirely. | | `rateLimitRetries?` | `number` | On HTTP 429, retry this many times, waiting the `Retry-After` header when present (else exponential backoff). 0 disables. | ### DEFAULT\_BASE\_URL ```typescript theme={null} const DEFAULT_BASE_URL: "https://api.lighton.ai" ``` Client configuration. ### VERSION ```typescript theme={null} const VERSION: string ``` ## Workspaces & files ### Workspace ```typescript theme={null} new Workspace(init?: WorkspaceInit) ``` | Name | Type | Description | | ------- | --------------- | ----------- | | `init?` | `WorkspaceInit` | | | Field | Type | Description | | ----------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `number \| null` | Server-assigned id; null until created or retrieved. | | `name` | `string` | | | `description` | `string` | | | `workspaceType?` | `string \| null` | Workspace type (read-only). | | `documentUploadMethod?` | `string \| null` | How documents are uploaded to this workspace (read-only). | | `filesCount?` | `number \| null` | | | `usedStorage?` | `number \| null` | Bytes of storage used (read-only). | | `createdAt?` | `string \| null` | | | `updatedAt?` | `string \| null` | | | `userRole?` | `Role \| null` | Your role on this workspace (read-only). Null when you hold none. | | `taxonomy?` | `WorkspaceTaxonomy \| null` | Classification coverage and per-root document counts (read-only). Only `list()` returns it. The detail endpoint omits the key entirely, so `get()` and `refresh()` neither populate it nor clear an already-loaded value. Re-list for fresh coverage numbers. | | `sync?` | `WorkspaceSync \| null` | External datasource this workspace imports from (read-only); null when documents are uploaded directly. | #### `Workspace.get()` ```typescript theme={null} static get(client: Transport, id: number | string): Promise ``` Fetch a single workspace by id. **Arguments** | Name | Type | Description | | -------- | ------------------ | -------------------------------------------------- | | `client` | `Transport` | The client to request with and bind to the result. | | `id` | `number \| string` | The workspace id to retrieve. | **Returns** | Type | Description | | -------------------- | --------------------------------- | | `Promise` | The workspace, bound to `client`. | #### `Workspace.list()` ```typescript theme={null} static list(client: Transport, options?: WorkspaceListOptions): Promise ``` List every workspace, following pagination to the end. Only a listing returns `taxonomy` and the other listing-only extras. **Arguments** | Name | Type | Description | | ------------------ | ---------------------- | ----------------------------------------------------------------------------- | | `client` | `Transport` | The client to request with and bind to each result. | | `options?` | `WorkspaceListOptions` | Endpoint filters under `filters`, by their API names. | | `options.filters?` | `WorkspaceFilters` | Endpoint filters under their API names, e.g. `name`, `user_role`, `ordering`. | **Returns** | Type | Description | | ---------------------- | -------------------------------------------- | | `Promise` | Every matching workspace, bound to `client`. | #### `Workspace.create()` ```typescript theme={null} create(client: Transport): Promise ``` Create this workspace and bind the client for later lifecycle calls. **Arguments** | Name | Type | Description | | -------- | ----------- | ----------------------------------------------------------- | | `client` | `Transport` | The client to create the workspace with and bind to `this`. | **Returns** | Type | Description | | --------------------------------- | ----------------------------------------------------------------- | | `Promise` | `this`, updated with the server-assigned id and read-only fields. | #### `Workspace.delete()` ```typescript theme={null} delete(): Promise ``` Delete this resource and clear its local id. **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | #### `Workspace.ingest()` ```typescript theme={null} ingest(file: File, options?: IngestOptions): Promise ``` Upload a File into this workspace. Uploading *is* the ingestion. Non-blocking by default: the returned File is `pending`, poll it with `refresh()` or `wait()`. Pass `wait: true` to block until ingestion is terminal. **Arguments** | Name | Type | Description | | -------------------- | --------------- | --------------------------------------------------------------- | | `file` | `File` | The File to upload; its `workspaceId` is set to this workspace. | | `options?` | `IngestOptions` | `wait`, `timeoutMs`, and tag ids. See `IngestOptions`. | | `options.wait?` | `boolean` | Block until ingestion reaches a terminal status. | | `options.tags?` | `number[]` | Tag ids to assign to the document on upload. | | `options.timeoutMs?` | `number` | Milliseconds before giving up. Default 300\_000. | | `options.pollMs?` | `number` | Milliseconds between status checks. Default 2000. | **Returns** | Type | Description | | --------------------------------- | --------------------------------------------------- | | `Promise` | The created File, bound to this workspace's client. | **Throws** | Error | When | | ------- | -------------------------------------------------------- | | `Error` | If this workspace has not been created or retrieved yet. | #### `Workspace.ingestMany()` ```typescript theme={null} ingestMany(files: readonly (File | string)[], options?: BatchOptions & { mode?: typeof ExecMode.sync; }): Promise ingestMany(files: readonly (File | string)[], options: BatchOptions & { mode: typeof ExecMode.async; }): Promise ``` Upload many files into this workspace, concurrently. Every local path is validated to exist **before** any upload starts. Staying under the API rate limit and honoring the 429 cooldown are the client's job, so they apply across uploads and status polls alike. **Arguments** | Name | Type | Description | | ------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `files` | `readonly (File \| string)[]` | Items to ingest: `File` objects and path strings, mixed. A string containing `*`, `?` or `[` is expanded as a glob (`**` works); duplicates are ignored. Files carrying a `blob` need no filesystem. | | `options?` | `BatchOptions & { mode?: typeof ExecMode.sync; }` | Execution mode, error handling and concurrency. See `BatchOptions`. | | `options.ignoreErrors?` | `boolean` | If false (the default), the first failure throws, inline or from `job.wait()`. If true, failures are collected and the batch carries on. | | `options.wait?` | `boolean` | Wait for each upload's ingestion to finish, not just to be accepted. | | `options.timeoutMs?` | `number` | Per-file milliseconds to wait for ingestion when `wait` is set. Default 300\_000. | | `options.pollMs?` | `number` | Milliseconds between ingestion status checks. Default 2000. | | `options.maxConcurrency?` | `number` | Concurrent uploads and polls. Default 8. | | `options.tags?` | `number[]` | Tag ids assigned to every uploaded document. | | `options.mode?` | `typeof ExecMode.sync` | | **Returns** | Type | Description | | ------------------------------------------------- | ------------------------------------------------------------------- | | `Promise \| Promise` | A `BatchIngest` inline, or a `BatchIngestJob` with `mode: "async"`. | **Throws** | Error | When | | ------- | ------------------------------------------------------------------ | | `Error` | If this workspace has no id, or an item has neither path nor blob. | | `Error` | If any path is missing and `ignoreErrors` is unset. | #### `Workspace.refresh()` ```typescript theme={null} refresh(): Promise ``` Re-fetch this resource from the API. **Returns** | Type | Description | | --------------- | --------------------------------------------- | | `Promise` | `this`, updated with the latest field values. | #### `Workspace.save()` ```typescript theme={null} save(): Promise ``` Persist local edits to name and description. **Returns** | Type | Description | | --------------- | --------------------------------------------- | | `Promise` | `this`, refreshed with the server's response. | ### WorkspaceInit | Field | Type | Description | | -------------- | -------- | ----------- | | `name?` | `string` | | | `description?` | `string` | | ### WorkspaceListOptions | Field | Type | Description | | ---------- | ------------------ | ----------------------------------------------------------------------------- | | `filters?` | `WorkspaceFilters` | Endpoint filters under their API names, e.g. `name`, `user_role`, `ordering`. | ### IngestOptions | Field | Type | Description | | ------------ | ---------- | ------------------------------------------------- | | `wait?` | `boolean` | Block until ingestion reaches a terminal status. | | `tags?` | `number[]` | Tag ids to assign to the document on upload. | | `timeoutMs?` | `number` | Milliseconds before giving up. Default 300\_000. | | `pollMs?` | `number` | Milliseconds between status checks. Default 2000. | ### WorkspaceTaxonomy How much of a workspace is classified, and under which roots. The cheapest way to see classification coverage without listing files. Only the list endpoint returns it; the detail endpoint omits the key entirely, so `get()` and `refresh()` leave whatever was already there rather than clearing it. | Field | Type | Description | | --------------------- | ------------------- | -------------------------------------------------------------------- | | `classifiedFilesRate` | `number` | Fraction of the workspace's files that carry a content type, 0 to 1. | | `rootContentTypes` | `RootContentType[]` | Per-root document counts, one entry per root content type. | ### RootContentType How many of a workspace's documents sit under one root content type. | Field | Type | Description | | ------- | -------- | -------------------------------------------------- | | `path` | `string` | Root content-type path, e.g. `legal`. | | `label` | `string` | Human-readable label for that root. | | `count` | `number` | Documents classified under it, including children. | ### WorkspaceSync The external datasource a workspace imports from, when one is connected. Null on a workspace whose documents were uploaded directly. | Field | Type | Description | | ------------------- | ----------------- | -------------------------------------------------------- | | `name?` | `string \| null` | | | `datasourceType?` | `string \| null` | | | `sourceName?` | `string \| null` | | | `lastStatus?` | `string \| null` | Outcome of the last import run. | | `updatedAt?` | `string \| null` | When the sync last ran; null if it never has. | | `nextImportDate?` | `string \| null` | When the next import is due; null if none is scheduled. | | `failedFilesCount?` | `number \| null` | Files the last run could not import. | | `editable?` | `boolean \| null` | Whether the caller may change this configuration. | | `instanceUrl?` | `string \| null` | | | `tenantId?` | `string \| null` | | | `siteName?` | `string \| null` | | | `clientId?` | `string \| null` | | | `filterCriteria?` | `unknown` | Datasource-specific import filter, passed through as-is. | ### File ```typescript theme={null} new File(init?: FileInit) ``` | Name | Type | Description | | ------- | ---------- | ----------- | | `init?` | `FileInit` | | | Field | Type | Description | | ------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `number \| null` | Server-assigned id; null until created or retrieved. | | `path?` | `string` | Local source path; set before create(), never present in a response. | | `blob?` | `Blob` | Source bytes, as an alternative to `path`. Never present in a response. | | `workspaceId?` | `number \| null` | | | `filename?` | `string \| null` | | | `title?` | `string \| null` | | | `externalMetadata?` | `ExternalMetadata \| null` | | | `status?` | `FileStatus \| null` | Ingestion pipeline status (read-only). | | `statusDetail?` | `string \| null` | Free-text error detail, present only on failure (read-only). | | `pendingReprocess?` | `ReprocessLevel \| null` | Reprocessing queued but not started (read-only). While this is set, `status` and the file-derived fields still describe the *previous* run; it clears the moment processing starts. `update` means a file replacement. | | `extension?` | `string \| null` | | | `totalPages?` | `number \| null` | | | `size?` | `number \| null` | | | `thumbnail?` | `Thumbnail \| null` | Check `status` is `READY` before calling `downloadThumbnail()`. | | `createdAt?` | `string \| null` | | | `updatedAt?` | `string \| null` | | #### `File.deleteMany()` ```typescript theme={null} static deleteMany(client: Transport, files: readonly (File | number)[]): Promise ``` Delete many files in one request. All-or-nothing: if any id is unknown (or not yours), the API rejects the whole call with 404 and deletes **nothing**, which surfaces as a `NotFoundError`. There is no partial-success result to report, so a failure throws rather than returning a per-file report: nothing was deleted, and retrying with the ids you can account for is the fix. **Arguments** | Name | Type | Description | | -------- | ----------------------------- | --------------------------------------------------------------------------------------------- | | `client` | `Transport` | The client to delete with. | | `files` | `readonly (File \| number)[]` | Files or bare ids, mixed. Empty is a local no-op, because the endpoint rejects an empty list. | **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | **Throws** | Error | When | | --------------- | ------------------------------------------------------ | | `NotFoundError` | If any id is unknown; no file is deleted in that case. | #### `File.get()` ```typescript theme={null} static get(client: Transport, id: number | string): Promise ``` Fetch a single file by id. **Arguments** | Name | Type | Description | | -------- | ------------------ | -------------------------------------------------- | | `client` | `Transport` | The client to request with and bind to the result. | | `id` | `number \| string` | The file id to retrieve. | **Returns** | Type | Description | | --------------- | ---------------------------- | | `Promise` | The file, bound to `client`. | #### `File.getByName()` ```typescript theme={null} static getByName(client: Transport, name: string, workspace: IdRef): Promise ``` Fetch every file with this user-facing name in a workspace. Matches `title`, not `filename`: the server uniquifies filenames on upload (`report.pdf` is stored as something like `report_20260728_c9be.pdf`), so the name you uploaded never matches the stored one. A title defaults to the uploaded filename without its extension, so `report.pdf` and `report` both find that upload. Titles are not unique the way stored filenames are, so this returns every match rather than picking one. The API's `title` filter is a case-insensitive *partial* match, so candidates are narrowed to an exact title match here. **Arguments** | Name | Type | Description | | ----------- | ----------- | ----------------------------------------------------- | | `client` | `Transport` | The client to query with and bind to the results. | | `name` | `string` | The file's title, with or without an extension. | | `workspace` | `IdRef` | The workspace to search in (a `Workspace` or its id). | **Returns** | Type | Description | | ----------------- | ------------------------------------------------ | | `Promise` | Every File with that title; empty if none match. | **Throws** | Error | When | | ------- | --------------------------------------------------- | | `Error` | If the workspace has not been created or retrieved. | #### `File.list()` ```typescript theme={null} static list(client: Transport, options?: FileListOptions): Promise ``` List files, following pagination to the end. **Arguments** | Name | Type | Description | | ---------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client` | `Transport` | The client to request with and bind to each result. | | `options?` | `FileListOptions` | `workspaceId`, `title`, and any other endpoint filter under `filters`. | | `options.workspaceId?` | `number` | | | `options.title?` | `string` | | | `options.filters?` | `FileFilters` | Any other filter the endpoint accepts, under its API name: `status`, `tag_id`, `external_metadata__external_id`, `ordering`, date ranges... Where it overlaps `workspaceId` or `title`, those win. | **Returns** | Type | Description | | ----------------- | -------------------- | | `Promise` | Every matching file. | #### `File.classify()` ```typescript theme={null} classify(contentType: PathRef): Promise ``` Assign a content type to this file. **Arguments** | Name | Type | Description | | ------------- | --------- | ----------- | | `contentType` | `PathRef` | | **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | #### `File.clearAttribute()` ```typescript theme={null} clearAttribute(contentType: PathRef, name: string): Promise ``` Clear an attribute value under an assigned content type. **Arguments** | Name | Type | Description | | ------------- | --------- | ----------- | | `contentType` | `PathRef` | | | `name` | `string` | | **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | #### `File.create()` ```typescript theme={null} create(client: Transport, options?: CreateOptions): Promise ``` Upload the file. This starts ingestion. **Arguments** | Name | Type | Description | | --------------------------- | ------------------ | ----------------------------------------------------------- | | `client` | `Transport` | The client to upload with and bind to `this`. | | `options?` | `CreateOptions` | Tags to assign, and external metadata. See `CreateOptions`. | | `options.tags?` | `number[]` | Tag ids to assign on upload. | | `options.externalMetadata?` | `ExternalMetadata` | Overrides the `externalMetadata` field when both are set. | **Returns** | Type | Description | | --------------------------------- | --------------------------------------------------------------- | | `Promise` | `this`, updated with the server-assigned id and initial status. | **Throws** | Error | When | | ------- | ---------------------------------------- | | `Error` | If no source or no `workspaceId` is set. | #### `File.delete()` ```typescript theme={null} delete(): Promise ``` Delete this resource and clear its local id. **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | #### `File.download()` ```typescript theme={null} download(purpose?: DownloadPurpose | string): Promise ``` Download this document's stored bytes. **Arguments** | Name | Type | Description | | ---------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `purpose?` | `DownloadPurpose \| string` | Which stored version to fetch. The server falls back to `original` when the requested purpose has no associated file, so this never 404s just because a rendition is missing. | **Returns** | Type | Description | | --------------------- | ----------------- | | `Promise` | The file content. | #### `File.downloadThumbnail()` ```typescript theme={null} downloadThumbnail(): Promise ``` Download this document's 256x256 WebP thumbnail. Generated asynchronously and **independently of ingestion**, so an embedded file may still have none. Check the `thumbnail` field first. **Returns** | Type | Description | | --------------------- | --------------- | | `Promise` | The WebP image. | **Throws** | Error | When | | --------------- | ----------------------------------------------- | | `NotFoundError` | If no thumbnail exists (status is not `READY`). | #### `File.facets()` ```typescript theme={null} facets(): Promise ``` List this file's assigned content types and their attribute values. **Returns** | Type | Description | | ------------------ | ----------- | | `Promise` | | #### `File.pages()` ```typescript theme={null} pages(): Promise ``` Fetch the parsed text of this document, one entry per page. The platform stores what it parsed at ingestion, so this reads it back instead of re-uploading and re-parsing a document it already has. The result is the **same** `{index, markdown}` shape `parse` returns, so code can move between parsing a local file and reading an ingested one without reshaping anything. A method, not a field: the text can be large, and most callers of `refresh()` don't want it riding along. **Returns** | Type | Description | | ----------------- | ------------------------------------------------------------ | | `Promise` | One Page per page. Empty if the document has no stored text. | #### `File.refresh()` ```typescript theme={null} refresh(): Promise ``` Re-fetch this resource from the API. **Returns** | Type | Description | | --------------- | --------------------------------------------- | | `Promise` | `this`, updated with the latest field values. | #### `File.replace()` ```typescript theme={null} replace(source: string | Blob | { filename: string; blob: Blob; }, options?: WaitOptions & { wait?: boolean; }): Promise ``` Replace this document's content in place. The document keeps its id, title, tags and content-type classifications, and is re-ingested from the new content, so every reference to the id survives what used to need a delete plus a re-upload. The new file may be of a different type. `filename` follows the new file, but `title` is preserved, so a replaced document is still found under the name it was uploaded with. Addressed by **id**, never by name: titles and filenames aren't unique, so resolve to the one document you mean first. **Arguments** | Name | Type | Description | | -------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------- | | `source` | `string \| Blob \| { filename: string; blob: Blob; }` | Local path, `File`, or `{filename, blob}` whose content replaces the current one. | | `options?` | `WaitOptions & { wait?: boolean; }` | `wait` to block until re-ingestion is terminal, plus `timeoutMs`. | | `options.timeoutMs?` | `number` | Milliseconds before giving up. Default 300\_000. | | `options.pollMs?` | `number` | Milliseconds between status checks. Default 2000. | | `options.wait?` | `boolean` | | **Returns** | Type | Description | | --------------- | ---------------------------------------------------------------------------------------------------------- | | `Promise` | `this`. Without `wait`, the absorbed fields still describe the *previous* content, see `pendingReprocess`. | #### `File.save()` ```typescript theme={null} save(options?: SaveOptions): Promise ``` Persist local edits to `title`, plus whatever you pass explicitly. `filename` is immutable server-side. `title` is a plain field: set it and save. `tags` and `externalMetadata` are **options, not fields**, because neither is a plain set server-side, and naming them at the call site says which one you are doing. Omitting either leaves that part of the document untouched, so a bare `save()` only ever writes the title. **Arguments** | Name | Type | Description | | --------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `options?` | `SaveOptions` | Replacement tags and metadata to merge. See `SaveOptions`. | | `options.tags?` | `readonly TagRef[]` | Replacement tags: this **replaces** every tag on the document, auto-assigned included. Omit to leave tags untouched; pass `[]` to clear them all. | | `options.externalMetadata?` | `ExternalMetadata` | Origin fields to **merge** into what is stored. Omit to leave it untouched. | **Returns** | Type | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `Promise` | `this`, refreshed with the server's response, so `externalMetadata` shows the merged result rather than the partial value you sent. | #### `File.setAttribute()` ```typescript theme={null} setAttribute(contentType: PathRef, name: string, value: unknown): Promise ``` Set an attribute value under an assigned content type. **Arguments** | Name | Type | Description | | ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- | | `contentType` | `PathRef` | The assigned content type, or its path. | | `name` | `string` | Attribute identifier (snake\_case). | | `value` | `unknown` | The value; its shape follows the attribute type (string, number, date `YYYY-MM-DD`, boolean, or string\[] for multi-select). | **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | #### `File.tag()` ```typescript theme={null} tag(tags: readonly TagRef[]): Promise ``` Assign tags to this file. **Arguments** | Name | Type | Description | | ------ | ------------------- | ------------------------------------------------------------------- | | `tags` | `readonly TagRef[]` | Tags to add: `Tag` objects, ids, or names, mixed. Empty is a no-op. | **Returns** | Type | Description | | --------------- | ------------------------------------ | | `Promise` | `this`, refreshed from the response. | #### `File.unclassify()` ```typescript theme={null} unclassify(contentType: PathRef): Promise ``` Remove a content-type assignment from this file. **Arguments** | Name | Type | Description | | ------------- | --------- | ----------- | | `contentType` | `PathRef` | | **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | #### `File.untag()` ```typescript theme={null} untag(tags: readonly TagRef[]): Promise ``` Remove tags from this file, one request each: there is no bulk tag delete. **Arguments** | Name | Type | Description | | ------ | ------------------- | ---------------------------------------------------------------------- | | `tags` | `readonly TagRef[]` | Tags to remove: `Tag` objects, ids, or names, mixed. Empty is a no-op. | **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | `this`. | #### `File.wait()` ```typescript theme={null} wait(options?: WaitOptions): Promise ``` Poll until ingestion reaches a terminal state. A pending reprocess counts as *not* terminal: while `pendingReprocess` is set the queued work has not started and `status` still reports the previous run, so trusting it would call a `replace()` done before it began. ponytail: a plain poll loop, because the API offers no webhook. Use `waitAll` to run several concurrently. **Arguments** | Name | Type | Description | | -------------------- | ------------- | ------------------------------------------------- | | `options?` | `WaitOptions` | `timeoutMs` and `pollMs`. See `WaitOptions`. | | `options.timeoutMs?` | `number` | Milliseconds before giving up. Default 300\_000. | | `options.pollMs?` | `number` | Milliseconds between status checks. Default 2000. | **Returns** | Type | Description | | --------------- | --------------------------------------------------------------------- | | `Promise` | `this`, once `status` is terminal-success and no reprocess is queued. | **Throws** | Error | When | | -------------- | ---------------------------------------------- | | `Error` | If the timeout elapses first. | | `LightOnError` | If ingestion ends in a terminal-failure state. | ### LightOnFile Alias of [`File`](#file). ### FileInit | Field | Type | Description | | ------------------- | ------------------ | ----------------------------------------------------------------------- | | `path?` | `string` | Local path to upload. Node-family runtimes only; elsewhere pass `blob`. | | `blob?` | `Blob` | File bytes, for runtimes with no filesystem. Needs `filename`. | | `workspaceId?` | `number` | Target workspace. `Workspace.ingest()` fills this in for you. | | `filename?` | `string` | Document filename; defaults to the path's basename on upload. | | `title?` | `string` | Document title; defaults to the filename server-side. | | `externalMetadata?` | `ExternalMetadata` | | ### FileListOptions | Field | Type | Description | | -------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspaceId?` | `number` | | | `title?` | `string` | | | `filters?` | `FileFilters` | Any other filter the endpoint accepts, under its API name: `status`, `tag_id`, `external_metadata__external_id`, `ordering`, date ranges... Where it overlaps `workspaceId` or `title`, those win. | ### CreateOptions | Field | Type | Description | | ------------------- | ------------------ | --------------------------------------------------------- | | `tags?` | `number[]` | Tag ids to assign on upload. | | `externalMetadata?` | `ExternalMetadata` | Overrides the `externalMetadata` field when both are set. | ### SaveOptions | Field | Type | Description | | ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `tags?` | `readonly TagRef[]` | Replacement tags: this **replaces** every tag on the document, auto-assigned included. Omit to leave tags untouched; pass `[]` to clear them all. | | `externalMetadata?` | `ExternalMetadata` | Origin fields to **merge** into what is stored. Omit to leave it untouched. | ### WaitOptions | Field | Type | Description | | ------------ | -------- | ------------------------------------------------- | | `timeoutMs?` | `number` | Milliseconds before giving up. Default 300\_000. | | `pollMs?` | `number` | Milliseconds between status checks. Default 2000. | ### FileSource A local path (Node-family runtimes), a `File`/`Blob`, or a `Blob` with a name. ```typescript theme={null} type FileSource = string | Blob | { filename: string; blob: Blob; } ``` ### ExternalMetadata Where a document came from in a third-party system. Set it on upload (or with `save()`) and it survives on the File, so a later sync can match the platform document back to the record it was ingested from. Updates **merge** server-side, including into `additionalMetadata`: patching one key leaves the others in place. There is no replace mode and no way to drop the record. What you *can* clear, verified against the live API: | to remove | how | | ------------------------------- | ------------------------------------------- | | `docType` | `{ docType: "" }` | | one key of `additionalMetadata` | `{ additionalMetadata: { version: null } }` | | `externalId` | not possible, it can only be overwritten | | the whole record | not possible | | Field | Type | Description | | --------------------- | ---------------- | ---------------------------------------------------------------- | | `externalId?` | `string \| null` | Document id in the source system; required the first time. | | `docType?` | `string \| null` | Document type in the source system, e.g. `incident`. | | `additionalMetadata?` | `unknown` | Arbitrary JSON (url, version, timestamps), passed through as-is. | ### Thumbnail Whether a file's 256x256 WebP thumbnail exists yet, and where it lives. Generation is asynchronous and independent of ingestion, so check `status` before fetching: `file.downloadThumbnail()` 404s while it isn't `READY`. | Field | Type | Description | | --------- | ------------------------- | --------------------------------------------------------- | | `status?` | `ThumbnailStatus \| null` | | | `url?` | `string \| null` | Relative URL to the image; null unless status is `READY`. | ### Page One page of a document. Defined once and reused everywhere: `parse` returns these, and so does `file.pages()`, so code moves between parsing a local file and reading an ingested one without reshaping. Never redefine this shape per app. | Field | Type | Description | | ---------- | -------- | ----------- | | `index` | `number` | | | `markdown` | `string` | | ### `waitAll()` ```typescript theme={null} export declare function waitAll(files: readonly File[], options?: WaitOptions): Promise ``` Wait for many ingestions at once. **Arguments** | Name | Type | Description | | -------------------- | ----------------- | ------------------------------------------------------- | | `files` | `readonly File[]` | The files to wait on; each is polled via `file.wait()`. | | `options?` | `WaitOptions` | Passed to each `wait()`. | | `options.timeoutMs?` | `number` | Milliseconds before giving up. Default 300\_000. | | `options.pollMs?` | `number` | Milliseconds between status checks. Default 2000. | **Returns** | Type | Description | | ----------------- | ---------------------------------------------------------------- | | `Promise` | The same files, once each has reached a terminal-success status. | **Throws** | Error | When | | -------------- | --------------------------------------------------------- | | `Error` | If any file does not finish in time. | | `LightOnError` | If any file's ingestion ends in a terminal-failure state. | ## Tags & content types ### Tag ```typescript theme={null} new Tag(init?: TagInit) ``` | Name | Type | Description | | ------- | --------- | ----------- | | `init?` | `TagInit` | | | Field | Type | Description | | ---------------- | ---------------- | ---------------------------------------------------- | | `id` | `number \| null` | Server-assigned id; null until created or retrieved. | | `name` | `string` | | | `description` | `string` | | | `autoAssign` | `boolean` | | | `documentCount?` | `number \| null` | Number of documents carrying this tag (read-only). | | `createdAt?` | `string \| null` | | | `updatedAt?` | `string \| null` | | #### `Tag.get()` ```typescript theme={null} static get(): Promise ``` Not available: the tags API exposes no single-tag GET. Declared so the failure is a clear message at the call site rather than a 404 from a URL that was never going to exist. Use `Tag.list` instead. **Returns** | Type | Description | | ---------------- | ----------- | | `Promise` | | **Throws** | Error | When | | ------- | ------- | | `Error` | Always. | #### `Tag.list()` ```typescript theme={null} static list(client: Transport, options?: TagListOptions): Promise ``` List every tag, following pagination to the end. **Arguments** | Name | Type | Description | | ------------------ | ---------------- | ------------------------------------------------------------------- | | `client` | `Transport` | The client to request with and bind to each result. | | `options?` | `TagListOptions` | Endpoint filters under `filters`, by their API names. | | `options.filters?` | `TagFilters` | Endpoint filters under their API names, e.g. `name`, `auto_assign`. | **Returns** | Type | Description | | ---------------- | -------------------------------------- | | `Promise` | Every matching tag, bound to `client`. | #### `Tag.create()` ```typescript theme={null} create(client: Transport): Promise ``` Create this tag and bind the client for later lifecycle calls. **Arguments** | Name | Type | Description | | -------- | ----------- | ----------------------------------------------------- | | `client` | `Transport` | The client to create the tag with and bind to `this`. | **Returns** | Type | Description | | --------------------------------- | -------------------------------------------- | | `Promise` | `this`, updated with the server-assigned id. | #### `Tag.delete()` ```typescript theme={null} delete(): Promise ``` Delete this resource and clear its local id. **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | #### `Tag.refresh()` ```typescript theme={null} refresh(): Promise ``` Re-fetch this resource from the API. **Returns** | Type | Description | | ---------------- | ----------- | | `Promise` | | **Throws** | Error | When | | ------- | ----------------------------------------------- | | `Error` | Always: the tags API exposes no single-tag GET. | ### TagInit | Field | Type | Description | | -------------- | --------- | ------------------------------------------------------------------ | | `name?` | `string` | | | `description?` | `string` | | | `autoAssign?` | `boolean` | If true the system may auto-assign this tag; else it is user-only. | ### TagListOptions | Field | Type | Description | | ---------- | ------------ | ------------------------------------------------------------------- | | `filters?` | `TagFilters` | Endpoint filters under their API names, e.g. `name`, `auto_assign`. | ### TagRef A `Tag`, its id, or its name. The three mix freely in one list. ```typescript theme={null} type TagRef = number | string | Tag | { readonly id: number | string | null; } ``` ### ContentType A node in the content-type taxonomy. | Field | Type | Description | | -------------- | ---------------- | ---------------------------------------------------------------- | | `path` | `string` | Full taxonomy path, e.g. `legal:contract:nda`. | | `code` | `string` | This node's own code segment. | | `label` | `string` | | | `description?` | `string` | | | `source?` | `string \| null` | Where the type is defined (read-only). | | `attributes?` | `Attribute[]` | Attribute definitions, present when `includeAttributes` was set. | | `children?` | `ContentType[]` | | #### `ContentType.adopt()` ```typescript theme={null} adopt(client: Transport, paths: readonly string[]): Promise ``` Import starter trees from the template catalog into your taxonomy. **Arguments** | Name | Type | Description | | -------- | ------------------- | ----------------------------------------------------------- | | `client` | `Transport` | The client to write with. | | `paths` | `readonly string[]` | Template root paths to import, e.g. `["legal", "finance"]`. | **Returns** | Type | Description | | ------------------------ | ----------------------------- | | `Promise` | The imported top-level nodes. | #### `ContentType.batch()` ```typescript theme={null} batch(client: Transport, actions: readonly Record[]): Promise ``` Apply several taxonomy actions in one request. Each entry is the body a single-action method would send, so a tree and its attributes land together instead of one round trip each: ```ts theme={null} await ContentType.batch(client, [ \{ action: "adopt", content_types: ["legal"] \}, \{ action: "define_attribute", content_type_path: "legal", name: "jurisdiction", attribute_type: "select", choices: ["FR", "US"], \}, ]) ``` The entries are wire bodies, so their keys are the server's, not the SDK's. **Arguments** | Name | Type | Description | | --------- | ------------------------------------ | ---------------------------- | | `client` | `Transport` | The client to write with. | | `actions` | `readonly Record[]` | The action bodies, in order. | **Returns** | Type | Description | | ------------------------------ | ----------------------------------------- | | `Promise` | One result per action, in the same order. | #### `ContentType.define()` ```typescript theme={null} define(client: Transport, code: string, label: string, options?: DefineOptions): Promise ``` Create or update one node. Idempotent: defining an existing code again updates it, so this is also how you rename a node. **Arguments** | Name | Type | Description | | ---------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- | | `client` | `Transport` | The client to write with. | | `code` | `string` | This node's own segment: lowercase alphanumeric with hyphens, e.g. `employment-contract`. The server rejects anything else. | | `label` | `string` | Human-readable label. | | `options?` | `DefineOptions` | Parent, description, and attribute inheritance. | | `options.parent?` | `PathRef` | Parent node or path; omit for a root node. | | `options.description?` | `string` | | | `options.inheritAttributes?` | `boolean` | Whether children inherit this node's attributes (server default true). | **Returns** | Type | Description | | ---------------------- | ------------------------------ | | `Promise` | The created (or updated) node. | #### `ContentType.defineAttribute()` ```typescript theme={null} defineAttribute(client: Transport, contentType: PathRef, name: string, attributeType: AttributeType | string, options?: DefineAttributeOptions): Promise ``` Create or update an attribute column on a node. **Arguments** | Name | Type | Description | | ---------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------- | | `client` | `Transport` | The client to write with. | | `contentType` | `PathRef` | The node to define it on, or its path. | | `name` | `string` | Attribute identifier, snake\_case. | | `attributeType` | `AttributeType \| string` | An `AttributeType`, or the equivalent string. | | `options?` | `DefineAttributeOptions` | Choices, label, description and whether it is required. | | `options.choices?` | `string[]` | Allowed values. **Required** for `select` and `multi-select`, and rejected by the server for every other type. | | `options.label?` | `string` | Human-readable label; defaults to a title-cased `name`. | | `options.description?` | `string` | | | `options.required?` | `boolean` | Whether the schema requires a value (server default false). | **Returns** | Type | Description | | -------------------- | ---------------------------------------------- | | `Promise` | The created (or updated) attribute definition. | **Throws** | Error | When | | ------- | --------------------------------------------------------------------------------------------------------------------------------- | | `Error` | If a `select`/`multi-select` is missing `choices`. The API rejects that with a 422 anyway; catching it here saves the round trip. | #### `ContentType.list()` ```typescript theme={null} list(client: Transport, options?: ContentTypeListOptions): Promise ``` List the content-type taxonomy: top-level nodes, each carrying its `children`. **Arguments** | Name | Type | Description | | ---------------------------- | ------------------------ | ---------------------------------------------- | | `client` | `Transport` | The client to query with. | | `options?` | `ContentTypeListOptions` | Subtree, depth, attribute and search filters. | | `options.path?` | `string` | Restrict to the subtree rooted at this path. | | `options.depth?` | `number` | How many levels of children to return. | | `options.includeAttributes?` | `boolean` | Populate each node's `attributes` definitions. | | `options.query?` | `string` | Free-text filter over labels and paths. | **Returns** | Type | Description | | ------------------------ | --------------------------------- | | `Promise` | The top-level content-type nodes. | #### `ContentType.templates()` ```typescript theme={null} templates(client: Transport): Promise ``` List the starter taxonomies you can `ContentType.adopt`. **Arguments** | Name | Type | Description | | -------- | ----------- | ------------------------- | | `client` | `Transport` | The client to query with. | **Returns** | Type | Description | | --------------------- | ----------------------------------------------------------------------------------------------------- | | `Promise` | The template root nodes, each with its `children` and an `attributes` map covering the whole subtree. | #### `ContentType.undefine()` ```typescript theme={null} undefine(client: Transport, contentType: PathRef): Promise ``` Delete a node **and cascade its whole subtree**. **Arguments** | Name | Type | Description | | ------------- | ----------- | -------------------------------- | | `client` | `Transport` | The client to write with. | | `contentType` | `PathRef` | The node to delete, or its path. | **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | #### `ContentType.undefineAttribute()` ```typescript theme={null} undefineAttribute(client: Transport, contentType: PathRef, name: string): Promise ``` Remove an attribute column from a node. **Arguments** | Name | Type | Description | | ------------- | ----------- | --------------------------------------- | | `client` | `Transport` | The client to write with. | | `contentType` | `PathRef` | The node it is defined on, or its path. | | `name` | `string` | Attribute identifier to remove. | **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | ### ContentTypeListOptions | Field | Type | Description | | -------------------- | --------- | ---------------------------------------------- | | `path?` | `string` | Restrict to the subtree rooted at this path. | | `depth?` | `number` | How many levels of children to return. | | `includeAttributes?` | `boolean` | Populate each node's `attributes` definitions. | | `query?` | `string` | Free-text filter over labels and paths. | ### DefineOptions | Field | Type | Description | | -------------------- | --------- | ---------------------------------------------------------------------- | | `parent?` | `PathRef` | Parent node or path; omit for a root node. | | `description?` | `string` | | | `inheritAttributes?` | `boolean` | Whether children inherit this node's attributes (server default true). | ### DefineAttributeOptions | Field | Type | Description | | -------------- | ---------- | -------------------------------------------------------------------------------------------------------------- | | `choices?` | `string[]` | Allowed values. **Required** for `select` and `multi-select`, and rejected by the server for every other type. | | `label?` | `string` | Human-readable label; defaults to a title-cased `name`. | | `description?` | `string` | | | `required?` | `boolean` | Whether the schema requires a value (server default false). | ### Template A starter taxonomy from the catalog, what `adopt()` imports. The same tree as a `ContentType` except for `attributes`: on a template it is a **map** from node path to that node's attribute definitions, with the whole subtree's attributes hanging off the root, rather than this node's own list. A sibling interface, not an extension: TypeScript cannot re-type an inherited member, so the Python subclass (which needs a `# type: ignore` for exactly this) has no direct equivalent. | Field | Type | Description | | -------------- | ----------------------------- | ----------------------------------------------------------- | | `attributes?` | `Record` | Attribute definitions per node path, for the whole subtree. | | `path` | `string` | Full taxonomy path, e.g. `legal:contract:nda`. | | `code` | `string` | This node's own code segment. | | `label` | `string` | | | `description?` | `string` | | | `source?` | `string \| null` | Where the type is defined (read-only). | | `children?` | `ContentType[]` | | ### Attribute One attribute of a content type: a definition, or a value set on a file. Carries both the schema (`type`/`required`/`choices`) and, when read from a file's facets, the current `value`. `value` is absent for a bare definition or when unset. | Field | Type | Description | | -------------- | ---------- | ----------------------------------------------------------------- | | `name` | `string` | Attribute identifier, snake\_case. | | `label?` | `string` | | | `type?` | `string` | One of the `AttributeType` values. | | `value?` | `unknown` | Current value on the file; absent for a definition or when unset. | | `required?` | `boolean` | | | `choices?` | `string[]` | Allowed values, for `select` and `multi-select`. | | `description?` | `string` | | ### Facet A content type assigned to a file, with the file's attribute values on it. | Field | Type | Description | | ------------ | ------------- | --------------------------------------- | | `path` | `string` | Assigned content-type path on the file. | | `label` | `string` | | | `attributes` | `Attribute[]` | Attribute values set on the file. | ### BatchActionResult One result of a `ContentType.batch` call. | Field | Type | Description | | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | `number` | HTTP status this action would have returned on its own. | | `data?` | `unknown` | The node or attribute the action produced. Left as-is, including its wire naming: `data` is one of the opaque keys the camelCase boundary does not rewrite, because which shape it holds depends on the action. Reach for the single-action methods when you want a typed result. | ## API keys ### ApiKey ```typescript theme={null} new ApiKey(init?: ApiKeyInit) ``` | Name | Type | Description | | ------- | ------------ | ----------- | | `init?` | `ApiKeyInit` | | | Field | Type | Description | | ------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string \| null` | String id, unlike every other resource. | | `name` | `string` | | | `expiresAt?` | `string \| null` | | | `scopes` | `ApiKeyScope[]` | | | `prefix?` | `string \| null` | Non-secret key prefix for identification (read-only). | | `createdAt?` | `string \| null` | | | `key?` | `string \| null` | The plaintext secret. Returned by `create()` only, once. Readable as `apiKey.key`, but non-enumerable, so `console.log`, `util.inspect`, `JSON.stringify` and object spread all leave it out. This is the TypeScript counterpart of the Python SDK's `SecretStr`: a key logged by accident is the likeliest way one leaks. | #### `ApiKey.get()` ```typescript theme={null} static get(client: Transport, id: string): Promise ``` Fetch a single API key by id. The plaintext secret is never included. **Arguments** | Name | Type | Description | | -------- | ----------- | -------------------------------------------------- | | `client` | `Transport` | The client to request with and bind to the result. | | `id` | `string` | The key id to retrieve. | **Returns** | Type | Description | | ----------------- | --------------------------- | | `Promise` | The key, bound to `client`. | #### `ApiKey.list()` ```typescript theme={null} static list(client: Transport, options?: ApiKeyListOptions): Promise ``` List every API key, following pagination to the end. The plaintext secret is never included. **Arguments** | Name | Type | Description | | ------------------ | ------------------- | ---------------------------------------------------------- | | `client` | `Transport` | The client to request with and bind to each result. | | `options?` | `ApiKeyListOptions` | Endpoint filters under `filters`, by their API names. | | `options.filters?` | `ApiKeyFilters` | Endpoint filters under their API names, e.g. `is_expired`. | **Returns** | Type | Description | | ------------------- | ------------------------------------------ | | `Promise` | Every matching API key, bound to `client`. | #### `ApiKey.create()` ```typescript theme={null} create(client: Transport): Promise ``` Create this API key and bind the client for later lifecycle calls. **Arguments** | Name | Type | Description | | -------- | ----------- | ----------------------------------------------------- | | `client` | `Transport` | The client to create the key with and bind to `this`. | **Returns** | Type | Description | | --------------------------------- | ------------------------------------------------------------- | | `Promise` | `this`, updated with the id and the one-time plaintext `key`. | #### `ApiKey.delete()` ```typescript theme={null} delete(): Promise ``` Delete this resource and clear its local id. **Returns** | Type | Description | | --------------- | ----------- | | `Promise` | | #### `ApiKey.refresh()` ```typescript theme={null} refresh(): Promise ``` Re-fetch this resource from the API. **Returns** | Type | Description | | --------------- | --------------------------------------------- | | `Promise` | `this`, updated with the latest field values. | #### `ApiKey.save()` ```typescript theme={null} save(): Promise ``` Persist local edits to name and scopes. **Returns** | Type | Description | | --------------- | ---------------------------------------------------------------------------- | | `Promise` | `this`, refreshed with the server's response, which never re-includes `key`. | ### ApiKeyInit | Field | Type | Description | | ------------ | ---------------- | --------------------------------------------------------------------- | | `name?` | `string` | | | `expiresAt?` | `string \| null` | Expiry timestamp (ISO-8601); omit for no expiry. | | `scopes?` | `ApiKeyScope[]` | Per-workspace access scopes; omit or leave empty for an unscoped key. | ### ApiKeyScope Access granted on one workspace. | Field | Type | Description | | ------------- | -------- | ----------- | | `workspaceId` | `number` | | | `role` | `Role` | | ### ApiKeyListOptions | Field | Type | Description | | ---------- | --------------- | ---------------------------------------------------------- | | `filters?` | `ApiKeyFilters` | Endpoint filters under their API names, e.g. `is_expired`. | ## Verb options ### ScopeOptions | Field | Type | Description | | -------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspaces?` | `readonly IdRef[]` | Restrict to these workspaces. Excludes `files`. | | `tags?` | `readonly TagRef[]` | Restrict to documents carrying any of these tags (OR-matched). Accepts `Tag` objects, ids, or names; names are resolved via the tags endpoint and must exist. Excludes `files`. | | `files?` | `readonly IdRef[]` | Restrict to these files. Excludes `workspaces` and `tags`. | | `contentType?` | `readonly PathRef[]` | Restrict to these content-type paths (OR-matched, exact-or-subtree, so `legal` also matches `legal:contract`). Wildcards: `legal:contract*`, `*nda*`. | | `attribute?` | `readonly string[]` | Restrict by attribute value, e.g. `["fiscal_year:2024\|2025", "status:active"]`. Entries are ANDed, `\|` ORs within one entry. Also `name` (has any value), `name:>value`, `name:prefix*`, `name:*text*`. | | `signal?` | `AbortSignal` | Caller cancellation. | ### AskOptions | Field | Type | Description | | ------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `maxResults?` | `number` | Chunks to retrieve for context (1 to 50; server default 10). | | `relevanceScoring?` | `RelevanceScoring` | Defaults to `scoringAndFiltering` server-side. | | `model?` | `string` | LLM for answer generation; platform default if omitted. | | `schema?` | `SchemaInput` | Constrain the answer to structured output: a Zod schema or a plain JSON Schema object (the same inputs `extract` takes, sent as the API's `response_format`; it must describe an object). The answer then comes back as JSON *text* in `.answer`. The SDK does not parse it back for you, so that a schema mismatch surfaces where you can see it. | | `workspaces?` | `readonly IdRef[]` | Restrict to these workspaces. Excludes `files`. | | `tags?` | `readonly TagRef[]` | Restrict to documents carrying any of these tags (OR-matched). Accepts `Tag` objects, ids, or names; names are resolved via the tags endpoint and must exist. Excludes `files`. | | `files?` | `readonly IdRef[]` | Restrict to these files. Excludes `workspaces` and `tags`. | | `contentType?` | `readonly PathRef[]` | Restrict to these content-type paths (OR-matched, exact-or-subtree, so `legal` also matches `legal:contract`). Wildcards: `legal:contract*`, `*nda*`. | | `attribute?` | `readonly string[]` | Restrict by attribute value, e.g. `["fiscal_year:2024\|2025", "status:active"]`. Entries are ANDed, `\|` ORs within one entry. Also `name` (has any value), `name:>value`, `name:prefix*`, `name:*text*`. | | `signal?` | `AbortSignal` | Caller cancellation. | ### SearchOptions | Field | Type | Description | | ------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `maxResults?` | `number` | Chunks to return after reranking (1 to 100; server default 10). | | `mode?` | `SearchMode` | `text` (hybrid keyword + vector) or `vision` (page image). | | `relevanceScoring?` | `RelevanceScoring` | Defaults to `scoringAndFiltering` server-side. | | `includeImage?` | `boolean` | Attach a base64 page image to each result. | | `includeBboxes?` | `boolean` | Attach chunk bounding boxes (PDF text-mode only). | | `workspaces?` | `readonly IdRef[]` | Restrict to these workspaces. Excludes `files`. | | `tags?` | `readonly TagRef[]` | Restrict to documents carrying any of these tags (OR-matched). Accepts `Tag` objects, ids, or names; names are resolved via the tags endpoint and must exist. Excludes `files`. | | `files?` | `readonly IdRef[]` | Restrict to these files. Excludes `workspaces` and `tags`. | | `contentType?` | `readonly PathRef[]` | Restrict to these content-type paths (OR-matched, exact-or-subtree, so `legal` also matches `legal:contract`). Wildcards: `legal:contract*`, `*nda*`. | | `attribute?` | `readonly string[]` | Restrict by attribute value, e.g. `["fiscal_year:2024\|2025", "status:active"]`. Entries are ANDed, `\|` ORs within one entry. Also `name` (has any value), `name:>value`, `name:prefix*`, `name:*text*`. | | `signal?` | `AbortSignal` | Caller cancellation. | ### ParseOptions | Field | Type | Description | | --------- | ------------- | ---------------------------------------------------------------------- | | `file?` | `FileSource` | A local path, `File`, or `{filename, blob}` to upload. Excludes `url`. | | `url?` | `string` | A publicly accessible URL for the server to fetch. Excludes `file`. | | `signal?` | `AbortSignal` | Caller cancellation. | ### ParseAsyncOptions | Field | Type | Description | | ------------ | ----------------------- | -------------------------------------------------------------------------------- | | `mode` | `typeof ExecMode.async` | | | `wait?` | `boolean` | Block until the job is terminal, so the returned job already carries its result. | | `timeoutMs?` | `number` | With `wait`, how long to wait before throwing. Default 300\_000. | | `file?` | `FileSource` | A local path, `File`, or `{filename, blob}` to upload. Excludes `url`. | | `url?` | `string` | A publicly accessible URL for the server to fetch. Excludes `file`. | | `signal?` | `AbortSignal` | Caller cancellation. | ### ExtractOptions | Field | Type | Description | | ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `file?` | `FileSource` | A local path, `File`, or `{filename, blob}` to upload. | | `url?` | `string` | A publicly accessible URL for the server to fetch. | | `ingested?` | `IdRef` | An already-ingested file (a `File` or its id). No re-upload: the server reads the document it already has, which is the cheapest of the three sources. | | `options?` | `Record` | Free-form request options, merged into the body. | | `signal?` | `AbortSignal` | Caller cancellation. | ### ExtractAsyncOptions | Field | Type | Description | | ------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `mode` | `typeof ExecMode.async` | | | `wait?` | `boolean` | Block until the job is terminal, so the returned job already carries its result. | | `timeoutMs?` | `number` | With `wait`, how long to wait before throwing. Default 300\_000. | | `file?` | `FileSource` | A local path, `File`, or `{filename, blob}` to upload. | | `url?` | `string` | A publicly accessible URL for the server to fetch. | | `ingested?` | `IdRef` | An already-ingested file (a `File` or its id). No re-upload: the server reads the document it already has, which is the cheapest of the three sources. | | `options?` | `Record` | Free-form request options, merged into the body. | | `signal?` | `AbortSignal` | Caller cancellation. | ## Responses ### AskResponse A grounded answer plus the chunks it was grounded in. | Field | Type | Description | | --------- | ----------------- | ----------- | | `answer` | `string` | | | `results` | `AskResultItem[]` | | ### AskResultItem One retrieved chunk used as context by `ask`. | Field | Type | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `bboxes?` | `{ height: number; origin: string; pageNumber: number; unit: string; width: number; x: number; y: number; }[]` | | | `chunkId` | `string` | | | `content` | `string \| null` | | | `image?` | `{ b64Content: string; }` | | | `score` | `number` | | | `scores` | `{ keyword: number \| null; multivector: number \| null; relevance: number \| null; text: number \| null; vision: number \| null; }` | | | `source` | `{ contentTypes?: { [x: string]: unknown; }[] \| undefined; externalMetadata: { additionalMetadata: { [key: string]: unknown; }; externalId: string; externalUrl: string \| null; } \| null; fileId: number; filename: string; mimeType: string \| null; pageEnd: number \| null; pageStart: number \| null; sizeBytes: number \| null; tags: { id: number; name: string; }[]; title: string \| null; totalPages: number; }` | | | `warnings?` | `{ code: string; reason?: string \| undefined; }[]` | | | `workspace` | `{ id: number; name: string; } \| null` | | ### SearchResponse Ranked passages, with optional warnings and scoring breakdown. | Field | Type | Description | | ----------- | --------------------------------------------------- | ----------- | | `explain?` | `{ [key: string]: unknown; }` | | | `results` | `SearchResultItem[]` | | | `warnings?` | `{ code: string; reason?: string \| undefined; }[]` | | ### SearchResultItem One ranked passage returned by `search`. | Field | Type | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `bboxes?` | `{ height: number; origin: string; pageNumber: number; unit: string; width: number; x: number; y: number; }[]` | | | `chunkId` | `string` | | | `content` | `string \| null` | | | `image?` | `{ b64Content: string; }` | | | `score` | `number` | | | `scores` | `{ keyword: number \| null; multivector: number \| null; relevance: number \| null; text: number \| null; vision: number \| null; }` | | | `source` | `{ contentTypes?: { [x: string]: unknown; }[] \| undefined; externalMetadata: { additionalMetadata: { [key: string]: unknown; }; externalId: string; externalUrl: string \| null; } \| null; fileId: number; filename: string; mimeType: string \| null; pageEnd: number \| null; pageStart: number \| null; sizeBytes: number \| null; tags: { id: number; name: string; }[]; title: string \| null; totalPages: number; }` | | | `workspace` | `{ id: number; name: string; } \| null` | | ### ParseResponse A completed synchronous `parse`. | Field | Type | Description | | ------------------ | --------------- | ----------- | | `completedAt` | `string` | | | `createdAt` | `string` | | | `document` | `ParseDocument` | | | `id` | `string` | | | `processingTimeMs` | `number` | | | `result` | `ParseResult` | | | `status` | `string` | | | `usage` | `ParseUsage` | | ### ParseResult | Field | Type | Description | | ------- | -------- | ----------- | | `pages` | `Page[]` | | ### ParseDocument | Field | Type | Description | | --------------- | ---------------- | ----------- | | `fileSizeBytes` | `number` | | | `filename` | `string` | | | `mimeType` | `string` | | | `pageCount` | `number \| null` | | ### ParseUsage | Field | Type | Description | | ---------------- | -------- | ----------- | | `pagesProcessed` | `number` | | ### ParseError | Field | Type | Description | | --------- | -------- | ----------- | | `message` | `string` | | ### ExtractJobResponse An `extract` job, whether it ran inline or was queued. | Field | Type | Description | | ------------------ | ------------------------- | ----------- | | `completedAt` | `string \| null` | | | `createdAt` | `string \| null` | | | `document` | `ExtractDocument \| null` | | | `id` | `string` | | | `processingTimeMs` | `number \| null` | | | `progress` | `JobProgress \| null` | | | `result` | `ExtractResult \| null` | | | `status` | `string` | | | `usage` | `ExtractUsage \| null` | | ### ExtractResult | Field | Type | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------- | ----------- | | `data` | `{ [key: string]: unknown; }[] \| null` | | | `pagination` | `{ hasNext: boolean; hasPrev: boolean; page: number; pageSize: number; totalItems: number; totalPages: number; } \| null` | | ### ExtractDocument | Field | Type | Description | | --------------- | ---------------- | ----------- | | `fileSizeBytes` | `number \| null` | | | `filename` | `string \| null` | | | `mimeType` | `string \| null` | | | `pageCount` | `number \| null` | | ### ExtractUsage | Field | Type | Description | | ---------------- | ---------------- | ----------- | | `pagesProcessed` | `number \| null` | | ### JobProgress Progress reported by a running async job. | Field | Type | Description | | ---------------- | -------- | ----------- | | `pagesProcessed` | `number` | | | `percentage` | `number` | | ## Jobs & batches ### Job A queued parse or extract job. Terminal state is `completedAt` being set, not a status string: the API documents only `pending` and `completed` and publishes no failure vocabulary, so a job that ends badly is one whose `completedAt` is set while `succeeded` is false. ```typescript theme={null} new Jobprotected constructor(transport: Transport, path: string, data: Record) ``` | Name | Type | Description | | ----------- | ------------------------- | ----------- | | `transport` | `Transport` | | | `path` | `string` | | | `data` | `Record` | | | Field | Type | Description | | ------------------- | --------------------- | ------------------------------------------------------------- | | `id` | `string` | | | `status` | `string` | | | `createdAt?` | `string \| null` | | | `completedAt?` | `string \| null` | | | `processingTimeMs?` | `number \| null` | | | `progress?` | `JobProgress \| null` | | | `done` | `boolean` | Whether the job is terminal, successfully or not. | | `succeeded` | `boolean` | Whether the job finished successfully. The one success state. | #### `Job.poll()` ```typescript theme={null} poll(options?: { page?: number; }): Promise ``` Re-fetch the job, updating it in place. **Arguments** | Name | Type | Description | | --------------- | -------------------- | ---------------------------------------------------------------------- | | `options?` | `{ page?: number; }` | `page` selects a page of results; extract paginates, parse ignores it. | | `options.page?` | `number` | | **Returns** | Type | Description | | --------------- | ------------------------------------------------------------------------------ | | `Promise` | This job, updated, so `while (!(await job.poll()).succeeded)` reads naturally. | #### `Job.wait()` ```typescript theme={null} wait(options?: { timeoutMs?: number; pollMs?: number; }): Promise ``` Poll until the job is terminal. **Arguments** | Name | Type | Description | | -------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- | | `options?` | `{ timeoutMs?: number; pollMs?: number; }` | `timeoutMs` before giving up (default 300\_000), `pollMs` between polls (default 2000). | | `options.timeoutMs?` | `number` | | | `options.pollMs?` | `number` | | **Returns** | Type | Description | | --------------- | ------------------- | | `Promise` | This job, finished. | **Throws** | Error | When | | -------------- | ----------------------------- | | `Error` | If the timeout elapses first. | | `LightOnError` | If the job ends in failure. | ### ParseJob An async `parse` job. Differs from `ExtractJob` only in what it carries. | Field | Type | Description | | ------------------- | ----------------------- | --------------------------------------------------------------- | | `document?` | `ParseDocument \| null` | | | `result?` | `ParseResult \| null` | | | `usage?` | `ParseUsage \| null` | | | `error?` | `ParseError \| null` | Set when the parse failed. Only parse reports failure this way. | | `id` | `string` | | | `status` | `string` | | | `createdAt?` | `string \| null` | | | `completedAt?` | `string \| null` | | | `processingTimeMs?` | `number \| null` | | | `progress?` | `JobProgress \| null` | | | `done` | `boolean` | Whether the job is terminal, successfully or not. | | `succeeded` | `boolean` | Whether the job finished successfully. The one success state. | #### `ParseJob.poll()` ```typescript theme={null} poll(options?: { page?: number; }): Promise ``` Re-fetch the job, updating it in place. **Arguments** | Name | Type | Description | | --------------- | -------------------- | ---------------------------------------------------------------------- | | `options?` | `{ page?: number; }` | `page` selects a page of results; extract paginates, parse ignores it. | | `options.page?` | `number` | | **Returns** | Type | Description | | --------------- | ------------------------------------------------------------------------------ | | `Promise` | This job, updated, so `while (!(await job.poll()).succeeded)` reads naturally. | #### `ParseJob.wait()` ```typescript theme={null} wait(options?: { timeoutMs?: number; pollMs?: number; }): Promise ``` Poll until the job is terminal. **Arguments** | Name | Type | Description | | -------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- | | `options?` | `{ timeoutMs?: number; pollMs?: number; }` | `timeoutMs` before giving up (default 300\_000), `pollMs` between polls (default 2000). | | `options.timeoutMs?` | `number` | | | `options.pollMs?` | `number` | | **Returns** | Type | Description | | --------------- | ------------------- | | `Promise` | This job, finished. | **Throws** | Error | When | | -------------- | ----------------------------- | | `Error` | If the timeout elapses first. | | `LightOnError` | If the job ends in failure. | ### ExtractJob An async `extract` job. | Field | Type | Description | | ------------------- | ------------------------- | ------------------------------------------------------------- | | `document?` | `ExtractDocument \| null` | | | `result?` | `ExtractResult \| null` | | | `usage?` | `ExtractUsage \| null` | | | `id` | `string` | | | `status` | `string` | | | `createdAt?` | `string \| null` | | | `completedAt?` | `string \| null` | | | `processingTimeMs?` | `number \| null` | | | `progress?` | `JobProgress \| null` | | | `done` | `boolean` | Whether the job is terminal, successfully or not. | | `succeeded` | `boolean` | Whether the job finished successfully. The one success state. | #### `ExtractJob.poll()` ```typescript theme={null} poll(options?: { page?: number; }): Promise ``` Re-fetch the job, updating it in place. **Arguments** | Name | Type | Description | | --------------- | -------------------- | ---------------------------------------------------------------------- | | `options?` | `{ page?: number; }` | `page` selects a page of results; extract paginates, parse ignores it. | | `options.page?` | `number` | | **Returns** | Type | Description | | --------------- | ------------------------------------------------------------------------------ | | `Promise` | This job, updated, so `while (!(await job.poll()).succeeded)` reads naturally. | #### `ExtractJob.wait()` ```typescript theme={null} wait(options?: { timeoutMs?: number; pollMs?: number; }): Promise ``` Poll until the job is terminal. **Arguments** | Name | Type | Description | | -------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- | | `options?` | `{ timeoutMs?: number; pollMs?: number; }` | `timeoutMs` before giving up (default 300\_000), `pollMs` between polls (default 2000). | | `options.timeoutMs?` | `number` | | | `options.pollMs?` | `number` | | **Returns** | Type | Description | | --------------- | ------------------- | | `Promise` | This job, finished. | **Throws** | Error | When | | -------------- | ----------------------------- | | `Error` | If the timeout elapses first. | | `LightOnError` | If the job ends in failure. | ### BatchIngestJob A running (or finished) batch ingestion. Returned by `Workspace.ingestMany(files, { mode: "async" })`. Uploads (and, when `wait` is set, ingestion polls) run in the background; read `progress`, `succeeded` and `failed` at any time, or block with `wait()`. ```typescript theme={null} new BatchIngestJob(client: Transport, workspaceId: number, files: File[], prefailed: FailedIngest[], options: BatchOptions) ``` | Name | Type | Description | | ------------- | ---------------- | ----------- | | `client` | `Transport` | | | `workspaceId` | `number` | | | `files` | `File[]` | | | `prefailed` | `FailedIngest[]` | | | `options` | `BatchOptions` | | | Field | Type | Description | | ----------- | ------------------------- | ------------------------------------------------------------------ | | `done` | `boolean` | True once every file has reached a terminal state, ok or failed. | | `progress` | `BatchProgress` | A snapshot of the counts, safe to read while the batch runs. | | `succeeded` | `readonly File[]` | Files that have succeeded so far. | | `failed` | `readonly FailedIngest[]` | Failures so far, available mid-run. | | `result` | `BatchIngest` | Current succeeded/failed as a `BatchIngest`; terminal once `done`. | #### `BatchIngestJob.poll()` ```typescript theme={null} poll(): BatchProgress ``` The current progress. The mirror of a parse/extract job's `poll()`, except that nothing needs fetching: the batch is driven from this process, so its state is already current. **Returns** | Type | Description | | --------------- | ----------- | | `BatchProgress` | | #### `BatchIngestJob.wait()` ```typescript theme={null} wait(options?: { timeoutMs?: number; }): Promise ``` Block until the batch finishes, then return its result. **Arguments** | Name | Type | Description | | -------------------- | ------------------------- | ----------------------------------------------------------- | | `options?` | `{ timeoutMs?: number; }` | `timeoutMs` for the whole batch; omit to wait indefinitely. | | `options.timeoutMs?` | `number` | | **Returns** | Type | Description | | ---------------------- | --------------------------- | | `Promise` | The terminal `BatchIngest`. | **Throws** | Error | When | | ------- | ----------------------------------------------------------------------------------------- | | `Error` | If the batch doesn't finish in time. | | `Error` | The first upload or ingestion error, rethrown, when the batch ran without `ignoreErrors`. | ### BatchOptions | Field | Type | Description | | ----------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `ignoreErrors?` | `boolean` | If false (the default), the first failure throws, inline or from `job.wait()`. If true, failures are collected and the batch carries on. | | `wait?` | `boolean` | Wait for each upload's ingestion to finish, not just to be accepted. | | `timeoutMs?` | `number` | Per-file milliseconds to wait for ingestion when `wait` is set. Default 300\_000. | | `pollMs?` | `number` | Milliseconds between ingestion status checks. Default 2000. | | `maxConcurrency?` | `number` | Concurrent uploads and polls. Default 8. | | `tags?` | `number[]` | Tag ids assigned to every uploaded document. | ### BatchIngest The terminal outcome of a batch. | Field | Type | Description | | ----------- | ---------------- | --------------------------- | | `succeeded` | `File[]` | | | `failed` | `FailedIngest[]` | | | `ok` | `boolean` | Whether every item made it. | ### BatchProgress A snapshot of a running batch. | Field | Type | Description | | ---------- | --------- | ------------------------------------------------------------------------ | | `total` | `number` | | | `uploaded` | `number` | Uploads the API has accepted. | | `ingested` | `number` | Files that have finished ingesting. Stays 0 unless the batch is waiting. | | `failed` | `number` | | | `done` | `boolean` | | ### FailedIngest One item of a batch that did not make it. | Field | Type | Description | | -------- | -------- | ------------------------------------------------------------------------ | | `source` | `string` | The path or pattern it came from; empty when the source was a blob. | | `error` | `Error` | Why it failed: the upload error, the ingestion error, or a missing path. | | `file?` | `File` | The File, when the failure was at *ingestion* rather than upload. | ## Streaming events ### AskEvent ```typescript theme={null} type AskEvent = SourcesEvent | TokenEvent | DoneEvent ``` ### SourcesEvent The retrieved chunks, sent once before generation starts. | Field | Type | Description | | --------- | ----------------- | --------------------------------------------------------------- | | `type` | `"sources"` | | | `results` | `AskResultItem[]` | Retrieved chunks used as context, the same items `ask` returns. | ### TokenEvent One chunk of the answer as it generates. | Field | Type | Description | | ------ | --------- | --------------------------------------------- | | `type` | `"token"` | | | `text` | `string` | Answer text to append; may be several tokens. | ### DoneEvent Generation finished; no further events follow. | Field | Type | Description | | ------ | -------- | ----------- | | `type` | `"done"` | | ## Schemas ### `asJsonSchema()` ```typescript theme={null} export declare function asJsonSchema(schema: SchemaInput): Promise ``` Either guided-generation input, as the self-contained schema to send. **Arguments** | Name | Type | Description | | -------- | ------------- | ------------------------------------------------------ | | `schema` | `SchemaInput` | A Zod schema, or a plain object holding a JSON Schema. | **Returns** | Type | Description | | --------------------- | --------------------------------------------------------- | | `Promise` | A self-contained JSON Schema, free of `$defs` and `$ref`. | **Throws** | Error | When | | ----------- | ----------------------- | | `TypeError` | If `schema` is neither. | ### `normalizeJsonSchema()` ```typescript theme={null} export declare function normalizeJsonSchema(schema: JsonSchema): JsonSchema ``` Normalize a JSON Schema into the self-contained shape vLLM wants. `$defs`/`$ref` inlined, nullable `anyOf` collapsed to `type: [X, "null"]`, and the draft-2020-12 `$schema` marker added (an existing one is kept). **Arguments** | Name | Type | Description | | -------- | ------------ | ------------------------------------------------ | | `schema` | `JsonSchema` | A JSON Schema, possibly carrying `$defs`/`$ref`. | **Returns** | Type | Description | | ------------ | ---------------------------------------------------------------- | | `JsonSchema` | An equivalent self-contained schema, free of `$defs` and `$ref`. | **Throws** | Error | When | | ----------- | ---------------------------------- | | `TypeError` | If a `#/$defs/` ref has no target. | ### SchemaInput Either input `ask` and `extract` accept for guided generation. A Zod schema is converted with Zod's own `toJSONSchema`, imported only when one is actually passed, so `zod` stays an optional peer dependency that costs nothing to callers who hand over a plain JSON Schema instead. ```typescript theme={null} type SchemaInput = JsonSchema | StandardSchemaLike ``` ### JsonSchema A JSON Schema, as a plain object. ```typescript theme={null} type JsonSchema = Record ``` ## List filters ### FileFilters Filters for `File.list`, e.g. `status`, `tag_id`, `external_metadata__external_id`. | Field | Type | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `page_size?` | `number` | | | `attribute?` | `string` | | | `content_type?` | `string` | | | `created_at_after?` | `string` | | | `created_at_before?` | `string` | | | `extension?` | `string` | | | `external_metadata__doc_type?` | `string` | | | `external_metadata__external_id?` | `string` | | | `filename?` | `string` | | | `group_id?` | `string` | | | `include_details?` | `boolean` | | | `max_documents?` | `number` | | | `ordering?` | `string` | | | `owner_id?` | `string` | | | `search?` | `string` | | | `search_details?` | `boolean` | | | `search_details_chunks_limit?` | `number` | | | `status?` | `"converting" \| "embedded" \| "embedding" \| "embedding_failed" \| "fail" \| "parsed" \| "parsing" \| "parsing_failed" \| "pending" \| "pending_conversion" \| "updating"` | | | `status_vision?` | `"-" \| "embedded" \| "fail" \| "pending" \| "processing"` | | | `tag_id?` | `string` | | | `title?` | `string` | | | `total_pages_max?` | `number \| null` | | | `total_pages_min?` | `number \| null` | | | `updated_at_after?` | `string` | | | `updated_at_before?` | `string` | | | `upload_session_uuid?` | `string` | | | `workspace_id?` | `string` | | ### WorkspaceFilters Filters for `Workspace.list`, e.g. `name`, `user_role`, `ordering`. | Field | Type | Description | | ------------------------- | ------------------------------------------------------------------------------------- | ----------- | | `page_size?` | `number` | | | `group_id?` | `number` | | | `ordering?` | `"-created_at" \| "-name" \| "-updated_at" \| "created_at" \| "name" \| "updated_at"` | | | `name?` | `string` | | | `datasource_type?` | `"googledrive" \| "servicenow" \| "sharepoint" \| "smb" \| "webscrapper"` | | | `document_upload_method?` | `"manual" \| "synced"` | | | `group_name?` | `string` | | | `user_role?` | `"editor" \| "owner" \| "viewer"` | | | `workspace_type?` | `"personal" \| "public" \| "shared"` | | ### TagFilters Filters for `Tag.list`, e.g. `name`, `auto_assign`. | Field | Type | Description | | -------------- | --------- | ----------- | | `page_size?` | `number` | | | `auto_assign?` | `boolean` | | | `name?` | `string` | | ### ApiKeyFilters Filters for `ApiKey.list`, e.g. `is_expired`. | Field | Type | Description | | ------------- | --------- | ----------- | | `is_expired?` | `boolean` | | | `page_size?` | `number` | | ## Enums ### AttributeType Type of a content-type attribute column. `select` and `multiSelect` require `choices`; the API also accepts the aliases `multiselect` and `richtext` for the hyphenated values used here. | Member | Value | | ------------- | -------------- | | `text` | `text` | | `number` | `number` | | `date` | `date` | | `boolean` | `boolean` | | `select` | `select` | | `multiSelect` | `multi-select` | | `richText` | `rich-text` | ### DownloadPurpose Which stored version of a file to download. The server falls back to `original` when the requested purpose has no associated file. | Member | Value | | ------------- | -------------- | | `original` | `original` | | `renderedPdf` | `rendered_pdf` | | `transcript` | `transcript` | ### ExecMode Execution mode for parse/extract: run inline or queue as an async job. | Member | Value | | ------- | ------- | | `sync` | `sync` | | `async` | `async` | ### FileStatus Ingestion pipeline status for a File. | Member | Value | | ------------------- | -------------------- | | `pending` | `pending` | | `pendingConversion` | `pending_conversion` | | `converting` | `converting` | | `parsing` | `parsing` | | `parsingFailed` | `parsing_failed` | | `embedding` | `embedding` | | `embeddingFailed` | `embedding_failed` | | `embedded` | `embedded` | | `parsed` | `parsed` | | `fail` | `fail` | | `updating` | `updating` | ### JobStatus Status of an async parse/extract job. Only `pending` (initial) and `completed` (success) are documented by the API; the schema types `status` as a bare string with no enum and doesn't publish the failure vocabulary. This is for call-site comparisons, NOT to validate the response field, so an unrecognized server value compares unequal rather than erroring. Detect terminal failure via `completedAt` being set without `completed` (or, for parse, the `error` block) rather than a status string. | Member | Value | | ----------- | ----------- | | `pending` | `pending` | | `completed` | `completed` | ### RelevanceScoring Cross-encoder relevance scoring step for search. | Member | Value | Description | | --------------------- | ----------------------- | ------------------------------------ | | `none` | `none` | Skip scoring, return all candidates. | | `scoringOnly` | `scoring_only` | Score but don't filter. | | `scoringAndFiltering` | `scoring_and_filtering` | Score and drop below threshold. | ### ReprocessLevel Reprocessing level queued on a File (`pendingReprocess`), `update` = replacement. | Member | Value | | --------------- | ---------------- | | `reparse` | `reparse` | | `rechunk` | `rechunk` | | `reembed` | `reembed` | | `reembedVision` | `reembed_vision` | | `update` | `update` | ### Role Access role granted by an API-key scope on a workspace. | Member | Value | | -------- | -------- | | `viewer` | `viewer` | | `editor` | `editor` | | `owner` | `owner` | ### SearchMode Retrieval mode for search and ask. | Member | Value | Description | | -------- | -------- | ------------------------ | | `text` | `text` | Hybrid keyword + vector. | | `vision` | `vision` | VLM-embedded page image. | ### ThumbnailStatus Whether a file's thumbnail has been generated (uppercase, as the API sends). | Member | Value | | ------------ | ------------ | | `MISSING` | `MISSING` | | `PROCESSING` | `PROCESSING` | | `READY` | `READY` | ## Errors Everything the SDK throws derives from `LightOnError`, importable from `@lighton-ai/sdk`. Every method that performs a request can throw these, so they are listed once here rather than repeated on each method. A method's own **Throws** block covers only what it throws directly. | Error | Extends | Thrown when | | ------------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LightOnError` | `Error` | Base class for every error raised by this SDK. | | `LightOnConnectionError` | `LightOnError` | Transport failure before any response was received (DNS, timeout, reset). | | `MalformedResponseError` | `LightOnError` | A 2xx response body was not valid JSON. | | `StreamError` | `LightOnError` | The server sent an `error` event partway through a stream. Not a `LightOnAPIError`: the HTTP response was a perfectly good 200 and the failure happened during generation, so there is no status code to carry. The answer is incomplete, which is why this throws instead of arriving as one more event a caller could mistake for a finished answer. `body` holds the payload. | | `LightOnAPIError` | `LightOnError` | The API returned a non-2xx response. | | `AuthenticationError` | `LightOnAPIError` | 401, bad or missing API key (the request is not authenticated). | | `PermissionDeniedError` | `LightOnAPIError` | 403, authenticated, but the key lacks permission for this operation. Distinct from `AuthenticationError`: the credentials are valid, but the caller isn't allowed (e.g. an endpoint that requires the CompanyAdmin role). | | `NotFoundError` | `LightOnAPIError` | 404, the resource does not exist. | | `RateLimitError` | `LightOnAPIError` | 429, too many requests. `retryAfter` is the seconds to wait before retrying, from the `Retry-After` response header when the server sends it (else null). | | `ServerError` | `LightOnAPIError` | 5xx, the API failed to handle the request. | | `MaintenanceError` | `ServerError` | 503 during a planned maintenance window, not a crash. A `ServerError` subclass, so existing `catch (e) { if (e instanceof ServerError) }` handlers keep working; check for this specifically to tell "come back later" apart from "this broke", since only one of the two is worth retrying. `mode` is `full_shutdown` or `warning_banner` (both block the request), `reason` is operator-supplied text, `startedAt` is when the window opened, and `endpointCategories` names the affected categories, empty meaning every endpoint. The untouched payload is always on `.body`. |