---
title: "list_workspaces"
method: GET
path: "/v1/workspaces"
tags: ["workspaces"]
---

# list_workspaces

`GET /v1/workspaces`

## Request

- Base URL: `https://ndi-api.nace.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://ndi-api.nace.ai/v1/workspaces`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/nace/apis/ndi-service/docs/v1/workspaces/get.ts> (a function with typed inputs; its response is checked against the schema)

Page through the caller's workspaces, oldest-first. Cost class: fast.

Keyset-paginated on ``(created_at, id)``; the cursor is opaque.

Args:
    session: Database session.
    caller: The authenticated tenant.
    name_contains: Substring filter on the workspace name.
    cursor: Opaque cursor from a previous page's ``next_cursor``.
    limit: Rows per page.

Returns:
    One page of workspaces with an exact total.

## Query parameters

- `name_contains` string, nullable: Case-insensitive name filter.
- `cursor` string, nullable: Opaque cursor from a previous page's `next_cursor`. Omit for the first page.
- `limit` integer: Rows per page.

## Response `200`

Successful Response

- PageWorkspace
  - `items` Workspace[], required: This page's rows, in the list's order.
    - `storage` union: The workspace's durable storage backend and external connection health.
      - ManagedWorkspaceStorage
        - `type` 'managed'
      - TenantBucketWorkspaceStorage
        - `type` 'tenant_bucket'
        - `provider` 's3'
        - `location` string, required: Workspace namespace in the tenant's configured bucket.
      - ExternalWorkspaceStorage
        - `type` 'external'
        - `connection_id` string, uuid, nullable: Reusable storage connection bound permanently to this workspace; each workspace has its own exclusive namespace. Null when the caller cannot view the storage connection.
        - `provider` 's3' | 'azure_blob', nullable: Customer object storage provider. Null when the caller cannot view the storage connection.
        - `location` string, nullable: Exclusive namespace containing this workspace's durable objects. Null when the caller cannot view the storage connection.
        - `health` 'draft' | 'ready' | 'degraded' | 'revoked', nullable: Current connection authorization state. Null when the caller cannot view the storage connection.
    - `workspace_id` string, uuid, required
    - `owner_user_id` string, uuid, nullable, required: The console user who owns the workspace, or null for an organization-owned integration workspace.
    - `share_count` integer, required: Number of users explicitly granted workspace access; excludes the owner.
    - `name` string, required
    - `domain_id` string, uuid, required
    - `domain_slug` string, required
    - `domain_version` integer, required
    - `access` AccessConfig, required: A workspace's access-control setting, chosen once at creation. ``labels = []`` is the default and means **no filtering at all** — no classification pass at ingestion, no filter clause at retrieval, and ``Coverage`` reports nothing. A workspace that does not need document-level access control should not pay for a classification that always returns the same answer. Coverage reporting is always strict: whenever the gate withholds candidates, the response says so in counts and label names. A silently narrowed answer is the failure mode this platform exists to prevent, so there is no opt-out.
      - `labels` AccessLabel[]
        - `name` string, required
        - `description` string, required: This string IS the classifier's prompt.
      - `default_label` string, nullable: Applied when the classifier cannot decide. Required whenever labels is non-empty.
    - `knowledge_graph` KnowledgeGraphConfig, required: A workspace's knowledge-graph build policy. The defaults keep the whole corpus in scope and build the graph after every ingestion, so fact search and deep search have it to navigate by. Set ``auto_build=false`` for a workspace that builds only on request. ``exclude_path_prefixes`` and ``exclude_categories`` are the workspace-wide skip rules a file's ``graph_inclusion`` can override — a file matching either is left out of the graph corpus unless it is explicitly ``include``\ d.
      - `auto_build` boolean: Build the graph automatically after each ingestion completes. On by default; turn it off to build only on request (a build is billable and long-running). Ingestion skips the automatic build once the graph corpus reaches the deployment's kg.auto_build.max_corpus_files limit; an explicit build still runs.
      - `exclude_path_prefixes` string[]: Files whose path starts with any of these are kept out of the graph corpus (override per file).
      - `exclude_categories` string[]: Files whose category is any of these are kept out of the graph corpus (override per file).
    - `currency` CurrencyPolicy, required: How this workspace's documents should be read where they leave a currency open. Extraction never converts an amount and never invents a currency: one whose currency the source does not state is recorded as ``ambiguous`` with no value, so it matches no amount filter. New workspaces default to ``DEFAULT_WORKSPACE_CURRENCY`` (USD), so a corpus that writes every total as a bare ``$900.00`` and names a currency nowhere is filterable out of the box. Set ``default`` to another ISO code to change the reading, or to ``null`` to assume nothing — an amount whose currency the source never states then stays ``ambiguous`` rather than being read as USD.
      - `default` string, nullable: ISO 4217 code, e.g. 'USD'.
    - `ledger_understanding` LedgerUnderstandingConfig: A workspace's ledger-understanding policy. On by default in its cheapest form: ``auto`` costs a workspace with no ledger in it nothing at all, because the test for "is there a ledger here" is the census's own pure predicate over sidecars that ingestion already wrote.
      - `engine` 'measured' | 'llm': Discovery method; selected packages always run measured validation.
      - `package_confirmation` 'required' | 'automatic': Who confirms an llm-discovered package before GL parsing: a person, or the model on its own. When a person must, parsing runs only on the mapping that person confirmed.
      - `package_scope` LedgerPackageScope: A package's source files: every file under the prefix plus every explicit path.
        - `path_prefix` string, nullable: Folder containing the package, relative to the workspace root.
        - `paths` string[]: Exact source paths in the package, added to every path under the prefix.
        - `selection_id` string, uuid, nullable: Protected, immutable source-role selection reference.
      - `trigger` 'auto' | 'always' | 'off': When an ingestion should chain the stage: only for a workspace that holds a journal-line table, after every ingestion that landed files, or never.
      - `gl_parsing` boolean: Whether the stage should also map each journal's account/debit-credit groups to balanced sub-journals and publish the mapping as a derived table.
      - `prepared_relationships` PreparedRelationshipConfig[]: Reviewed large-table relationships to prepare before JET starts. Empty disables preparation.
        - `name` string, required: Stable name for the prepared relationship.
        - `left` PreparedTableSelectionConfig, required: One logical source table selected by its stable workspace coordinate.
          - `path` string, required: Workspace path or published dataset root.
          - `component` string, nullable: Worksheet or component when the path has more than one table.
        - `right` PreparedTableSelectionConfig, required: One logical source table selected by its stable workspace coordinate.
          - `path` string, required: Workspace path or published dataset root.
          - `component` string, nullable: Worksheet or component when the path has more than one table.
        - `keys` PreparedKeyConfig[], required: Ordered equality key components.
          - `left_column` string, required: Column on the left table.
          - `right_column` string, required: Column on the right table.
          - `left_normalization` union: Reviewed normalization applied to the left column.
            - PreparedIdentityNormalizationConfig: Compare a VARCHAR key exactly as stored.
              - …
            - PreparedLeftPadNormalizationConfig: Apply the declared single-character left padding before comparison.
              - …
          - `right_normalization` union: Reviewed normalization applied to the right column.
            - PreparedIdentityNormalizationConfig: Compare a VARCHAR key exactly as stored.
              - …
            - PreparedLeftPadNormalizationConfig: Apply the declared single-character left padding before comparison.
              - …
        - `bucket_count` integer, required: Number of hash buckets materialized on each side.
    - `global_context` string: Standing background for every query in this workspace — how its journals are keyed, which entity it covers, what an auditor already knows. A je-testing or search request that omits `context` runs with this text; a request that sends `context` replaces it for that run, and `""` runs with none. Empty means none. Surrounding whitespace is stripped.
    - `config_version` integer, required
    - `status` 'active' | 'deleting', required: Lifecycle states visible on the API surface. ``deleted`` is a final internal state; a deleted workspace never appears in any list or ``get`` response — it is as if it never existed.
    - `purpose` 'perception_playground': Why the platform provisioned a workspace nobody asked for. A purposed workspace is platform-managed: it is created on a person's behalf and it refuses deletion, so a caller can tell from a list response which row will answer 409 rather than discovering it by trying.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `next_cursor` string, nullable: Opaque; null means the last page.
  - `total_count` integer, required: Exact, and filtered by the caller's access predicate.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `410`: Gone
- `413`: Request Entity Too Large
- `422`: Unprocessable Entity
- `424`: Failed Dependency
- `429`: Too Many Requests
- `500`: Internal Server Error
- `501`: Not Implemented
- `503`: Service Unavailable
- `504`: Gateway Timeout

---

[API](https://skmtc.dev/nace/apis/ndi-service.md) - [All operations](https://skmtc.dev/nace/apis/ndi-service/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/ndi-service/revisions/d9d1f8ec2207?raw)