# Registry Public API

The public registry and hosted compiler contract for Decantr browse, search, detail, intelligence-summary, and execution-pack flows. These are the hosted endpoints used by the registry portal, CLI, MCP consumers, and external tooling.

## Base URL

    https://api.decantr.ai/v1

Canonical response schemas are published at /schemas/.

- `namespace`
- `sort=recommended|recent|name`
- `recommended=true`
- `intelligence_source=authored|benchmark|hybrid`
- `blueprint_set=all|featured|certified|labs`
- `limit`
- `offset`

## Search

    GET /search?q=portfolio&type=blueprint&sort=recommended&recommended=true&intelligence_source=hybrid
    GET /search?q=studio&type=blueprint&blueprint_set=certified

Purpose: Full-text search across public registry content.
Schema: `search-response.v1.json`
Key fields: `total`, `results[]`, `results[].blueprint_portfolio`, `results[].intelligence`

## Public Lists

    GET /blueprints?namespace=@official&sort=recommended&recommended=true
    GET /blueprints?blueprint_set=featured
    GET /blueprints?blueprint_set=labs
    GET /patterns?namespace=@official&limit=50&offset=0
    GET /archetypes?namespace=@official&intelligence_source=authored

Supported endpoints: `/patterns`, `/themes`, `/blueprints`, `/archetypes`, `/shells`
Purpose: Browse one public content type with shared ranking and intelligence filters. Blueprint lists exclude Labs and folded slugs by default; `blueprint_set` exposes only the public cuts.
Schema: `public-content-list.v1.json`

## Public Detail

    GET /blueprints/@official/portfolio
    GET /patterns/@official/hero

Purpose: Fetch a single public content record, including its typed `data` payload and attached intelligence metadata.
Schema: `public-content-record.v1.json`

## Public Schema Discovery

    GET /schema/search-response.v1.json
    GET /schema/registry-intelligence-summary.v1.json

Purpose: Fetch the published JSON Schemas behind public Decantr contracts.
Browse all schemas: /schemas/

## Hosted Execution Pack Compile

    POST /packs/compile?namespace=@official
    Content-Type: application/json

    {
      "version": "4.0.0",
      "dna": {
        "theme": { "id": "clean", "mode": "light", "shape": "rounded" },
        "spacing": { "base_unit": 4, "scale": "linear", "density": "comfortable", "content_gap": "_gap4" },
        "typography": { "scale": "modular", "heading_weight": 600, "body_weight": 400 },
        "color": { "palette": "semantic", "accent_count": 1, "cvd_preference": "auto" },
        "radius": { "philosophy": "rounded", "base": 8 },
        "elevation": { "system": "layered", "max_levels": 3 },
        "motion": { "preference": "subtle", "duration_scale": 1, "reduce_motion": true },
        "accessibility": { "wcag_level": "AA", "focus_visible": true, "skip_nav": true },
        "personality": ["professional"]
      },
      "blueprint": {
        "shell": "sidebar-main",
        "sections": [
          {
            "id": "dashboard",
            "role": "primary",
            "shell": "sidebar-main",
            "description": "Primary dashboard section",
            "features": ["auth"],
            "pages": [{ "id": "home", "route": "/", "layout": ["hero"] }]
          }
        ],
        "features": ["auth"],
        "routes": { "/": { "section": "dashboard", "page": "home" } }
      },
      "meta": {
        "archetype": "saas-dashboard",
        "target": "react",
        "platform": { "type": "spa", "routing": "history" },
        "guard": { "mode": "guided", "dna_enforcement": "warn", "blueprint_enforcement": "warn" }
      }
    }

Purpose: Compile a schema-backed execution-pack bundle from an essence document using hosted public registry content.
Schema: `execution-pack-bundle.v1.json`
Notes: `namespace` is optional and defaults to `@official`. The API prefers the requested namespace first, then falls back to `@official` for public content resolution.

## Hosted Selected Execution Pack

    POST /packs/select?namespace=@official
    Content-Type: application/json

    {
      "essence": {
        "version": "4.0.0",
        "dna": {
          "theme": { "id": "clean", "mode": "light", "shape": "rounded" },
          "spacing": { "base_unit": 4, "scale": "linear", "density": "comfortable", "content_gap": "_gap4" },
          "typography": { "scale": "modular", "heading_weight": 600, "body_weight": 400 },
          "color": { "palette": "semantic", "accent_count": 1, "cvd_preference": "auto" },
          "radius": { "philosophy": "rounded", "base": 8 },
          "elevation": { "system": "layered", "max_levels": 3 },
          "motion": { "preference": "subtle", "duration_scale": 1, "reduce_motion": true },
          "accessibility": { "wcag_level": "AA", "focus_visible": true, "skip_nav": true },
          "personality": ["professional"]
        },
        "blueprint": {
          "shell": "sidebar-main",
          "sections": [
            {
              "id": "dashboard",
              "role": "primary",
              "shell": "sidebar-main",
              "description": "Primary dashboard section",
              "features": ["auth"],
              "pages": [{ "id": "home", "route": "/", "layout": ["hero"] }]
            }
          ],
          "features": ["auth"],
          "routes": { "/": { "section": "dashboard", "page": "home" } }
        },
        "meta": {
          "archetype": "saas-dashboard",
          "target": "react",
          "platform": { "type": "spa", "routing": "history" },
          "guard": { "mode": "guided", "dna_enforcement": "warn", "blueprint_enforcement": "warn" }
        }
      },
      "pack_type": "page",
      "id": "home"
    }

Purpose: Compile and return one schema-backed execution pack plus the manifest metadata needed to place it in the broader bundle.
Schema: `selected-execution-pack.v1.json`
Notes: Include a valid Decantr essence document on `essence`. `pack_type` must be one of `scaffold`, `review`, `section`, `page`, or `mutation`, and `id` is required for `section`, `page`, and `mutation` selection.

## Hosted File Critique

    POST /critique/file?namespace=@official
    Content-Type: application/json

    {
      "essence": {
        "version": "4.0.0",
        "dna": {
          "theme": { "id": "clean", "mode": "light", "shape": "rounded" },
          "spacing": { "base_unit": 4, "scale": "linear", "density": "comfortable", "content_gap": "_gap4" },
          "typography": { "scale": "modular", "heading_weight": 600, "body_weight": 400 },
          "color": { "palette": "semantic", "accent_count": 1, "cvd_preference": "auto" },
          "radius": { "philosophy": "rounded", "base": 8 },
          "elevation": { "system": "layered", "max_levels": 3 },
          "motion": { "preference": "subtle", "duration_scale": 1, "reduce_motion": true },
          "accessibility": { "wcag_level": "AA", "focus_visible": true, "skip_nav": true },
          "personality": ["professional"]
        },
        "blueprint": {
          "shell": "sidebar-main",
          "sections": [
            {
              "id": "dashboard",
              "role": "primary",
              "shell": "sidebar-main",
              "description": "Primary dashboard section",
              "features": ["auth"],
              "pages": [{ "id": "home", "route": "/", "layout": ["hero"] }]
            }
          ],
          "features": ["auth"],
          "routes": { "/": { "section": "dashboard", "page": "home" } }
        },
        "meta": {
          "archetype": "saas-dashboard",
          "target": "react",
          "platform": { "type": "spa", "routing": "history" },
          "guard": { "mode": "guided", "dna_enforcement": "warn", "blueprint_enforcement": "warn" }
        }
      },
      "filePath": "src/pages/Home.tsx",
      "code": "<button style={{ color: "#ff00ff" }}>Click me</button>",
      "treatmentsCss": ".brand-accent { color: var(--d-primary); }"
    }

Purpose: Critique inline file contents against a hosted review-pack contract compiled from the posted essence document.
Schema: `file-critique-report.v1.json`
Shared Definitions: `verification-report.common.v1.json`
Notes: Include a valid Decantr essence document on `essence` and a non-empty source string on `code`. `filePath` and `treatmentsCss` are optional but help the hosted critique stay aligned with local project context.

## Hosted Project Audit

    POST /audit/project?namespace=@official
    Content-Type: application/json

    {
      "essence": {
        "version": "4.0.0",
        "dna": {
          "theme": { "id": "clean", "mode": "light", "shape": "rounded" },
          "spacing": { "base_unit": 4, "scale": "linear", "density": "comfortable", "content_gap": "_gap4" },
          "typography": { "scale": "modular", "heading_weight": 600, "body_weight": 400 },
          "color": { "palette": "semantic", "accent_count": 1, "cvd_preference": "auto" },
          "radius": { "philosophy": "rounded", "base": 8 },
          "elevation": { "system": "layered", "max_levels": 3 },
          "motion": { "preference": "subtle", "duration_scale": 1, "reduce_motion": true },
          "accessibility": { "wcag_level": "AA", "focus_visible": true, "skip_nav": true },
          "personality": ["professional"]
        },
        "blueprint": {
          "shell": "sidebar-main",
          "sections": [
            {
              "id": "dashboard",
              "role": "primary",
              "shell": "sidebar-main",
              "description": "Primary dashboard section",
              "features": ["auth"],
              "pages": [{ "id": "home", "route": "/", "layout": ["hero"] }]
            }
          ],
          "features": ["auth"],
          "routes": { "/": { "section": "dashboard", "page": "home" } }
        },
        "meta": {
          "archetype": "saas-dashboard",
          "target": "react",
          "platform": { "type": "spa", "routing": "history" },
          "guard": { "mode": "guided", "dna_enforcement": "warn", "blueprint_enforcement": "warn" }
        }
      },
      "dist": {
        "indexHtml": "<!doctype html><html lang="en"><head><meta name="viewport" content="width=device-width, initial-scale=1"><title>Audit</title></head><body><div id="root"></div><script type="module" src="/assets/app.js"></script></body></html>",
        "assets": {
          "/assets/app.js": "console.log("/");"
        }
      },
      "sources": {
        "files": {
          "src/pages/Home.tsx": "export function Home() { return <button style={{ color: '#ff00ff' }}>Hi</button>; }"
        }
      }
    }

Purpose: Run the shared Decantr project audit remotely by compiling hosted execution packs from the posted essence and optionally replaying runtime verification against posted dist and source snapshots.
Schema: `project-audit-report.v1.json`
Shared Definitions: `verification-report.common.v1.json`
Notes: The `dist` object is optional. Without it, hosted audit still checks schema, topology, and compiled-pack presence, but runtime verification remains pending. The `sources` object is also optional and lets hosted audit aggregate source-level verifier findings from posted source files.

## Showcase Benchmark Surfaces

    GET /showcase/manifest
    GET /showcase/shortlist
    GET /showcase/shortlist-verification

Purpose: Inspect the audited showcase corpus, shortlist metadata, and the schema-backed shortlist verification report.
Schemas: `showcase-manifest.v1.json`, `showcase-shortlist.v1.json`, `showcase-shortlist-report.v1.json`
Shared Definitions: `verification-report.common.v1.json`

## Registry Intelligence Summary

    GET /intelligence/summary?namespace=@official

Purpose: Read a schema-backed aggregate rollup of public registry intelligence coverage without crawling every item.
Schema: `registry-intelligence-summary.v1.json`
Key totals: `total_public_items`, `with_intelligence`, `recommended`, `authored`, `benchmark`, `hybrid`, `smoke_green`, `build_green`, `high_confidence`
Per-type rollups: `by_type.pattern`, `theme`, `blueprint`, `archetype`, `shell`

## CLI and MCP Equivalents

    decantr search portfolio --type blueprint --sort recommended --recommended --source hybrid
    decantr list blueprints --source authored
    decantr registry summary --namespace @official --json
    decantr registry compile-packs decantr.essence.json --namespace @official --json
    decantr registry get-pack manifest --namespace @official --json
    decantr registry get-pack page home --namespace @official --json
    decantr registry critique-file src/pages/Home.tsx --namespace @official --json
    decantr registry audit-project --namespace @official --json
    pnpm audit:public-api

- `decantr_search_registry`
- `decantr_get_registry_intelligence_summary`
- `decantr_get_showcase_benchmarks`
- `decantr_get_execution_pack`
- `decantr_compile_execution_packs`
- `decantr_critique`
- `decantr_audit_project`

Browse Schemas Open Registry View Repo