reference

Registry API

Full endpoint reference for the YounndAI Domains API — all 10 endpoints.

Prerequisites

All endpoints use the base URL https://domains.younndai.com/api. All published domains are publicly accessible — no authentication required.

Domain Endpoints

List Domains

GET/api/domains

Returns a paginated list of published domains with filtering, search, and sorting.

{
  "domains": [
    {
      "id": "clx...",
      "path": "yon.health",
      "version": "1.0",
      "status": "active",
      "state": "active",
      "tier": "official",
      "verified": true,
      "score": 0.95,
      "notice": null,
      "description": "Healthcare domain covering patient data and clinical records",
      "records": 12,
      "totalFieldCount": 47,
      "tagline": "Structured healthcare vocabularies for AI agents",
      "tags": ["VITALS", "VITAL", "PATIENT", "DX", "RX", "LAB", "PROCEDURE", "ALLERGY", "SYMPTOM", "DIFFERENTIAL", "CODE_SUGGESTION", "ENCOUNTER_SUMMARY"]
    }
  ],
  "nextCursor": "clx...",
  "hasMore": true,
  "total": 31
}

Cache: public, s-maxage=300, stale-while-revalidate=60 (5 minutes)

Get Domain Schema

GET/api/domains/:path

Returns the full schema for a specific domain.

{
  "domain": "yon.health",
  "version": "1.0",
  "status": "active",
  "description": "Healthcare domain covering patient data and clinical records",
  "records": {
    "VITALS": {
      "description": "Patient vital signs",
      "fields": {
        "bp": { "type": "string", "required": true, "pattern": "\\d+/\\d+", "description": "Blood Pressure in mmHg in systolic/diastolic format", "unit": "mmHg", "example": "120/80" },
        "hr": { "type": "int", "required": false, "range": [30, 250], "description": "Heart Rate in bpm", "unit": "bpm", "example": "72" },
        "temp_c": { "type": "float", "required": false, "range": [30.0, 45.0], "description": "Temperature (Celsius) in °C", "unit": "°C", "example": "37.0" },
        "spo2": { "type": "float", "required": false, "range": [0, 100], "description": "Oxygen Saturation in %", "unit": "%", "example": "98" }
      }
    }
  }
}

Cache: public, s-maxage=86400 (24 hours). Pinned versions: immutable.

List Versions

GET/api/domains/:path/versions

Returns all published versions of a domain.

{
  "versions": [
    { "version": "1.0", "status": "active", "score": 1.0, "createdAt": "2026-01-15T00:00:00Z" },
    { "version": "0.9", "status": "deprecated", "score": 0.9, "changeNote": "Initial release", "createdAt": "2025-11-01T00:00:00Z" }
  ]
}

Search Domains

GET/api/domains/search?q=:query

Full-text search across domain names, descriptions, tags, and fields.

{
  "results": [
    {
      "path": "yon.health",
      "version": "1.0",
      "tier": "official",
      "verified": true,
      "score": 0.95,
      "notice": null,
      "description": "Healthcare domain",
      "tagline": "Structured healthcare vocabularies",
      "tags": ["VITALS", "DX", "RX"],
      "matchedField": "description"
    }
  ]
}

Cache: public, s-maxage=300 (5 minutes)

Registry Stats

GET/api/domains/stats

Aggregate statistics about the registry.

{
  "totalDomains": 31,
  "totalRecords": 248,
  "totalFields": 1547,
  "byTier": {
    "official": 31, "community": 0, "partner": 0, "institutional": 0
  }
}

Cache: public, s-maxage=300, stale-while-revalidate=60 (5 minutes)

Namespace Endpoints

List Namespaces

GET/api/namespaces

Returns all registered namespaces.

{
  "namespaces": [
    { "path": "yon", "type": "official", "domainCount": 31 },
    { "path": "com", "type": "community", "domainCount": 0 }
  ]
}

Get Namespace

GET/api/namespaces/:path

Returns details for a specific namespace.

{
  "path": "yon",
  "type": "official",
  "description": "Official YounndAI domains",
  "domainCount": 31,
  "domains": ["yon.health", "yon.fintech", "yon.logistics"]
}

Operations Endpoints

Notices

GET/api/notices

Active operational notices (deprecations, migrations, advisories).

{
  "notices": [
    {
      "code": "N002",
      "scope": "domain",
      "target": "yon.health",
      "severity": "info",
      "message": "yon.health v1.1 adds LAB record type — migration advisory"
    }
  ]
}

Announcements

GET/api/announcements

Published registry announcements (releases, events).

{
  "announcements": [
    {
      "id": "ann-001",
      "type": "release",
      "title": "31 Official Domains Launched",
      "summary": "The initial set of 31 yon.* domains is now available.",
      "publishedAt": "2026-02-28T00:00:00Z"
    }
  ]
}

Health Check

GET/api/health

Registry health status.

{
  "ok": true,
  "timestamp": "2026-02-28T21:00:00Z",
  "version": "1.0"
}

Response Codes

Code	Description
`200`	Success
`404`	Domain or namespace not found
`400`	Invalid query parameters
`403`	Access denied (tier restriction)
`429`	Rate limited (60 req/min default)
`500`	Internal server error

Caching

All responses include caching headers:

Endpoint	TTL	Header
Domain lists	5 min	`s-maxage=300, stale-while-revalidate=60`
Single domain (latest)	24h	`s-maxage=86400`
Pinned version	Immutable	`immutable`
Stats	5 min	`s-maxage=300, stale-while-revalidate=60`
Health	No cache	—

Use If-None-Match or If-Modified-Since headers for conditional requests.

Next Steps

Schema Format

Anatomy of a domain schema — types, constraints, and payloads.

SDK

Use the @younndai/domains TypeScript package.