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/.

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
Browse Schemas Open Registry View Repo