curl --request PATCH \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"currency": {
"default": "USD"
},
"knowledge_graph": {
"auto_build": false,
"exclude_categories": [
"<string>"
],
"exclude_path_prefixes": [
"<string>"
]
}
}
'{
"access": {
"default_label": "<string>",
"labels": [
{
"description": "<string>",
"name": "<string>"
}
]
},
"config_version": 123,
"created_at": "2023-11-07T05:31:56Z",
"currency": {
"default": "USD"
},
"domain_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"domain_slug": "<string>",
"domain_version": 123,
"knowledge_graph": {
"auto_build": false,
"exclude_categories": [
"<string>"
],
"exclude_path_prefixes": [
"<string>"
]
},
"name": "<string>",
"retention_policy": {
"derived_ttl_days": 2,
"job_ttl_days": 30,
"source_ttl_days": 2
},
"status": "active",
"updated_at": "2023-11-07T05:31:56Z",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"purpose": "perception_playground"
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}update_workspace
Change a workspace’s mutable configuration. Cost class: fast.
Presence-aware, and whole-block: an omitted field is left alone, a supplied
one replaces its block entirely. Read the workspace, edit the block, send it
back — partial blocks fall back to the schema defaults, which is how a caller
flipping auto_build would otherwise wipe its own exclusion rules.
Graph builds are explicit by default: a build happens when
POST /v1/workspaces/{id}/knowledge-graph/builds asks for one. Turning
knowledge_graph.auto_build on hands that trigger to ingestion instead, for
a workspace that wants a graph over everything it ingests and accepts the bill
for one per ingestion. Either way a build already in flight is unaffected —
cancel it if that is what you meant.
currency follows the same whole-block rule, so {} is how its policy is
cleared. Setting currency.default changes how the next ingestion reads
amounts marked with a symbol that names several currencies ($, ¥, kr);
amounts already extracted as ambiguous stay that way until their file is
re-ingested, because the catalog records what a past extraction could read.
The domain, the label list, and the workspace name are deliberately not mutable here. The first two are part of the versioned config record stamped onto every derived artifact, so editing them in place would re-describe material that was derived under the old one.
curl --request PATCH \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"currency": {
"default": "USD"
},
"knowledge_graph": {
"auto_build": false,
"exclude_categories": [
"<string>"
],
"exclude_path_prefixes": [
"<string>"
]
}
}
'{
"access": {
"default_label": "<string>",
"labels": [
{
"description": "<string>",
"name": "<string>"
}
]
},
"config_version": 123,
"created_at": "2023-11-07T05:31:56Z",
"currency": {
"default": "USD"
},
"domain_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"domain_slug": "<string>",
"domain_version": 123,
"knowledge_graph": {
"auto_build": false,
"exclude_categories": [
"<string>"
],
"exclude_path_prefixes": [
"<string>"
]
},
"name": "<string>",
"retention_policy": {
"derived_ttl_days": 2,
"job_ttl_days": 30,
"source_ttl_days": 2
},
"status": "active",
"updated_at": "2023-11-07T05:31:56Z",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"purpose": "perception_playground"
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}Authorizations
Path Parameters
Workspace identifier.
Body
Change a workspace's mutable configuration.
Presence-aware: a field omitted from the body is left exactly as it is, so a
caller changing one block cannot clear another by not mentioning it. A field
that is supplied replaces its block whole — the rule set_key_grants
follows for label grants, which is what keeps turning a policy off the same
operation as turning it on, with no add/remove asymmetry to get wrong.
Only the knowledge-graph policy and the currency policy are mutable today. The domain and the label list are not: both are part of the versioned config record that every derived artifact is stamped with, so editing them in place would silently re-describe material that was derived under the old one.
The workspace's complete new currency-reading policy, or omitted to leave it unchanged. Whole-block like knowledge_graph: an empty object resets to the USD default, and {"default": null} is how the policy is cleared to assume nothing. Applies from the next ingestion onwards: amounts already extracted as ambiguous stay that way until their file is re-ingested, since the catalog records what a past extraction could read.
Show child attributes
Show child attributes
The workspace's complete new knowledge-graph policy, or omitted to leave it unchanged. Supplying it replaces every field it holds, so send the block read back from the workspace with your edits applied rather than only the key you are changing.
Show child attributes
Show child attributes
Response
Successful Response
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.
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
active, deleting 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.
perception_playground