Data Domains API

The Data Domains API provides CRUD operations for domains, steward management, product assignment, hierarchy navigation, scorecard retrieval, and domain-aware approvers.

Base path: /organizations/{org_slug}/domains

All endpoints require authentication.

---

Domain CRUD

Create Domain

POST /organizations/{org_slug}/domains

Request Body:

Field	Type	Required	Description
name	string	✅	Domain name
slug	string	✅	URL-safe identifier
description	string	—	Domain purpose/scope
icon	string	—	Emoji or icon identifier
owner_id	UUID	—	Owner user ID (defaults to caller)
parent_domain_id	UUID	—	Parent domain for hierarchy

Response: 201 Created — DataDomainResponse

Errors: 409 Conflict — Slug already exists.

---

List Domains

GET /organizations/{org_slug}/domains

Response: 200 OK — DataDomainListResponse[]

[
  {
    "id": "uuid",
    "name": "Finance",
    "slug": "finance",
    "description": "All financial data assets",
    "icon": "💰",
    "owner": {
      "id": "uuid",
      "email": "cdo@example.com",
      "full_name": "Chief Data Officer",
      "avatar_url": null
    },
    "product_count": 15
  }
]

---

Get Domain

GET /organizations/{org_slug}/domains/{domain_slug}

Response: 200 OK — DataDomainResponse (includes memberships, children, product count).

Errors: 404 Not Found

---

Update Domain

PATCH /organizations/{org_slug}/domains/{domain_slug}

Request Body (all fields optional):

Field	Type	Description
name	string	Updated name
description	string	Updated description
icon	string	Updated icon
owner_id	UUID	Transfer ownership
parent_domain_id	UUID | null	Move in hierarchy

Response: 200 OK — DataDomainResponse

---

Delete Domain

DELETE /organizations/{org_slug}/domains/{domain_slug}

Response: 204 No Content

---

Hierarchy

Get Domain Tree

GET /organizations/{org_slug}/domains/tree

Returns all domains with parent_domain_id populated for client-side tree rendering.

Response: 200 OK — DataDomainListResponse[] (each item includes parent_domain_id)

---

Steward Management

Add Steward

POST /organizations/{org_slug}/domains/{domain_slug}/stewards

Request Body:

Field	Type	Required	Description
user_id	UUID	✅	User to add
role	string	✅	owner or steward

Response: 201 Created — DomainMembershipResponse

Errors: 409 Conflict — User already a steward.

---

Remove Steward

DELETE /organizations/{org_slug}/domains/{domain_slug}/stewards/{user_id}

Response: 204 No Content

Errors: 400 Bad Request — Cannot remove the last owner.

---

Product Assignment

Assign Product

POST /organizations/{org_slug}/domains/{domain_slug}/products

Request Body:

Field	Type	Required	Description
product_id	UUID	✅	Product to assign

Response: 201 Created — ProductDomainAssignmentResponse

Errors: 409 Conflict — Product already assigned to this domain.

---

Unassign Product

DELETE /organizations/{org_slug}/domains/{domain_slug}/products/{product_id}

Response: 204 No Content

---

List Domain Products

GET /organizations/{org_slug}/domains/{domain_slug}/products

Query Parameters:

Parameter	Type	Default	Description
limit	int	100	Max items (1–500)
offset	int	0	Pagination offset

Response: 200 OK

{
  "items": [
    {
      "id": "uuid",
      "name": "orders",
      "slug": "orders",
      "product_type": "table",
      "description": "Order transactions",
      "space_id": "uuid"
    }
  ],
  "total": 15
}

---

Governance Scorecard

Get Domain Scorecard

GET /organizations/{org_slug}/domains/{domain_slug}/scorecard

Returns governance health metrics for all products assigned to the domain.

Response: 200 OK — DomainScorecardResponse

---

Domain Approvers

Get Approvers for Product

GET /organizations/{org_slug}/domains/products/{product_id}/domain-approvers

Returns domain owners who can approve access requests for a product based on its domain membership.

Response: 200 OK

[
  {
    "user": {
      "id": "uuid",
      "email": "owner@example.com",
      "full_name": "Domain Owner",
      "avatar_url": null
    },
    "domain_name": "Finance",
    "domain_slug": "finance"
  }
]

---

Response Models

DataDomainResponse

Field	Type	Description
id	UUID	Domain identifier
name	string	Domain name
slug	string	URL-safe identifier
description	string | null	Domain description
icon	string | null	Icon/emoji
owner_id	UUID	Primary owner
organization_id	UUID	Parent organization
parent_domain_id	UUID | null	Parent domain (hierarchy)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp
owner	UserBrief | null	Owner details
memberships	DomainMembershipResponse[]	All steward memberships
children	DataDomainListResponse[]	Child sub-domains
product_count	int	Number of assigned products

DataDomainListResponse

Field	Type	Description
id	UUID	Domain identifier
name	string	Domain name
slug	string	URL-safe identifier
description	string | null	Description
icon	string | null	Icon
parent_domain_id	UUID | null	Parent domain
owner	UserBrief | null	Owner details
product_count	int	Product count

DomainMembershipResponse

Field	Type	Description
id	UUID	Membership ID
domain_id	UUID	Domain ID
user_id	UUID	User ID
role	string	owner or steward
created_at	datetime	Membership creation date
user	UserBrief | null	User details