Domains

A domain is a taxonomy (classification vocabulary) and a knowledge-graph ontology, versioned together. Platform domains (generic, financial, legal, audit, etc.) are published and ready to use. Tenant domains are authored by your organization and visible only to you. All list routes use keyset cursor pagination (cursor / next_cursor).

Generate domain draft

POST /v1/domains/generate

Ask the model for an unsaved taxonomy and ontology from a free-text domain description. Cost class: slow. Nothing is persisted and no job is created — edit the draft, then create it with POST /v1/domains. Request body:

description (required) — What kinds of files belong in this domain.
display_name (optional) — Preferred display name; overrides the model’s suggestion.
slug (optional) — Preferred slug; overrides the model’s suggestion.

curl -X POST "$NDI_BASE_URL/v1/domains/generate" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Files produced during an audit engagement: planning memos, risk assessments, working papers, client correspondence, financial statements and supporting evidence. Classify each file by the phase of work and the type of record it represents.",
    "display_name": "Akhan Testing"
  }'

Response: taxonomy, ontology, suggested_slug, suggested_display_name, and a validation object (same shape as create/publish). The draft is normalized so rule R0 and the other publish gates are satisfied.

List domains

GET /v1/domains

List all domains visible to the caller: platform-owned published domains plus the tenant’s own domains in any status. Query parameters:

owner (optional) — platform or tenant.
status (optional) — draft or published.
cursor (optional) — Opaque cursor from next_cursor.
limit (optional, default 50, max 200)

curl "$NDI_BASE_URL/v1/domains?owner=platform&status=published" \
  -H "X-API-Key: $NDI_API_KEY"

Response:

{
  "items": [
    {
      "domain_id": "550e8400-e29b-41d4-a716-446655440000",
      "slug": "generic",
      "display_name": "Generic",
      "owner": "platform",
      "version": 1,
      "status": "published",
      "parent_slug": null,
      "class_count": 48,
      "selectable": true
    },
    {
      "domain_id": "550e8400-e29b-41d4-a716-446655440001",
      "slug": "audit",
      "display_name": "Audit",
      "owner": "platform",
      "version": 2,
      "status": "published",
      "parent_slug": "generic",
      "class_count": 120,
      "selectable": true
    }
  ],
  "next_cursor": null,
  "total_count": 8
}

Get domain

GET /v1/domains/{domain_id}

Read one domain version with inheritance already resolved. The taxonomy and ontology include any entries inherited from a parent domain. Response:

{
  "domain_id": "550e8400-e29b-41d4-a716-446655440001",
  "slug": "audit",
  "display_name": "Audit",
  "owner": "platform",
  "version": 2,
  "status": "published",
  "parent_slug": "generic",
  "class_count": 120,
  "selectable": true,
  "taxonomy": {
    "classes": [
      {
        "group": "financial",
        "subgroup": "balance_sheet",
        "description": "Balance sheet: assets, liabilities, and equity.",
        "document_type": "BalanceSheet",
        "aliases": []
      }
    ],
    "allow_other": true
  },
  "ontology": {
    "node_types": [{"name": "Organization", "tier": 1, "description": "..."}],
    "edge_types": [{"name": "subsidiary_of", "from_types": ["Organization"], "to_types": ["Organization"], "description": "..."}]
  },
  "published_at": "2026-01-01T00:00:00Z"
}

Create domain

POST /v1/domains

Create a tenant-owned domain in draft status. Drafts are editable and not yet usable by workspaces. Omitting ontology copies the platform’s generic ontology. Request:

{
  "slug": "compliance_2026",
  "display_name": "Compliance 2026",
  "taxonomy": {
    "classes": [
      {
        "group": "regulatory",
        "subgroup": "gdpr",
        "description": "GDPR compliance documentation.",
        "document_type": "RegulatoryDocument",
        "aliases": []
      }
    ],
    "allow_other": true
  }
}

Body fields:

slug (required) — Unique slug for the tenant, slug pattern, max 64 chars. Reserved platform slugs are refused.
display_name (required, 1–200 chars) — Human-readable label.
taxonomy (required) — The classification vocabulary.
ontology (optional) — Knowledge-graph node and edge types. Omit to inherit the platform generic ontology.

Response (201 Created):

{
  "domain": { ... },
  "validation": {
    "valid": true,
    "errors": [],
    "effective_class_count": 1,
    "effective_node_type_count": 12,
    "effective_edge_type_count": 20
  }
}

Every create and update response includes a validation block so you know whether a publish call would succeed before you make it. Errors:

reserved_domain_slug (409) — Slug is reserved for platform use.
domain_validation_failed (422) — Taxonomy or ontology failed validation.

Update domain

PATCH /v1/domains/{domain_id}

Edit a draft, or spin a published domain into a new draft version.

Editing a draft mutates the draft in place.
Editing a published domain creates version n+1 as a new draft, leaving version n untouched.

Existing workspaces remain pinned to the version they were created with. Request:

{
  "display_name": "Compliance 2026 v2",
  "taxonomy": { ... }
}

Body fields: Any subset of display_name, taxonomy, ontology. Response: Same shape as Create.

Publish domain

POST /v1/domains/{domain_id}/publish

Freeze a draft and make it selectable by workspaces. Validation must pass; a failing publish returns domain_validation_failed with the full error list. Request body: {} (empty) Response: Same shape as Create, with status: "published" and published_at set. Errors:

domain_validation_failed (422) — Taxonomy or ontology failed the publish gate.

Built-in platform domains

The following slugs are reserved and available to every organization:

Slug	Description
`generic`	General-purpose categories
`financial`	Financial document taxonomy
`legal`	Legal document taxonomy
`insurance`	Insurance document taxonomy
`audit`	Audit-specific vocabulary
`audit_private_profit`	Private-sector audit taxonomy
`audit_public_non_profit`	Public/non-profit audit taxonomy

Granular operations

Platform resources

Knowledge graph

Tools

Operations

Generate domain draft

List domains

Get domain

Create domain

Update domain

Publish domain

Built-in platform domains

​Generate domain draft

​List domains

​Get domain

​Create domain

​Update domain

​Publish domain

​Built-in platform domains

Generate domain draft

List domains

Get domain

Create domain

Update domain

Publish domain

Built-in platform domains