---
title: "Get a workspace"
method: GET
path: "/v1/workspaces/{id}"
tags: ["Workspaces"]
---

# Get a workspace

`GET /v1/workspaces/{id}`

## Request

- Base URL: `https://console.nace.ai`
- URL: `https://console.nace.ai/v1/workspaces/{id}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nace/apis/drex-api/docs/v1/workspaces/:id/get.ts> (a function with typed inputs; its response is checked against the schema)

Free.

## Path parameters

- `id` string, required

## Response `200`

The workspace.

- Workspace
  - `workspace_id` string, required: The id every workspace route takes, and the `workspace_id` of its files' `workspace_file` sources.
  - `name` string, required: The workspace's current display name. Rename it with a name-only PATCH /v1/workspaces/{id}; its workspace_id stays the same.
  - `owner_user_id` string, nullable: The account member who created it.
  - `access` WorkspaceAccess: Access labels. Set at creation; they can't change later.
    - `labels` AccessLabel[]: Up to 16. Ingestion gives each file one label. Default `[]`, labels off.
      - `name` string, required: Lowercase letters and digits joined by `_`.
      - `description` string, required: Written for the classifier: ingestion gives each file the label whose description fits it.
    - `default_label` string, nullable: The label a file gets when the classifier can't decide. Required when `labels` has any, and must be one of them.
  - `knowledge_graph` object: `auto_build` (default false), `exclude_path_prefixes` and `exclude_categories`.
  - `currency` object, nullable: `default`, the ISO 4217 code ingestion reads for an ambiguous symbol.
  - `domain_id` string: The pinned version of the domain the workspace sorts its files into.
  - `domain_slug` string: The slug of that domain, such as `generic`.
  - `domain_version` integer: The version of the domain the workspace is pinned to.
  - `global_context` string: Background every search and QA turn without its own `context` runs with.
  - `config_version` integer
  - `status` 'active' | 'deleting' | 'unavailable', required: `unavailable` only in a list: the document service has no workspace by this id, so reading it is `404 workspace_not_found`. Delete it to take it off the list.
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `storage` WorkspaceStorage: Where the workspace keeps its files. For a workspace you were invited into from another account, `connection_id` and `location` are null.
    - `type` 'managed' | 'tenant_bucket' | 'external', required: `external` for a bucket or container of the owner account's.
    - `connection_id` string, nullable: `external`: the storage connection.
    - `provider` 's3' | 'azure_blob' | 'null', nullable: `external`: the cloud.
    - `location` string, nullable: The folder the workspace's files are kept in.
    - `health` 'draft' | 'ready' | 'degraded' | 'revoked' | 'null', nullable: `external`: the connection's `status`.

## Other responses

- `401`: Missing or invalid API key (`authentication_error`, code `invalid_api_key`).
- `404`: No workspace with this id that the key may use (`not_found_error`, code `workspace_not_found`), or Workspaces are off on this deployment (`not_found`).
- `429`: Over the account's requests per minute for document routes, or the document service is throttling this account (`rate_limit_error`).
- `500`: Something failed on Drex's side (`internal_error`).
- `502`: The document service refused Drex's own request (`upstream_error`, code `ndi_refused_drex`). Retry later.
- `503`: The document service is unavailable (`service_unavailable`).

---

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