# API

> The HextaUI HTTP API and OpenAPI spec: registry and docs endpoints, authentication with sessions and API tokens, Pro blocks and error responses.

Docs: https://hextaui.com/docs/api
Markdown: https://hextaui.com/docs/api.md

Everything on HextaUI is also available over HTTP. The registry and docs are static JSON and Markdown files that need no key. Account and Pro endpoints use your sign-in session or an API token.

Assistants that speak MCP can use the same data as tools through the [HextaUI MCP server](https://hextaui.com/docs/mcp) instead.

## OpenAPI spec

The HextaUI API is described by an OpenAPI 3.1 document at `https://hextaui.com/openapi.json`. Every operation has an `operationId`, typed parameters and response schemas, so you can generate a client or hand it to an agent as function-calling tools.

## Public endpoints

- `GET /r/registry.json` lists every registry item.
- `GET /r/{name}.json` returns one item with the full source of each file.
- `GET /mcp/index.json` lists every component, hook, utility and guide with its category, description and examples.
- `GET /docs/{slug}.md` returns a docs page as Markdown. `/llms.txt` links to all of them.
- `POST /mcp` is the Streamable HTTP endpoint of the MCP server.

```bash
curl https://hextaui.com/r/button.json
```

## Authentication

Sign in with GitHub or Google on the [account page](https://hextaui.com/account). The browser then holds a session cookie that the account endpoints read. Only pages on hextaui.com can call the endpoints that change something.

Pro accounts can create API tokens on the same page. Send one as `Authorization: Bearer hxt_…` to install Pro blocks from the shadcn CLI or a script.

Agents can read the step-by-step guide at `https://hextaui.com/auth.md`, and the token rules are published as protected-resource metadata at `https://hextaui.com/.well-known/oauth-protected-resource`. A 401 from a Pro endpoint links to it in its `WWW-Authenticate` header.

## Account endpoints

- `GET /api/account` returns whether the account owns Pro and which providers are linked.
- `POST /api/checkout` starts a Pro checkout and returns its URL.
- `GET /api/tokens` and `POST /api/tokens` list and create API tokens.
- `DELETE /api/tokens/{id}` deletes one.
- `GET /api/auth/get-session` returns the current session, or `null`.

## Pro endpoints

- `GET /r/pro/{name}.json` returns a Pro block as a shadcn registry item.
- `GET /api/pro/blocks/{name}` returns the source files of a Pro block.

```json title="components.json"
{
  "registries": {
    "@hextaui-pro": {
      "url": "https://hextaui.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${HEXTAUI_PRO_TOKEN}"
      }
    }
  }
}
```

## Errors

Errors use RFC 9457 problem details with the `application/problem+json` type. Each one has a stable `code`, a `detail` that says what went wrong and a `resolution` that says how to fix it.

- `bad_request` (400): Bad request.
- `unauthorized` (401): Unauthorized.
- `invalid_signature` (401): Invalid signature.
- `forbidden` (403): Forbidden.
- `pro_required` (403): HextaUI Pro required.
- `not_found` (404): Not found.
- `method_not_allowed` (405): Method not allowed.
- `token_limit` (400): Token limit reached.

```http
HTTP/2 401
Content-Type: application/problem+json

{
  "type": "https://hextaui.com/docs/api#errors-unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "HextaUI Pro items need a signed-in session or an API token.",
  "resolution": "Send Authorization: Bearer <token> with a token from https://hextaui.com/account, or sign in there.",
  "docs": "https://hextaui.com/docs/api#errors",
  "error": "Unauthorized"
}
```

## SDK and tools

There is no separate SDK package. The shadcn CLI is the client for the registry, the MCP server is the client for assistants, and the OpenAPI spec generates a typed client in any language.