Semantic Domains API

Overview

The Semantic Domains API allows you to create, retrieve, update, and delete semantic domains programmatically. Semantic domains define project-wide data terminology, organizing tables and fields into logical business concepts.

Base path:

https://semaphor.cloud/api/v1/domains

All endpoints require authentication with a Bearer token that includes project_id.

Access Control

Different operations require different token configurations:

Operation	Token Requirements
List domains (GET)	Any token with `projectId`. Results filtered by `semanticDomainAccess` on the token.
Get domain (GET)	Any token with `projectId`. Honors `semanticDomainAccess` restrictions.
Create domain (POST)	Project token (`type: "project"`) with `orgUserId`. User must be an Admin. Token must have unrestricted domain access (`semanticDomainAccess` omitted or `mode: "all"`).
Update domain (PUT/PATCH)	Project token with `orgUserId`. User must be an Admin.
Delete domain (DELETE)	Project token with `orgUserId`. User must be an Admin.

Domain Object

{
  "id": "domain_abc123",
  "projectId": "p_abc123",
  "name": "sales_metrics",
  "label": "Sales Metrics",
  "description": "Revenue and order metrics",
  "createdAt": "2026-03-22T10:00:00.000Z",
  "createdBy": "user_abc123"
}

Fields:

id: Unique domain identifier
projectId: The project this domain belongs to
name: Identifier (lowercase letters and underscores only, unique per project)
label: Human-readable display name (defaults to name if not provided)
description: Optional description (defaults to empty string)
createdBy: Organization user ID who created the domain (nullable)
createdAt: Timestamp in ISO 8601 format

Template management (relationships, calculated fields, joinability, discovery) is handled by separate sub-resource routes and is not part of this CRUD API.

Example: Create a Domain via API

1. Get a project token

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "projectId": "your-project-id",
    "projectSecret": "your-project-secret",
    "orgUserId": "your-org-user-id"
  }'

2. Create a domain

curl -X POST https://semaphor.cloud/api/v1/domains \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sales_metrics",
    "label": "Sales Metrics",
    "description": "Revenue and order tracking"
  }'

Expected Response:

{
  "domain": {
    "id": "domain_abc123",
    "projectId": "p_abc123",
    "name": "sales_metrics",
    "label": "Sales Metrics",
    "description": "Revenue and order tracking",
    "createdAt": "2026-03-22T10:00:00.000Z",
    "createdBy": "user_abc123"
  }
}

List Domains

GET /domains

Returns all domains in the project that the token has access to.
Results are filtered by semanticDomainAccess when present on the token.

Example Request:

curl -X GET https://semaphor.cloud/api/v1/domains \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "domains": [
    {
      "id": "domain_abc123",
      "projectId": "p_abc123",
      "name": "sales_metrics",
      "label": "Sales Metrics",
      "description": "Revenue and order tracking",
      "createdAt": "2026-03-22T10:00:00.000Z",
      "createdBy": "user_abc123"
    }
  ]
}

Create Domain

POST /domains

Creates a new semantic domain in the project.
Requires a project token with an Admin organization user.
Token must have unrestricted domain access (semanticDomainAccess omitted or mode: "all").

Request Body:

{
  "name": "customer_data",
  "label": "Customer Data",
  "description": "Customer demographics and preferences"
}

Required Fields:

name: Lowercase letters and underscores only, unique per project
label: Human-readable display name

Optional Fields:

description: Domain description (defaults to empty string)

Example Request:

curl -X POST https://semaphor.cloud/api/v1/domains \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer_data",
    "label": "Customer Data",
    "description": "Customer demographics and preferences"
  }'

Example Response:

{
  "domain": {
    "id": "domain_def456",
    "projectId": "p_abc123",
    "name": "customer_data",
    "label": "Customer Data",
    "description": "Customer demographics and preferences",
    "createdAt": "2026-03-22T11:00:00.000Z",
    "createdBy": "user_abc123"
  }
}

Get Domain by ID

GET /domains/:domainId

Returns a single domain's metadata.
Honors semanticDomainAccess restrictions on the token.

Example Request:

curl -X GET https://semaphor.cloud/api/v1/domains/domain_abc123 \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "domain": {
    "id": "domain_abc123",
    "projectId": "p_abc123",
    "name": "sales_metrics",
    "label": "Sales Metrics",
    "description": "Revenue and order tracking",
    "createdAt": "2026-03-22T10:00:00.000Z",
    "createdBy": "user_abc123"
  }
}

Update Domain

PUT /domains/:domainId or PATCH /domains/:domainId

Updates domain fields.
At least one of name, label, or description must be provided.
Both PUT and PATCH behave identically (partial update).
Requires a project token with an Admin organization user.

Request Body:

{
  "label": "Updated Sales Metrics",
  "description": "Updated description"
}

Example Request:

curl -X PUT https://semaphor.cloud/api/v1/domains/domain_abc123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Updated Sales Metrics",
    "description": "Updated description"
  }'

Example Response:

{
  "domain": {
    "id": "domain_abc123",
    "projectId": "p_abc123",
    "name": "sales_metrics",
    "label": "Updated Sales Metrics",
    "description": "Updated description",
    "createdAt": "2026-03-22T10:00:00.000Z",
    "createdBy": "user_abc123"
  }
}

Delete Domain

DELETE /domains/:domainId

Permanently deletes a domain.
Requires a project token with an Admin organization user.

Example Request:

curl -X DELETE https://semaphor.cloud/api/v1/domains/domain_abc123 \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "success": true,
  "deletedDomainId": "domain_abc123"
}

Error Handling

400 Bad Request:

{
  "error": "Invalid semantic domain payload",
  "details": { ... }
}

{
  "error": "Domain with name 'sales' already exists"
}

{
  "error": "Domain name must contain only lowercase letters and underscores"
}

{
  "error": "At least one of name, label, or description is required"
}

401 Unauthorized:

{
  "error": "Authentication failed"
}

{
  "error": "invalid token: project_id is missing in the token"
}

403 Forbidden:

{
  "error": "Access denied. Semantic domain writes require a project token."
}

{
  "error": "Access denied. Only organization users can manage semantic domains."
}

{
  "error": "Forbidden: scoped semanticDomainAccess tokens cannot create new domains."
}

404 Not Found:

{
  "error": "Domain not found"
}

Notes

All endpoints require authentication (Bearer token)
Domain names must be lowercase letters and underscores only
Domain names must be unique within each project
Read operations honor semanticDomainAccess restrictions on the token
Write operations require a project token with an organization user who has the Admin role
Creating new domains additionally requires unrestricted domain access on the token
All timestamps are returned in ISO 8601 format
The label field defaults to name when not explicitly set
Template management (relationships, calculated fields) uses separate sub-resource routes

Semantic Domains API

On this page