# Developer Resources

> Choose the Honest UI CLI, REST API, MCP server, and agent documentation for your development task.

Source: https://www.honestui.com/docs/developers

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.

## Choose the right starting point [#choose-the-right-starting-point]

* **Add components to a React project:** follow the [installation guide](/docs/get-started) for CLI commands, project requirements, and package imports.
* **Call Honest UI from code:** start with the [REST API v1 index](/api/v1), then use the [OpenAPI 3.1 specification](/openapi.json) as the complete machine-readable contract.
* **Connect an AI agent:** give it [llms.txt](/llms.txt) to discover the documentation, or connect an MCP client to the [Honest UI MCP server](#honest-ui-mcp-server) for typed registry tools.
* **Contribute to Honest UI:** read the [contributing guide](/docs/contributing) 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.

## Honest UI REST API v1 [#honest-ui-rest-api-v1]

The current base URL is:

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

| Resource                      | Purpose                                                                            |
| ----------------------------- | ---------------------------------------------------------------------------------- |
| `GET /api/v1`                 | Discover the current version, documentation, specification, and primary resources. |
| `GET /api/v1/registry`        | Retrieve the public shadcn-compatible registry catalog.                            |
| `GET /api/v1/registry/index`  | List public registry item names and types.                                         |
| `GET /api/v1/registry/{name}` | Retrieve one public registry item.                                                 |
| `GET /api/v1/colors/{name}`   | Retrieve the registry base-color definition.                                       |
| `GET /api/v1/init`            | Generate an initialization preset from documented query parameters.                |

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.

## Authentication and access [#authentication-and-access]

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](/developers), [agent skill](/skill.md), and [llms.txt](/llms.txt) for discovery.

## Honest UI MCP server [#honest-ui-mcp-server]

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

```text
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](/.well-known/ai-catalog.json) — the domain-level discovery document that lists Honest UI MCP servers.
* [MCP Server Card](/mcp/server-card) — the SEP-2127 card describing identity, transport, and supported protocol versions, served as `application/mcp-server-card+json`.

## Fair use and rate limits [#fair-use-and-rate-limits]

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:

| Header                | Meaning                                           |
| --------------------- | ------------------------------------------------- |
| `RateLimit-Limit`     | Maximum requests per client per window (600).     |
| `RateLimit-Remaining` | Requests left in the current window.              |
| `RateLimit-Reset`     | Unix timestamp in seconds when the window resets. |
| `RateLimit-Policy`    | The published quota expression: `600;w=60`.       |

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.

## JSON error responses [#json-error-responses]

Versioned API errors follow [RFC 9457 Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457) 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.

```json
{
  "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]

`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]

`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]

`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]

`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 [#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]

`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](#fair-use-and-rate-limits).

## Versioning and compatibility [#versioning-and-compatibility]

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.

## Deprecation policy [#deprecation-policy]

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.

## Agent-readable resources [#agent-readable-resources]

* [Honest UI developer resource index](/developers)
* [OpenAPI specification](/openapi.json)
* [MCP Streamable HTTP endpoint](/mcp)
* [MCP Server Card](/mcp/server-card)
* [AI Catalog](/.well-known/ai-catalog.json)
* [Documentation index](/llms.txt)
* [Full documentation snapshot](/llms-full.txt)
* [Honest UI agent skill](/skill.md)
* [Agent Skills discovery index](/.well-known/agent-skills/index.json)
* [XML sitemap](/sitemap.xml)

## CLI and package resources [#cli-and-package-resources]

* [Honest UI installation guide](/docs/get-started)
* [Official `honestui` package on npm](https://www.npmjs.com/package/honestui)
* [Honest UI source repository](https://github.com/honestui/honestui)

Use the [GitHub repository](https://github.com/honestui/honestui) to report a contract or documentation problem.