curl --request POST \
--url https://ndi-api.nace.ai/v1/workspaces \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"name": "<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": true,
"exclude_categories": [
"<string>"
],
"exclude_path_prefixes": [
"<string>"
]
},
"name": "<string>",
"owner_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"retention_policy": {
"derived_ttl_days": 2,
"job_ttl_days": 30,
"source_ttl_days": 2
},
"share_count": 1,
"status": "active",
"updated_at": "2023-11-07T05:31:56Z",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"global_context": "",
"ledger_understanding": {
"engine": "measured",
"gl_parsing": true,
"package_confirmation": "required",
"package_scope": {
"path_prefix": "<string>",
"paths": [
"<string>"
],
"selection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"prepared_relationships": [
{
"bucket_count": 123,
"keys": [
{
"left_column": "<string>",
"right_column": "<string>",
"left_normalization": {
"kind": "identity"
},
"right_normalization": {
"kind": "identity"
}
}
],
"left": {
"path": "<string>",
"component": "<string>"
},
"name": "<string>",
"right": {
"path": "<string>",
"component": "<string>"
}
}
],
"trigger": "auto"
},
"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
}
}create_workspace
Provision a new workspace. Cost class: fast.
Every field has a sensible default so a caller who knows nothing creates a working workspace with just a name. The workspace is immediately usable for ingestion after this call; no activation step is needed.
Storage is provisioned for you under the tenant’s own storage principal; the root URI is an internal detail and does not appear on the wire contract until customer-owned roots are supported end to end.
curl --request POST \
--url https://ndi-api.nace.ai/v1/workspaces \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"name": "<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": true,
"exclude_categories": [
"<string>"
],
"exclude_path_prefixes": [
"<string>"
]
},
"name": "<string>",
"owner_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"retention_policy": {
"derived_ttl_days": 2,
"job_ttl_days": 30,
"source_ttl_days": 2
},
"share_count": 1,
"status": "active",
"updated_at": "2023-11-07T05:31:56Z",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"global_context": "",
"ledger_understanding": {
"engine": "measured",
"gl_parsing": true,
"package_confirmation": "required",
"package_scope": {
"path_prefix": "<string>",
"paths": [
"<string>"
],
"selection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"prepared_relationships": [
{
"bucket_count": 123,
"keys": [
{
"left_column": "<string>",
"right_column": "<string>",
"left_normalization": {
"kind": "identity"
},
"right_normalization": {
"kind": "identity"
}
}
],
"left": {
"path": "<string>",
"component": "<string>"
},
"name": "<string>",
"right": {
"path": "<string>",
"component": "<string>"
}
}
],
"trigger": "auto"
},
"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
Body
Provision a new workspace.
Every field has a default so a caller who knows nothing creates a working workspace with just a name. Creating a workspace ingests nothing and costs nothing — it is a namespace plus a configuration.
1 - 200Access-label configuration. labels=[] (the default) disables filtering entirely.
Show child attributes
Show child attributes
How to read amounts whose currency the documents leave open. Defaults to USD; send default=null to assume nothing.
Show child attributes
Show child attributes
Domain vocabulary. Resolved to the latest published version unless pinned.
Pin a specific domain version. Omit to take the latest published.
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.
20000Knowledge-graph build policy. Builds are on demand unless this asks for automatic ones, so a workspace only pays for a graph someone wanted.
Show child attributes
Show child attributes
When to understand the workspace's general ledger — table and column roles, the journal key and its balance proof, and the integrity battery. Runs automatically for a workspace that holds a journal-line table, and costs one that does not nothing.
Show child attributes
Show child attributes
TTLs for derived material, source bytes, and job payloads.
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 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.
Show child attributes
Show child attributes
The console user who owns the workspace, or null for an organization-owned integration workspace.
A workspace's retention setting, chosen at creation and editable afterwards.
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
Number of users explicitly granted workspace access; excludes the owner.
x >= 0Lifecycle 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 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.
When this workspace understands its general ledger — table and column roles, the journal key and its balance proof, and the integrity battery. A workspace configured before this block existed reads back the default.
Show child attributes
Show child attributes
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