TypeScript SDK reference - LightOn Developers

Generated from @lighton-ai/sdk 1.0.0. Install it and see runnable examples in the quick start.

Client

LightOn

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()`

ask(query: string, options?: AskOptions & {
  stream?: false;
}): Promise<AskResponse>
ask(query: string, options: AskOptions & {
  stream: true;
}): AsyncGenerator<AskEvent, void, undefined>

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<AskResponse> \| AsyncGenerator<AskEvent, void, undefined>`

`LightOn.close()`

close(): void

Abort every in-flight request. The client is not reusable afterwards.

`LightOn.extract()`

extract(schema: SchemaInput, options: ExtractOptions & {
  mode?: "sync";
}): Promise<ExtractJobResponse>
extract(schema: SchemaInput, options: ExtractAsyncOptions): Promise<ExtractJob>

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<string, unknown>`	Free-form request options, merged into the body.
`options.signal?`	`AbortSignal`	Caller cancellation.
`options.mode?`	`"sync"`

Returns

Type	Description
`Promise<ExtractJobResponse> \| Promise<ExtractJob>`

`LightOn.parse()`

parse(options: ParseOptions & {
  mode?: "sync";
}): Promise<ParseResponse>
parse(options: ParseAsyncOptions): Promise<ParseJob>

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<ParseResponse> \| Promise<ParseJob>`

`LightOn.search()`

search(query: string, options?: SearchOptions): Promise<SearchResponse>

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<SearchResponse>`

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

const DEFAULT_BASE_URL: "https://api.lighton.ai"

Client configuration.

VERSION

const VERSION: string

Workspaces & files

Workspace

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()`

static get(client: Transport, id: number | string): Promise<Workspace>

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<Workspace>`	The workspace, bound to `client`.

`Workspace.list()`

static list(client: Transport, options?: WorkspaceListOptions): Promise<Workspace[]>

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<Workspace[]>`	Every matching workspace, bound to `client`.

`Workspace.create()`

create(client: Transport): Promise<this & {
  id: number;
}>

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 & { id: number; }>`	`this`, updated with the server-assigned id and read-only fields.

`Workspace.delete()`

delete(): Promise<void>

Delete this resource and clear its local id. Returns

Type	Description
`Promise<void>`

`Workspace.ingest()`

ingest(file: File, options?: IngestOptions): Promise<File & {
  id: number;
}>

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<File & { id: number; }>`	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()`

ingestMany(files: readonly (File | string)[], options?: BatchOptions & {
  mode?: typeof ExecMode.sync;
}): Promise<BatchIngest>
ingestMany(files: readonly (File | string)[], options: BatchOptions & {
  mode: typeof ExecMode.async;
}): Promise<BatchIngestJob>

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<BatchIngest> \| Promise<BatchIngestJob>`	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()`

refresh(): Promise<this>

Re-fetch this resource from the API. Returns

Type	Description
`Promise<this>`	`this`, updated with the latest field values.

`Workspace.save()`

save(): Promise<this>

Persist local edits to name and description. Returns

Type	Description
`Promise<this>`	`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

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()`

static deleteMany(client: Transport, files: readonly (File | number)[]): Promise<void>

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<void>`

Throws

Error	When
`NotFoundError`	If any id is unknown; no file is deleted in that case.

`File.get()`

static get(client: Transport, id: number | string): Promise<File>

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<File>`	The file, bound to `client`.

`File.getByName()`

static getByName(client: Transport, name: string, workspace: IdRef): Promise<File[]>

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<File[]>`	Every File with that title; empty if none match.

Throws

Error	When
`Error`	If the workspace has not been created or retrieved.

`File.list()`

static list(client: Transport, options?: FileListOptions): Promise<File[]>

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<File[]>`	Every matching file.

`File.classify()`

classify(contentType: PathRef): Promise<this>

Assign a content type to this file. Arguments

Name	Type	Description
`contentType`	`PathRef`

Returns

Type	Description
`Promise<this>`

`File.clearAttribute()`

clearAttribute(contentType: PathRef, name: string): Promise<this>

Clear an attribute value under an assigned content type. Arguments

Name	Type	Description
`contentType`	`PathRef`
`name`	`string`

Returns

Type	Description
`Promise<this>`

`File.create()`

create(client: Transport, options?: CreateOptions): Promise<this & {
  id: number;
}>

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 & { id: number; }>`	`this`, updated with the server-assigned id and initial status.

Throws

Error	When
`Error`	If no source or no `workspaceId` is set.

`File.delete()`

delete(): Promise<void>

Delete this resource and clear its local id. Returns

Type	Description
`Promise<void>`

`File.download()`

download(purpose?: DownloadPurpose | string): Promise<Uint8Array>

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<Uint8Array>`	The file content.

`File.downloadThumbnail()`

downloadThumbnail(): Promise<Uint8Array>

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<Uint8Array>`	The WebP image.

Throws

Error	When
`NotFoundError`	If no thumbnail exists (status is not `READY`).

facets(): Promise<Facet[]>

List this file’s assigned content types and their attribute values. Returns

Type	Description
`Promise<Facet[]>`

`File.pages()`

pages(): Promise<Page[]>

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<Page[]>`	One Page per page. Empty if the document has no stored text.

`File.refresh()`

refresh(): Promise<this>

Re-fetch this resource from the API. Returns

Type	Description
`Promise<this>`	`this`, updated with the latest field values.

`File.replace()`

replace(source: string | Blob | {
  filename: string;
  blob: Blob;
}, options?: WaitOptions & {
  wait?: boolean;
}): Promise<this>

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>`	`this`. Without `wait`, the absorbed fields still describe the previous content, see `pendingReprocess`.

`File.save()`

save(options?: SaveOptions): Promise<this>

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>`	`this`, refreshed with the server’s response, so `externalMetadata` shows the merged result rather than the partial value you sent.

`File.setAttribute()`

setAttribute(contentType: PathRef, name: string, value: unknown): Promise<this>

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<this>`

`File.tag()`

tag(tags: readonly TagRef[]): Promise<this>

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>`	`this`, refreshed from the response.

`File.unclassify()`

unclassify(contentType: PathRef): Promise<this>

Remove a content-type assignment from this file. Arguments

Name	Type	Description
`contentType`	`PathRef`

Returns

Type	Description
`Promise<this>`

`File.untag()`

untag(tags: readonly TagRef[]): Promise<this>

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>`	`this`.

`File.wait()`

wait(options?: WaitOptions): Promise<this>

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>`	`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.

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.

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()`

export declare function waitAll(files: readonly File[], options?: WaitOptions): Promise<File[]>

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<File[]>`	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

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()`

static get(): Promise<never>

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<never>`

Throws

Error	When
`Error`	Always.

static list(client: Transport, options?: TagListOptions): Promise<Tag[]>

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<Tag[]>`	Every matching tag, bound to `client`.

`Tag.create()`

create(client: Transport): Promise<this & {
  id: number;
}>

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 & { id: number; }>`	`this`, updated with the server-assigned id.

`Tag.delete()`

delete(): Promise<void>

Delete this resource and clear its local id. Returns

Type	Description
`Promise<void>`

`Tag.refresh()`

refresh(): Promise<never>

Re-fetch this resource from the API. Returns

Type	Description
`Promise<never>`

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.

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()`

adopt(client: Transport, paths: readonly string[]): Promise<ContentType[]>

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<ContentType[]>`	The imported top-level nodes.

`ContentType.batch()`

batch(client: Transport, actions: readonly Record<string, unknown>[]): Promise<BatchActionResult[]>

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:

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<string, unknown>[]`	The action bodies, in order.

Returns

Type	Description
`Promise<BatchActionResult[]>`	One result per action, in the same order.

`ContentType.define()`

define(client: Transport, code: string, label: string, options?: DefineOptions): Promise<ContentType>

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<ContentType>`	The created (or updated) node.

`ContentType.defineAttribute()`

defineAttribute(client: Transport, contentType: PathRef, name: string, attributeType: AttributeType | string, options?: DefineAttributeOptions): Promise<Attribute>

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<Attribute>`	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()`

list(client: Transport, options?: ContentTypeListOptions): Promise<ContentType[]>

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<ContentType[]>`	The top-level content-type nodes.

`ContentType.templates()`

templates(client: Transport): Promise<Template[]>

List the starter taxonomies you can ContentType.adopt. Arguments

Name	Type	Description
`client`	`Transport`	The client to query with.

Returns

Type	Description
`Promise<Template[]>`	The template root nodes, each with its `children` and an `attributes` map covering the whole subtree.

`ContentType.undefine()`

undefine(client: Transport, contentType: PathRef): Promise<void>

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<void>`

`ContentType.undefineAttribute()`

undefineAttribute(client: Transport, contentType: PathRef, name: string): Promise<void>

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<void>`

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<string, Attribute[]>`	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`

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

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()`

static get(client: Transport, id: string): Promise<ApiKey>

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<ApiKey>`	The key, bound to `client`.

`ApiKey.list()`

static list(client: Transport, options?: ApiKeyListOptions): Promise<ApiKey[]>

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<ApiKey[]>`	Every matching API key, bound to `client`.

`ApiKey.create()`

create(client: Transport): Promise<this & {
  id: string;
}>

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 & { id: string; }>`	`this`, updated with the id and the one-time plaintext `key`.

`ApiKey.delete()`

delete(): Promise<void>

Delete this resource and clear its local id. Returns

Type	Description
`Promise<void>`

`ApiKey.refresh()`

refresh(): Promise<this>

Re-fetch this resource from the API. Returns

Type	Description
`Promise<this>`	`this`, updated with the latest field values.

`ApiKey.save()`

save(): Promise<this>

Persist local edits to name and scopes. Returns

Type	Description
`Promise<this>`	`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<string, unknown>`	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<string, unknown>`	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.

new Jobprotected constructor(transport: Transport, path: string, data: Record<string, unknown>)

Name	Type	Description
`transport`	`Transport`
`path`	`string`
`data`	`Record<string, unknown>`

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()`

poll(options?: {
  page?: number;
}): Promise<this>

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>`	This job, updated, so `while (!(await job.poll()).succeeded)` reads naturally.

`Job.wait()`

wait(options?: {
  timeoutMs?: number;
  pollMs?: number;
}): Promise<this>

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>`	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()`

poll(options?: {
  page?: number;
}): Promise<this>

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>`	This job, updated, so `while (!(await job.poll()).succeeded)` reads naturally.

`ParseJob.wait()`

wait(options?: {
  timeoutMs?: number;
  pollMs?: number;
}): Promise<this>

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>`	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()`

poll(options?: {
  page?: number;
}): Promise<this>

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>`	This job, updated, so `while (!(await job.poll()).succeeded)` reads naturally.

`ExtractJob.wait()`

wait(options?: {
  timeoutMs?: number;
  pollMs?: number;
}): Promise<this>

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>`	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().

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()`

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()`

wait(options?: {
  timeoutMs?: number;
}): Promise<BatchIngest>

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<BatchIngest>`	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

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()`

export declare function asJsonSchema(schema: SchemaInput): Promise<JsonSchema>

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<JsonSchema>`	A self-contained JSON Schema, free of `$defs` and `$ref`.

Throws

Error	When
`TypeError`	If `schema` is neither.

`normalizeJsonSchema()`

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.

type SchemaInput = JsonSchema | StandardSchemaLike

JsonSchema

A JSON Schema, as a plain object.

type JsonSchema = Record<string, unknown>

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`.

​Client

​LightOn

​LightOn.ask()

​LightOn.close()

​LightOn.extract()

​LightOn.parse()

​LightOn.search()

​LightOnConfiguration

​DEFAULT_BASE_URL

​VERSION

​Workspaces & files

​Workspace

​Workspace.get()

​Workspace.list()

​Workspace.create()

​Workspace.delete()

​Workspace.ingest()

​Workspace.ingestMany()

​Workspace.refresh()

​Workspace.save()

​WorkspaceInit

​WorkspaceListOptions

​IngestOptions

​WorkspaceTaxonomy

​RootContentType

​WorkspaceSync

​File

​File.deleteMany()

​File.get()

​File.getByName()

​File.list()

​File.classify()

​File.clearAttribute()

​File.create()

​File.delete()

​File.download()

​File.downloadThumbnail()

​File.facets()

​File.pages()

​File.refresh()

​File.replace()

​File.save()

​File.setAttribute()

​File.tag()

​File.unclassify()

​File.untag()

​File.wait()

​LightOnFile

​FileInit

​FileListOptions

​CreateOptions

​SaveOptions

​WaitOptions

​FileSource

​ExternalMetadata

​Thumbnail

​Page

​waitAll()

​Tags & content types

​Tag

​Tag.get()

​Tag.list()

​Tag.create()

​Tag.delete()

​Tag.refresh()

​TagInit

​TagListOptions

​TagRef

​ContentType

​ContentType.adopt()

​ContentType.batch()

​ContentType.define()

​ContentType.defineAttribute()

​ContentType.list()

​ContentType.templates()

​ContentType.undefine()

​ContentType.undefineAttribute()

​ContentTypeListOptions

​DefineOptions

​DefineAttributeOptions

Client

LightOn

`LightOn.ask()`

`LightOn.close()`

`LightOn.extract()`

`LightOn.parse()`

`LightOn.search()`

LightOnConfiguration

DEFAULT_BASE_URL

VERSION

Workspaces & files

Workspace

`Workspace.get()`

`Workspace.list()`

`Workspace.create()`

`Workspace.delete()`

`Workspace.ingest()`

`Workspace.ingestMany()`

`Workspace.refresh()`

`Workspace.save()`

WorkspaceInit

WorkspaceListOptions

IngestOptions

WorkspaceTaxonomy

RootContentType

WorkspaceSync

File

`File.deleteMany()`

`File.get()`

`File.getByName()`

`File.list()`

`File.classify()`

`File.clearAttribute()`

`File.create()`

`File.delete()`

`File.download()`

`File.downloadThumbnail()`

`File.facets()`

`File.pages()`

`File.refresh()`

`File.replace()`

`File.save()`

`File.setAttribute()`

`File.tag()`

`File.unclassify()`

`File.untag()`

`File.wait()`

LightOnFile

FileInit

FileListOptions

CreateOptions

SaveOptions

WaitOptions

FileSource

ExternalMetadata

Thumbnail

Page

`waitAll()`

Tags & content types

Tag

`Tag.get()`

`Tag.list()`

`Tag.create()`

`Tag.delete()`

`Tag.refresh()`

TagInit

TagListOptions

TagRef

ContentType

`ContentType.adopt()`

`ContentType.batch()`

`ContentType.define()`

`ContentType.defineAttribute()`

`ContentType.list()`

`ContentType.templates()`

`ContentType.undefine()`

`ContentType.undefineAttribute()`

ContentTypeListOptions

DefineOptions

DefineAttributeOptions