Domains API¶

Direct access to domain resources (top-level learning categories).

Base URL: {base-url}/discovery/domains Authentication: Not required

Overview¶

The Domains API provides CRUD operations for domain resources. Domains are the top-level categories in the content hierarchy (e.g., "Machine Learning", "Web Development").

This API is accessed through the discovery edge function at the /domains path.

Endpoints¶

Endpoint	Purpose
`GET /`	List all domains
`GET /{slug}`	Get domain by slug or UUID
`GET /{slug}/trails`	Get domain with paginated trails
`GET /{slug}/related`	Get related domains (same category)

GET /¶

Returns a paginated list of all published domains.

Parameters¶

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Items per page (max: 100)
`snapshot_id`	UUID	current	Query specific snapshot

Response¶

{
  "data": [
    {
      "id": "uuid",
      "slug": "machine-learning",
      "name": "Machine Learning",
      "description": "Fundamentals of machine learning...",
      "icon": "brain",
      "color": "#4F46E5",
      "trail_count": 12
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

GET /{slug}¶

Returns a single domain by slug or UUID.

Path Parameters¶

Parameter	Type	Description
`slug`	string	Domain slug (e.g., `machine-learning`) or UUID

Query Parameters¶

Parameter	Type	Default	Description
`snapshot_id`	UUID	current	Query specific snapshot

Response¶

{
  "id": "uuid",
  "slug": "machine-learning",
  "name": "Machine Learning",
  "description": "Fundamentals of machine learning and AI",
  "icon": "brain",
  "color": "#4F46E5",
  "is_published": true,
  "trail_count": 12,
  "category_id": "uuid",
  "learning_outcomes": [
    "Understand ML fundamentals",
    "Build predictive models"
  ]
}

Errors¶

Code	Description
`NOT_FOUND`	Domain with slug/UUID not found

GET /{slug}/trails¶

Returns a domain with its trails (paginated).

Path Parameters¶

Parameter	Type	Description
`slug`	string	Domain slug or UUID

Query Parameters¶

Parameter	Type	Default	Description
`page`	integer	1	Page number for trails
`trail_limit`	integer	5	Max trails per page (max: 100)
`snapshot_id`	UUID	current	Query specific snapshot

Response¶

{
  "id": "uuid",
  "slug": "machine-learning",
  "name": "Machine Learning",
  "description": "Fundamentals of ML...",
  "icon": "brain",
  "color": "#4F46E5",
  "trail_count": 12,
  "trails": [
    {
      "id": "uuid",
      "title": "Neural Networks",
      "slug": "neural-networks",
      "estimated_mins": 180
    },
    {
      "id": "uuid",
      "title": "Deep Learning",
      "slug": "deep-learning",
      "estimated_mins": 240
    }
  ],
  "trail_meta": {
    "total": 12,
    "page": 1,
    "per_page": 5,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false,
    "total_concept_count": 45
  }
}

Key Fields¶

Field	Description
`trails`	Array of trail objects for current page
`trail_count`	Total trails in domain
`trail_meta`	Pagination metadata for trails
`trail_meta.total_concept_count`	Total concepts across all trails

GET /{slug}/related¶

Returns domains in the same category as the specified domain.

Path Parameters¶

Parameter	Type	Description
`slug`	string	Domain slug or UUID

Query Parameters¶

Parameter	Type	Default	Description
`limit`	integer	4	Max related domains (max: 10)
`snapshot_id`	UUID	current	Query specific snapshot

Response¶

{
  "data": [
    {
      "id": "uuid",
      "slug": "data-science",
      "name": "Data Science",
      "description": "Data analysis and visualization...",
      "icon": "chart",
      "color": "#10B981",
      "trail_count": 8
    },
    {
      "id": "uuid",
      "slug": "deep-learning",
      "name": "Deep Learning",
      "description": "Neural networks and deep learning...",
      "icon": "network",
      "color": "#6366F1",
      "trail_count": 10
    }
  ],
  "meta": {
    "total": 4,
    "page": 1,
    "per_page": 4
  }
}

Behavior¶

Returns domains with the same category_id as the requested domain
Excludes the requested domain from results
Falls back to random domains if no category or no related domains found

When to Use¶

Use Case	Endpoint
Domain catalog page	`GET /`
Domain detail page	`GET /{slug}`
Domain page with trail list	`GET /{slug}/trails`
"Related domains" section	`GET /{slug}/related`
Recommendations widget	`GET /{slug}/related`

Comparison with Discovery API¶

Feature	Domains API	Discovery API
Nested data	Separate endpoints	Single response
Trail pagination	Yes	Limited by `trail_limit`
Use case	Detail pages	Listing pages

Use the Domains API when you need: - Paginated trails for a domain - Related domain recommendations - Full domain detail

Use the Discovery API when you need: - Domains with preview trails in a single call - Homepage/catalog displays