Workspaces

A workspace is a named collection of source files and derived outputs, owned by your organization, pinned to a domain vocabulary and an access-control configuration. All list routes use keyset cursor pagination (cursor / next_cursor).

Create workspace

POST /v1/workspaces

Provision a new workspace. Every field has a default, so a name alone produces a working workspace. The workspace is immediately usable for file uploads and ingestion. Request:

{
  "name": "q4-2025-audit",
  "domain_slug": "audit",
  "domain_version": null,
  "access": {
    "labels": [
      {"name": "financial", "description": "Financial documents."},
      {"name": "confidential", "description": "Restricted documents."}
    ],
    "default_label": "financial"
  },
  "retention_policy": {
    "derived_ttl_days": null,
    "source_ttl_days": null,
    "job_ttl_days": 30
  }
}

Body fields:

name (required, 1–200 chars) — Human-readable workspace name.
domain_slug (optional, default "generic") — Domain vocabulary slug. Resolved to the latest published version unless domain_version is also set.
domain_version (optional) — Pin a specific published domain version. Omit to take the latest.
access (optional) — Access-control configuration:
- labels — List of {name, description} labels. Empty list (the default) disables filtering entirely.
- default_label — Required when labels is non-empty. Applied when the classifier cannot decide. Must name one of the declared labels.
retention_policy (optional):
- derived_ttl_days — Days before derived representations expire (anchored on ingested_at). Null = keep forever.
- source_ttl_days — Days before source bytes are deleted (anchored on created_at). Null = keep forever.
- job_ttl_days (default 30) — Days to retain job input and result payloads. Null = keep forever.
knowledge_graph (optional) — Graph build policy. Editable later via Update workspace.
- auto_build (default false) — Build the graph automatically after each ingestion completes. Off by default because a build is billable and long-running; set true for a workspace that should always hold a graph over what it ingests.
- exclude_path_prefixes / exclude_categories — Files matching either are kept out of the graph corpus, unless the file’s own graph_inclusion is include.

Response (201 Created):

{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440003",
  "name": "q4-2025-audit",
  "domain_id": "550e8400-e29b-41d4-a716-446655440000",
  "domain_slug": "audit",
  "domain_version": 2,
  "access": {"labels": [...], "default_label": "financial"},
  "retention_policy": {"derived_ttl_days": null, "source_ttl_days": null, "job_ttl_days": 30},
  "knowledge_graph": {"auto_build": false, "exclude_path_prefixes": [], "exclude_categories": []},
  "config_version": 1,
  "status": "active",
  "created_at": "2026-08-09T12:00:00Z",
  "updated_at": "2026-08-09T12:00:00Z"
}

Response fields:

workspace_id — UUID for the workspace.
domain_slug / domain_version — The resolved vocabulary this workspace uses.
knowledge_graph.auto_build — Whether ingestion automatically triggers a KG build (default false).
status — active or deleting.

Errors:

domain_not_found (404) — Slug does not match any visible domain.
domain_not_published (409) — The resolved domain version is a draft, not published.
default_label_required (422) — access.labels is non-empty but default_label is missing.

List workspaces

GET /v1/workspaces

Page through the caller’s workspaces, oldest first. Query parameters:

name_contains (optional) — Case-insensitive substring filter on workspace name.
cursor (optional) — Opaque cursor from next_cursor.
limit (optional, default 50, max 200)

Response:

{
  "items": [
    {
      "workspace_id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "q4-2025-audit",
      "domain_slug": "audit",
      "domain_version": 2,
      "status": "active",
      "created_at": "2026-08-09T12:00:00Z",
      "updated_at": "2026-08-09T12:00:00Z"
    }
  ],
  "next_cursor": null,
  "total_count": 1
}

Get workspace

GET /v1/workspaces/{workspace_id}

Retrieve one workspace. Response: Full workspace object (same shape as Create response). Errors:

workspace_not_found (404) — No such workspace for this key. Cross-tenant reads are indistinguishable from missing rows.

Update workspace

PATCH /v1/workspaces/{workspace_id}

Change a workspace’s mutable configuration. Only the knowledge-graph policy is mutable — the name, domain, access labels, and retention policy are fixed at creation, because every derived artifact is stamped with the configuration it was produced under. Omit a block to leave it unchanged. A block you do send replaces its previous value entirely, so read the workspace, edit the block, and send it back — a partial block falls back to the schema defaults and would clear rules you meant to keep. Request:

{
  "knowledge_graph": {
    "auto_build": true,
    "exclude_path_prefixes": ["drafts/"],
    "exclude_categories": []
  }
}

Response (200 OK): Full workspace object (same shape as Create response). Builds are explicit by default: a graph is built when Build knowledge graph asks for one. Setting auto_build to true hands that trigger to ingestion instead, for a workspace that wants a graph over everything it ingests and accepts one build per ingestion. Either way a build already in flight keeps running — cancel its job if that is what you meant. Errors:

workspace_not_found (404) — No such workspace for this key.
workspace_deleting (409) — A teardown is in flight; the workspace accepts no further writes.
invalid_request (422) — An unknown field, such as an attempt to rename the workspace.

Get workspace stats

GET /v1/workspaces/{workspace_id}/stats

Compute workspace content statistics without paging through files. Response:

{
  "files_total": 42,
  "files_by_ingestion_status": {
    "discovered": 2,
    "queued": 0,
    "ingesting": 0,
    "ingested": 38,
    "stale": 1,
    "expired": 1,
    "failed": 0,
    "not_required": 0
  },
  "bytes_total": 524288000,
  "pages_ingested": 4200,
  "index_documents": 4200,
  "kg_nodes": 1247,
  "kg_edges": 3156,
  "last_ingestion_at": "2026-08-09T11:30:00Z",
  "last_reconciliation_at": null,
  "next_expiry_at": null,
  "files_expiring_within_7d": 0
}

stale > 0 means observed and ingested hashes diverged — run an ingestion with selection.stale_only=true to catch up. expired > 0 means derived representations were dropped by retention; re-ingest to make those files searchable again.

Delete workspace

DELETE /v1/workspaces/{workspace_id}

Permanently delete a workspace and all of its content. Irreversible. confirm_name must equal the workspace’s name exactly; this is deliberate friction. The teardown (storage prefix, search index, graph nodes) runs asynchronously — poll the returned job. Request:

{
  "confirm_name": "q4-2025-audit"
}

Response (202 Accepted): A Job with kind: "workspace_delete". Errors:

workspace_deleting (409) — A teardown is already in flight.
invalid_request (422) — confirm_name does not match the workspace name.

Granular operations

Platform resources

Knowledge graph

Tools

Operations

Create workspace

List workspaces

Get workspace

Update workspace

Get workspace stats

Delete workspace

​Create workspace

​List workspaces

​Get workspace

​Update workspace

​Get workspace stats

​Delete workspace

Create workspace

List workspaces

Get workspace

Update workspace

Get workspace stats

Delete workspace