> ## Documentation Index > Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt > Use this file to discover all available pages before exploring further. # get_workspace > Read one workspace. Cost class: fast. ## OpenAPI ````yaml /openapi.json get /v1/workspaces/{workspace_id} openapi: 3.1.0 info: description: >- Document intelligence: parse, split, classify, extract, and ground files, or build a searchable workspace. Authenticate with ``X-API-Key``. title: NDI Platform API version: 0.1.0 servers: - url: https://ndi-api.nace.ai security: [] tags: [] paths: /v1/workspaces/{workspace_id}: get: tags: - workspaces summary: get_workspace description: 'Read one workspace. Cost class: fast.' operationId: get_workspace_v1_workspaces__workspace_id__get parameters: - description: Workspace identifier. in: path name: workspace_id required: true schema: description: Workspace identifier. format: uuid title: Workspace Id type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Workspace' description: Successful Response '504': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Gateway Timeout default: content: application/json: example: error: code: invalid_request detail: null message: >- Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false schema: $ref: '#/components/schemas/ErrorEnvelope' description: >- Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code. security: - APIKeyHeader: [] components: schemas: Workspace: additionalProperties: false description: >- A provisioned workspace, as the API returns it. Storage is provisioned for the caller and is not part of the wire contract: the root URI is an internal detail until customer-owned roots are exposed. properties: access: $ref: '#/components/schemas/AccessConfig' config_version: title: Config Version type: integer created_at: format: date-time title: Created At type: string currency: $ref: '#/components/schemas/CurrencyPolicy' domain_id: format: uuid title: Domain Id type: string domain_slug: title: Domain Slug type: string domain_version: title: Domain Version type: integer knowledge_graph: $ref: '#/components/schemas/KnowledgeGraphConfig' name: title: Name type: string purpose: anyOf: - $ref: '#/components/schemas/WorkspacePurpose' - type: 'null' description: >- Set when the platform provisioned this workspace on a person's behalf rather than at a caller's request. Such a workspace cannot be deleted. Null for every workspace created through this API. retention_policy: $ref: '#/components/schemas/RetentionPolicy' status: $ref: '#/components/schemas/WorkspaceStatus' updated_at: format: date-time title: Updated At type: string workspace_id: format: uuid title: Workspace Id type: string required: - workspace_id - name - domain_id - domain_slug - domain_version - access - retention_policy - knowledge_graph - currency - config_version - status - created_at - updated_at title: Workspace type: object ErrorEnvelope: description: Every non-2xx body on ``/v1``. example: error: code: invalid_request detail: null message: Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false properties: error: $ref: '#/components/schemas/Error' required: - error title: ErrorEnvelope type: object AccessConfig: additionalProperties: false description: >- 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. properties: default_label: anyOf: - type: string - type: 'null' description: >- Applied when the classifier cannot decide. Required whenever labels is non-empty. title: Default Label labels: items: $ref: '#/components/schemas/AccessLabel' maxItems: 16 title: Labels type: array title: AccessConfig type: object CurrencyPolicy: additionalProperties: false description: >- 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. properties: default: anyOf: - description: ISO 4217 code, e.g. 'USD'. pattern: ^[A-Z]{3}$ type: string - type: 'null' default: USD description: >- Which currency to read when a document marks an amount with a symbol that names several currencies ($ for USD/CAD/AUD/…, ¥ for JPY/CNY, kr for SEK/NOK/…) and states no ISO code anywhere. Defaults to 'USD'; set another ISO code to change it, or null to leave such an amount ambiguous (and so unfilterable). A resolved amount is recorded with 'currency_source: assumed' in the file's metadata so the assumption stays visible. It only ever disambiguates, never invents: an amount written '€900' is still EUR, a '$900' amount in a EUR-default workspace stays ambiguous (a dollar sign is not a way of writing euros), and an amount carrying no currency marker at all is never given one. title: Default title: CurrencyPolicy type: object KnowledgeGraphConfig: additionalProperties: false description: >- A workspace's knowledge-graph build policy. The defaults keep the whole corpus in scope but build nothing until asked: a graph is billable and runs for as long as the corpus takes, so it is not something ingestion should commit a caller to as a side effect. Set ``auto_build=true`` for a workspace that does want one after every ingestion. ``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. properties: auto_build: default: false description: >- Build the graph automatically after each ingestion completes. Off by default: a build is billable and long-running, so it is requested rather than implied. title: Auto Build type: boolean exclude_categories: description: >- Files whose category is any of these are kept out of the graph corpus (override per file). items: maxLength: 1024 type: string maxItems: 128 title: Exclude Categories type: array exclude_path_prefixes: description: >- Files whose path starts with any of these are kept out of the graph corpus (override per file). items: maxLength: 1024 type: string maxItems: 128 title: Exclude Path Prefixes type: array title: KnowledgeGraphConfig type: object WorkspacePurpose: description: >- 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. enum: - perception_playground title: WorkspacePurpose type: string RetentionPolicy: additionalProperties: false description: >- A workspace's retention setting, chosen once at creation. ``derived_ttl_days`` anchors on ``ingested_at`` and ``source_ttl_days`` on ``created_at`` — one anchor each, not configurable. properties: derived_ttl_days: anyOf: - minimum: 1 type: integer - type: 'null' description: >- Expire representations; source bytes untouched. The file moves to ingestion_status=expired. title: Derived Ttl Days job_ttl_days: anyOf: - minimum: 1 type: integer - type: 'null' default: 30 description: >- How long job input and result payloads are retained. Null means kept forever. title: Job Ttl Days source_ttl_days: anyOf: - minimum: 1 type: integer - type: 'null' description: Delete source bytes from platform-managed storage. title: Source Ttl Days title: RetentionPolicy type: object WorkspaceStatus: description: >- 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. enum: - active - deleting title: WorkspaceStatus type: string Error: description: The error object, per spec 12 §1.8. properties: code: $ref: '#/components/schemas/ErrorCode' detail: anyOf: - additionalProperties: true type: object - type: 'null' description: Structured payload, when the code carries one. title: Detail message: description: Human- and model-readable; says what to do differently. title: Message type: string request_id: description: Per-request correlation id; matches the ``X-Request-Id`` header. title: Request Id type: string retryable: description: Whether retrying the identical request could succeed. title: Retryable type: boolean required: - code - message - retryable - request_id title: Error type: object AccessLabel: additionalProperties: false description: One label in a workspace's unordered list. properties: description: description: This string IS the classifier's prompt. title: Description type: string name: maxLength: 64 pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$ title: Name type: string required: - name - description title: AccessLabel type: object ErrorCode: description: |- Every error the ``/v1`` surface can return. Clients must treat this as an **open** enum: a new member is an additive change (spec 12 §9), and a client that crashes on an unknown code makes every future error a breaking change. enum: - invalid_request - unsupported_file_type - file_too_large - invalid_schema - invalid_sql - invalid_path_prefix - command_not_permitted - batch_too_large - domain_validation_failed - default_label_required - wait_required_for_zero_retention - workspace_not_found - file_not_found - job_not_found - upload_not_found - node_not_found - schema_not_found - domain_not_found - session_not_found - access_label_not_found - path_conflict - schema_version_conflict - access_label_name_taken - workspace_name_taken - access_label_in_use - upload_expired - file_not_ingested - workspace_deleting - workspace_not_deletable - ingestion_in_progress - job_not_cancellable - confirmation_required - domain_not_published - domain_in_use - reserved_domain_slug - kg_not_built - kg_build_in_progress - session_busy - range_not_satisfiable - result_expired - access_denied - access_backstop_violation - access_mode_not_implemented - rate_limited - concurrency_limit_reached - quota_exceeded - corrupt_file - zero_byte_file - encrypted_file - parse_failed - ocr_failed - conversion_failed - sheetless_workbook - unplayable_media - unclassified_pages - job_cancelled - job_timeout - upstream_unavailable - internal_error - unauthorized - not_implemented title: ErrorCode type: string securitySchemes: APIKeyHeader: in: header name: X-API-Key type: apiKey ````