Domains API

Domains allow you to organize pipelines by team, function, or any logical grouping.

POST /api/domains

Create a new domain. Requires domains:write permission.

Request

{
  "name": "Marketing",
  "description": "Marketing team data pipelines",
  "color": "#10B981"
}

Response

{
  "id": "uuid",
  "name": "Marketing",
  "description": "Marketing team data pipelines",
  "color": "#10B981",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": null
}

GET /api/domains

List all domains in the organization. Requires domains:read permission.

Query Parameters:

Parameter	Type	Default	Description
limit	int	100	Maximum results
offset	int	0	Pagination offset
include_counts	bool	false	Include pipeline counts

Without Counts

[
  {
    "id": "uuid",
    "name": "Marketing",
    "description": "Marketing team data pipelines",
    "color": "#10B981",
    "created_at": "2024-01-15T10:00:00Z"
  }
]

With Counts

[
  {
    "id": "uuid",
    "name": "Marketing",
    "description": "Marketing team data pipelines",
    "color": "#10B981",
    "pipeline_count": 5,
    "created_at": "2024-01-15T10:00:00Z"
  }
]

GET /api/domains/{domain_id}

Get a domain by ID. Requires domains:read permission.

{
  "id": "uuid",
  "name": "Marketing",
  "description": "Marketing team data pipelines",
  "color": "#10B981",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": null
}

PUT /api/domains/{domain_id}

Update a domain. Requires domains:write permission.

{
  "name": "Marketing & Analytics",
  "description": "Updated description",
  "color": "#3B82F6"
}

All fields are optional - only provided fields are updated.

DELETE /api/domains/{domain_id}

Delete a domain. Requires domains:delete permission.

Returns 204 No Content.

Errors:

• 403 Forbidden - Domain has pipelines assigned. Move or delete pipelines first.
• 404 Not Found - Domain not found.

Color Codes

Domains support any valid hex color code. Suggested palette:

Color	Hex	Use Case
Gray	#6B7280	Default
Blue	#3B82F6	Engineering
Green	#10B981	Marketing
Purple	#8B5CF6	Product
Orange	#F59E0B	Sales
Red	#EF4444	Operations
Cyan	#06B6D4	Analytics

Using Domains with Pipelines

Assign pipelines to domains when creating or updating:

{
  "name": "HubSpot to BigQuery",
  "domain_id": "uuid",
  "config": { ... }
}

Filter pipelines by domain:

GET /api/pipelines?domain_id=uuid

Domain Role Overrides

Users can have elevated permissions within specific domains:

// Viewer at org level, but Admin in Marketing domain
{
  "org_role": "viewer",
  "domain_overrides": [
    {"domain_id": "marketing-uuid", "role": "admin"}
  ]
}

See Users API for domain role endpoints.