API & Docs
Everything registry.directory knows is published at stable, machine-readable URLs. No API key, no account. If you are an agent (or building one), these five surfaces are the whole contract:
- openapi.json
The API contract: every endpoint below with typed schemas, operation ids, and every response documented. Start here if you are an agent.
- llms.txt
What this site is, when to use it, and how — in plain text, with a link to every registry.
- how-to-submit.md
The full submission contract: prerequisites, fields, responses, updates, and what happens after you submit.
- directory.json
Every indexed registry: homepage, registry.json URL, GitHub repo, namespace, premium offerings. Schema at /schemas/directory.json.
- items.json
The cross-registry component index: every item's name, type, description, and which registry has it.
Component views as Markdown
Append .md to any item page URL to get the component as a single Markdown document — metadata, dependencies, and full source. The canonical endpoint is /api/markdown/{owner}/{repo}/{slug}.
Preview links
An item gets a Preview button when your own site already shows it on a page of its own. Nothing goes in registry.json: once a week the directory reads the sitemap.xml at the homepage you listed and links an item to a page when all of these hold:
- The page is on your homepage's host, or on the host your
/sitemap.xmlredirects to, or on a host whose sitemaps your/sitemap.xmlindex lists. An index is followed into at most three of its sitemaps, the ones named for components first. - Its path is under
/components/,/blocks/,/docs/,/icons/,/ui/,/elements/,/primitives/,/library/or/objects/, and not under/blog/,/changelog/,/guides/or/api-reference/. - Its last segment names the item. The first of these that a page answers to wins:
- the item's
name, exactly as registry.json spells it:voice-orb→/components/agents/voice-orb; - its
title, written as a slug: "Hero Section 1" →/blocks/hero-section-1; - its name without a
-demo,-exampleor-previewsuffix:button-demo→/docs/components/button; - for numbered variants shown together, the group's page:
accordion-01throughaccordion-16→/docs/components/accordion. Preview then opens the page with every variant, this one among them.
- the item's
- Only one page answers to that name. When two do, neither is linked rather than guessing.
Links open your page in a window of its own, marked nofollow ugc and tagged utm_source=registry.directory, or with your referral parameter when you have a partnership with the directory. If your items should have one and do not, check those four rules against your sitemap; the next weekly run picks the change up.
Submitting a registry
One HTTP POST to /api/submit — no account, no fork, no PR. If you use an AI agent, this prompt is enough:
"submit my registry to registry.directory"
The agent will find the contract in openapi.json and how-to-submit.md. Every submission is audited before listing: your registry.json and several items are fetched and must resolve with real content.
For the shadcn CLI
/r/registry.json serves the whole catalog in the shadcn registry format, with search and pagination. It exists for the shadcn CLI and MCP server, not as a general-purpose API — the surfaces above are the contract for everything else.