---
title: "get_workspace"
method: GET
path: "/v1/workspaces/{workspace_id}"
tags: ["workspaces"]
---

# get_workspace

`GET /v1/workspaces/{workspace_id}`

## Request

- Base URL: `https://ndi-api.nace.ai`
- URL: `https://ndi-api.nace.ai/v1/workspaces/{workspace_id}`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/nace/apis/ndi-platform-api/docs/v1/workspaces/:workspace_id/get.ts> (a function with typed inputs; its response is checked against the schema)

Read one workspace. Cost class: fast.

## Path parameters

- `workspace_id` string, uuid, required: Workspace identifier.

## Response `200`

Successful Response

- Workspace: A provisioned workspace, as the API returns it. Storage metadata identifies the durable backend without exposing credentials.
  - `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.
    - `default_label` string, nullable: Applied when the classifier cannot decide. Required whenever labels is non-empty.
    - `labels` AccessLabel[]
      - `description` string, required: This string IS the classifier's prompt.
      - `name` string, required
  - `config_version` integer, required
  - `created_at` string, date-time, required
  - `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'.
  - `domain_id` string, uuid, required
  - `domain_slug` string, required
  - `domain_version` integer, required
  - `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.
  - `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_categories` string[]: Files whose category is any of these are kept out of the graph corpus (override per file).
    - `exclude_path_prefixes` string[]: Files whose path starts with any of these are kept out of the graph corpus (override per file).
  - `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.
    - `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.
    - `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.
    - `prepared_relationships` PreparedRelationshipConfig[]: Reviewed large-table relationships to prepare before JET starts. Empty disables preparation.
      - `bucket_count` integer, required: Number of hash buckets materialized on each side.
      - `keys` PreparedKeyConfig[], required: Ordered equality key components.
        - `left_column` string, required: Column on the left table.
        - `left_normalization` union: Reviewed normalization applied to the left column.
          - PreparedIdentityNormalizationConfig: Compare a VARCHAR key exactly as stored.
            - `kind` 'identity': Keep the stored text unchanged.
          - PreparedLeftPadNormalizationConfig: Apply the declared single-character left padding before comparison.
            - `fill` string, required: Single character used for padding.
            - `kind` 'left_pad': Left-pad the stored text to a fixed width.
            - `width` integer, required: Width of the normalized key.
        - `right_column` string, required: Column on the right table.
        - `right_normalization` union: Reviewed normalization applied to the right column.
          - PreparedIdentityNormalizationConfig: Compare a VARCHAR key exactly as stored.
            - `kind` 'identity': Keep the stored text unchanged.
          - PreparedLeftPadNormalizationConfig: Apply the declared single-character left padding before comparison.
            - `fill` string, required: Single character used for padding.
            - `kind` 'left_pad': Left-pad the stored text to a fixed width.
            - `width` integer, required: Width of the normalized key.
      - `left` PreparedTableSelectionConfig, required: One logical source table selected by its stable workspace coordinate.
        - `component` string, nullable: Worksheet or component when the path has more than one table.
        - `path` string, required: Workspace path or published dataset root.
      - `name` string, required: Stable name for the prepared relationship.
      - `right` PreparedTableSelectionConfig, required: One logical source table selected by its stable workspace coordinate.
        - `component` string, nullable: Worksheet or component when the path has more than one table.
        - `path` string, required: Workspace path or published dataset root.
    - `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.
  - `name` string, required
  - `owner_user_id` string, uuid, nullable, required: The console user who owns the workspace, or null for an organization-owned integration workspace.
  - `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.
  - `share_count` integer, required: Number of users explicitly granted workspace access; excludes the owner.
  - `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.
  - `storage` union: The workspace's durable storage backend and external connection health.
    - ManagedWorkspaceStorage
      - `type` 'managed'
    - TenantBucketWorkspaceStorage
      - `location` string, required: Workspace namespace in the tenant's configured bucket.
      - `provider` 's3'
      - `type` 'tenant_bucket'
    - ExternalWorkspaceStorage
      - `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.
      - `health` 'draft' | 'ready' | 'degraded' | 'revoked', nullable: Current connection authorization state. 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.
      - `provider` 's3' | 'azure_blob', nullable: Customer object storage provider. Null when the caller cannot view the storage connection.
      - `type` 'external'
  - `updated_at` string, date-time, required
  - `workspace_id` string, uuid, required

## Other responses

- `504`: Gateway Timeout
- `default`: Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code.

---

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