Workspace files

client.workspaces.files lists, reads, replaces and deletes the files you uploaded to a workspace. To make them searchable, use client.workspaces.ingest.

• Arguments: every method takes the workspaceId first, and the file methods take the fileId next.
• A missing file: one that doesn't exist, or was deleted, rejects with NotFoundError, code file_not_found.
• Cost: listing, reading, replacing and deleting files is free, at any balance.

See List workspace files in the API reference.

List workspace filesCopy Anchor Link

client.workspaces.files.list(workspaceId, params?, options?) returns APIPromise<WorkspaceFilePage>. params is a WorkspaceFileListParams; each list filter is sent once per value.

const page = await client.workspaces.files.list(workspaceId, {
  path_prefix: "reports/",
  ingestion_status: ["stale"],
});
for (const file of page.items) console.log(file.path, file.ingestion_status);

Read a workspace fileCopy Anchor Link

client.workspaces.files.get(workspaceId, fileId, options?) returns APIPromise<WorkspaceFileDetail>, the file with download_url and preview_url, links to its bytes that work without your API key for 15 minutes.

const file = await client.workspaces.files.get(workspaceId, fileId);
console.log(file.path, file.download_url);

File metadataCopy Anchor Link

client.workspaces.files.metadata(workspaceId, fileId, options?) returns APIPromise<WorkspaceFileMetadata>, what ingestion learned about the file, its outputs, and whether each representations entry is current. Most of it is empty until the file is ingested. See File metadata.

const metadata = await client.workspaces.files.metadata(workspaceId, fileId);
console.log(metadata.lane, metadata.representations, metadata.outputs?.length);

File versionsCopy Anchor Link

client.workspaces.files.versions(workspaceId, fileId, params?, options?) returns APIPromise<WorkspaceFileVersionPage>, the file's versions, newest first. Only the current version's bytes are kept. params is a WorkspaceFileVersionListParams.

const { items } = await client.workspaces.files.versions(workspaceId, fileId);
for (const version of items) console.log(version.version, version.size_bytes, version.is_current);

Replace a workspace fileCopy Anchor Link

client.workspaces.files.replace(workspaceId, fileId, content, params?, options?) returns APIPromise<DocumentJob>, a job that has already succeeded, with result.file and result.previous_version.

params is a ReplaceWorkspaceFileParams. The bytes go through Drex, so a replace takes about 4.5 MB at most; to replace a larger file, upload it to the same path with on_conflict: "new_version" instead. Sending the same bytes and labels again changes nothing. An ingested file becomes stale until you ingest it again. See Replace a file.

import { readFile } from "node:fs/promises";

const job = await client.workspaces.files.replace(workspaceId, fileId, await readFile("report-v2.pdf"));

Delete a workspace fileCopy Anchor Link

client.workspaces.files.delete(workspaceId, fileId, params?, options?) returns APIPromise<DocumentJob>, a file_delete job. It removes the file, its outputs and its search-index entries, cancels ingestions still running on it, and can't be undone.

params is a DeleteWorkspaceFileParams.

const done = await client.jobs.wait((await client.workspaces.files.delete(workspaceId, fileId)).job_id);

Read an outputCopy Anchor Link

client.workspaces.files.output(workspaceId, fileId, outputId, options?) returns APIPromise<WorkspaceFileOutput>, with links to the output's bytes. See Read an output.

const output = await client.workspaces.files.output(workspaceId, fileId, outputId);
console.log(output.path, output.download_url);

List output membersCopy Anchor Link

client.workspaces.files.outputMembers(workspaceId, fileId, outputId, params?, options?) returns APIPromise<WorkspaceFileOutputMembers>, one page of the files inside a folder output, such as a recording's frames, with links to each. A single-file output has no members.

params is an OutputMembersParams.

const { members, total_count } = await client.workspaces.files.outputMembers(workspaceId, fileId, outputId, { limit: 100 });

Ingest filesCopy Anchor Link

client.workspaces.ingest(workspaceId, params?, options?) returns APIPromise<DocumentJob>, an ingestion job. Ingestion builds the search index, metadata and outputs, and is the only call that makes files searchable. One bad file doesn't fail the run: the result's outcomes reports each file. See Ingest files.

params is an IngestParams. file_ids with path_prefix or stale_only throws a NaceError before sending.

const job = await client.workspaces.ingest(workspaceId, { path_prefix: "reports/", stale_only: true });
const done = await client.jobs.wait(job.job_id);