Developer Resources

Use this page to find the right Honest UI resource for your task. The detailed sections below document the public, read-only REST API and Model Context Protocol (MCP) server for people and tools that integrate with Honest UI.

• Add components to a React project: follow the installation guide for CLI commands, project requirements, and package imports.
• Call Honest UI from code: start with the REST API v1 index, then use the OpenAPI 3.1 specification as the complete machine-readable contract.
• Connect an AI agent: give it llms.txt to discover the documentation, or connect an MCP client to the Honest UI MCP server for typed registry tools.
• Contribute to Honest UI: read the contributing guide for the review process, project checks, and contribution guidelines.

The REST API and MCP server are public and read-only. You do not need an Honest UI account or credential to use them.

The current base URL is:

https://www.honestui.com/api/v1

The existing /r/* and /init URLs remain available for CLI and registry compatibility. New HTTP integrations should use /api/v1 so their major API version is explicit.

The documented API is public and read-only. Requests do not require an account and do not carry a key, token, session cookie, or other credential. Use the Honest UI developer resource index, agent skill, and llms.txt for discovery.

Honest UI also publishes a public, read-only Model Context Protocol server at:

https://www.honestui.com/mcp

Use the Streamable HTTP transport. The server implements MCP protocol version 2026-07-28 and supports the standard server/discover, tools/list, and tools/call methods. It does not require a credential.

Use list_registry_items when an agent needs valid Honest UI component names. Its optional query argument filters names by a case-insensitive substring. Then call get_registry_item with an exact returned name to retrieve the shadcn-compatible source files and dependencies. Both tools are read-only and idempotent. If get_registry_item reports that a name is missing, call list_registry_items instead of guessing another name.

MCP clients can also discover the connection without manual configuration:

• AI Catalog — the domain-level discovery document that lists Honest UI MCP servers.
• MCP Server Card — the SEP-2127 card describing identity, transport, and supported protocol versions, served as application/mcp-server-card+json.

The REST API is free and read-only, and clients are expected to keep request rates reasonable. Responses from /api/v1 carry rate-limit headers describing the documented fair-use window:

The window is one minute per client address. When a client exceeds it, the API responds with 429 using the standard problem-details body, code RATE_LIMIT_EXCEEDED, and a Retry-After header giving the number of seconds to wait.

Enforcement is best-effort and applied per serving instance on horizontally scaled hosts, so a busy client may see RateLimit-Remaining reset early or never reach zero before receiving a 429. Treat the headers as advisory pacing guidance rather than a hard guarantee, and back off whenever Retry-After is present.

Versioned API errors follow RFC 9457 Problem Details for HTTP APIs and use Content-Type: application/problem+json. Every problem includes the standard type, title, status, detail, and instance members plus stable code, message, and resolution extensions.

{
  "type": "https://www.honestui.com/docs/developers#registry-item-not-found",
  "title": "Registry item not found",
  "status": 404,
  "detail": "No public Honest UI registry item is named \"missing-item\".",
  "instance": "https://www.honestui.com/api/v1/registry/missing-item",
  "code": "REGISTRY_ITEM_NOT_FOUND",
  "message": "Registry item not found",
  "resolution": "GET /api/v1/registry to find a valid item name."
}

Clients should branch on the HTTP status and code, not parse the human-readable detail, message, or resolution strings.

Registry item not found

REGISTRY_ITEM_NOT_FOUND uses HTTP 404 when no public registry item matches the requested name. Retrieve /api/v1/registry before retrying with a valid name.

Invalid preset configuration

INVALID_PRESET_CONFIGURATION uses HTTP 400 when an /api/v1/init query parameter has an unsupported value. Read /openapi.json for the accepted values.

Invalid only value

INVALID_ONLY_VALUE uses HTTP 400 when the only query parameter contains a registry subset other than theme, font, or fonts.

API route not found

API_ROUTE_NOT_FOUND uses HTTP 404 when the requested /api/v1 path is not part of the published contract. Start at /api/v1 or inspect /openapi.json.

Method not allowed

API_METHOD_NOT_ALLOWED uses HTTP 405 when a client sends a modifying method to a read-only resource. The response includes Allow: GET, HEAD.

Rate limit exceeded

RATE_LIMIT_EXCEEDED uses HTTP 429 when a client exceeds the documented fair-use window. Read the Retry-After header, wait that many seconds, and resume at the pace published in RateLimit-Policy. See Fair use and rate limits.

Honest UI versions the REST API in the URL path. The current major version is v1. Additive fields and endpoints may be introduced within v1; clients should ignore JSON object members they do not recognize. A change that removes or renames a documented field or changes its meaning requires a new major path such as /api/v2.

The X-Api-Version response header identifies the major version. The OpenAPI info.version field identifies the contract release within that major version.

No /api/v1 endpoint is currently deprecated or scheduled for retirement.

Every versioned API response links to this policy with Link: <https://www.honestui.com/docs/developers#deprecation-policy>; rel="deprecation"; type="text/html". When an endpoint is scheduled for deprecation, Honest UI will add the RFC 9745 Deprecation header using its Structured Field date syntax and publish a migration guide with the replacement and effective date.

Honest UI commits to a minimum notice period: a deprecation will be announced, and the Deprecation header published, at least 180 days before the endpoint's documented retirement date. If a deprecated endpoint is scheduled to stop responding, Honest UI will also send the RFC 8594 Sunset header with that retirement date. A Sunset date will never be earlier than its Deprecation date, and never earlier than the end of that 180-day notice period.

Until those headers and dates are published, clients should not infer a retirement date.

• Honest UI developer resource index
• OpenAPI specification
• MCP Streamable HTTP endpoint
• MCP Server Card
• AI Catalog
• Documentation index
• Full documentation snapshot
• Honest UI agent skill
• Agent Skills discovery index
• XML sitemap

• Honest UI installation guide
• Official honestui package on npm
• Honest UI source repository

Use the GitHub repository to report a contract or documentation problem.