--- title: "Create a workspace" method: POST path: "/v1/workspaces" tags: ["Workspaces"] --- # Create a workspace `POST /v1/workspaces` ## Request - Base URL: `https://console.nace.ai` - URL: `https://console.nace.ai/v1/workspaces` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) A new workspace in this key's account. Free; creating one uploads nothing. The knowledge graph is built only when asked unless `knowledge_graph.auto_build` is true. The name must be unique in the account, ignoring case. Not idempotent: a retried create that already went through answers `409`. ## Request body - object - `name` string, required: Unique among the account's live workspaces, ignoring case. Leading and trailing spaces are trimmed. - `domain_slug` string: The published domain the workspace sorts its files into: `generic`, the general-purpose default; a domain your account published; or one Nace provides. The workspace pins the newest published version at the time. Left out, `generic`. Can't change later. A slug that names no published domain you can use is `422 invalid_request`. - `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: Replaces the block whole: `auto_build`, `exclude_path_prefixes`, `exclude_categories`. - `currency` object, nullable: `{"default": "USD"}`, or null for none. - `global_context` string: Background for every search and QA turn; `""` clears it. - `storage` object: Keep the workspace's files in your own bucket or container: a storage connection of this account whose `status` is `ready`. Left out, Nace's managed storage. Can't change later, and never falls back to managed storage. A Zero retention account must give one. - `type` 'external', required - `connection_id` string, uuid, required ## Response `201` 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`: Workspaces are off on this deployment (`not_found`), or `storage` was given where customer storage is off (`not_found_error`, code `storage_connection_unavailable`). - `409`: The account already has a live workspace with this name, ignoring case (`conflict_error`, code `workspace_name_taken`). Pick another name. With `storage`, code `storage_conflict` means the workspace's folder could not be reserved under the connection's prefix. - `422`: The body or a parameter is invalid, or the document service refused it (`invalid_request_error`). Where customer storage is on, a `storage.connection_id` that is not a ready connection of this account is code `storage_connection_not_ready`; where it is off, `storage` answers `404`. - `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)