Workspaces
Workspaces
client.workspaces creates, lists, configures and deletes the workspaces that hold your uploaded files. Every method that works on one workspace takes its workspaceId first; one that isn't yours, or was deleted, rejects with NotFoundError, code workspace_not_found. Managing workspaces costs nothing and works at any balance. See Workspaces, and the API reference for every field.
Create a workspace
client.workspaces.create(params, options?) returns APIPromise<Workspace>.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 1 to 120 characters once trimmed. It can't be changed later. Unique in the account, ignoring case: a name in use throws ConflictError. |
domain_slug | string | No | The published domain the workspace sorts its files into: generic, one your account published, or one Nace provides. It pins the newest published version. A slug that names none rejects with UnprocessableEntityError. Can't be changed later. Default: "generic". |
access | WorkspaceAccess | No | Access labels, with the keys below. They can't be changed later. Default: no labels. |
Each object option takes these keys.
| Key | Type | Default | Description |
|---|---|---|---|
access.labels | Array<{ name: string; description: string }> | [] | Up to 16. Ingestion gives each file one label, using its description as the classifier's prompt. Each name is lowercase letters and digits joined by _. [] turns labels off. |
access.default_label | string | null | null | The label a file gets when the classifier can't decide. Required when labels has any, and must be one of them. |
params is a CreateWorkspaceParams. A create isn't idempotent, so it isn't retried unless options.retry asks: a retried create can make a second workspace. See Create a workspace.
const workspace = await client.workspaces.create({
name: "fy25-audit",
});
console.log(workspace.workspace_id);List workspaces
client.workspaces.list(params?, options?) returns APIPromise<WorkspacePage>, one page of the workspaces your key can use, oldest first. params is a WorkspaceListParams; a limit out of range throws a NaceError before sending.
| Parameter | Type | Required | Description |
|---|---|---|---|
name_contains | string | No | Only workspaces whose name contains this, ignoring case. |
limit | number | No | 1 to 200. Default: 50. |
cursor | string | null | No | The previous page's next_cursor. Keep going until it's null. |
const page = await client.workspaces.list({ name_contains: "audit", limit: 20 });
console.log(page.items.map((workspace) => workspace.name), page.total_count);Iterate over workspaces
client.workspaces.iterAll(params?, options?) returns AsyncGenerator<Workspace>, following every page, 200 (MAX_WORKSPACE_PAGE_SIZE) a page.
| Parameter | Type | Required | Description |
|---|---|---|---|
name_contains | string | No | Only workspaces whose name contains this, ignoring case. |
for await (const workspace of client.workspaces.iterAll({ name_contains: "audit" })) {
console.log(workspace.workspace_id, workspace.name);
}Read a workspace
client.workspaces.get(workspaceId, options?) returns APIPromise<Workspace>.
| Parameter | Type | Required | Description |
|---|---|---|---|
workspaceId | string | Yes | The workspace. |
const workspace = await client.workspaces.get(workspaceId);
console.log(workspace.status);Workspace stats
client.workspaces.stats(workspaceId, options?) returns APIPromise<WorkspaceStats>, with file and byte counts, files per ingestion status, and the size of the search index.
| Parameter | Type | Required | Description |
|---|---|---|---|
workspaceId | string | Yes | The workspace. |
const stats = await client.workspaces.stats(workspaceId);
console.log(stats.files_total, stats.files_by_ingestion_status);Delete a workspace
client.workspaces.delete(workspaceId, params, options?) returns APIPromise<DocumentJob | null>, which resolves to the workspace_delete job, or to null when the document service had already let the workspace go and no job is left to read.
| Parameter | Type | Required | Description |
|---|---|---|---|
workspaceId | string | Yes | The workspace. |
params.confirm_name | string | Yes | Exactly the workspace's name. Anything else rejects with UnprocessableEntityError. |
params is a DeleteWorkspaceParams. The delete answers at once, without wait_seconds; follow the job with jobs.wait. It removes every file, output and the search index, and can't be undone. The job's result has files_deleted, index_documents_deleted, prefix_deleted and verified. Only the account's owners and admins, or whoever created the workspace, can delete it; anyone else gets PermissionDeniedError, code access_denied. Once deleted, the workspace answers NotFoundError. See Delete a workspace.
const job = await client.workspaces.delete(workspaceId, { confirm_name: "fy25-audit" });
if (job) await client.jobs.wait(job.job_id);