# Half Rare public API

Half Rare publishes a read-only discovery API and MCP server. The live Name Picker and Logo Maker are browser products with separate rate-limited compute endpoints that are intentionally excluded from the public automation contract.

Base URL: `https://halfrare.com`

Last updated: 2026-07-27

## Public read-only HTTP endpoints

### `GET /api`

Returns the public API summary and links to machine-readable resources.

### `GET /api/health`

Returns service status, service name and the canonical origin.

### `GET /api/site-index`

Returns the current Name Picker and Logo Maker state, all canonical public routes, additional implementation offers, discovery URLs and claim boundaries.

### `GET /openapi.json`

Returns the OpenAPI 3.1 description for the read-only discovery endpoints and MCP transport.

## MCP

`POST /mcp` accepts public read-only MCP JSON-RPC requests. Discover tools, resources and protocol information through `/.well-known/mcp/server-card.json`, `initialize`, `tools/list` and `resources/list`.

The MCP server returns current product and route context, Product Brand Starter content and deterministic seven-answer build recommendations. It stores no recommendation answers and performs no generation, submission, checkout or purchase.

## Interactive product endpoints

The public browser interfaces use these anonymous, rate-limited endpoints:

- `POST /api/name`: generate name directions from allowlisted taste signals.
- `POST /api/kit/resolve`: resolve visual-taste selections into deterministic Brand DNA.
- `POST /api/kit/suggest`: suggest structured visual-taste selections.
- `POST /api/kit/build`: generate up to three logo directions.

These endpoints consume model capacity, enforce product-specific validation and may return `429` or `503`. They are documented here for transparency, but are excluded from OpenAPI, MCP and WebMCP automation. Agents must use the browser workflow and obtain user approval before starting generation. `/api/kit/direct` is an internal experimental route and is not a public contract.

## Submission, analytics and payment boundaries

The following endpoints are intentionally excluded from the public API and agent tools:

- `POST /api/leads`: validates and stores consented lead and application submissions containing personal data.
- `POST /api/analytics`: accepts typed, PII-safe behavioural events.
- payment, webhook, CAPI, share-signing and other internal infrastructure routes.

An agent must not submit a form or disclose personal data without explicit user approval.

## Discovery

- [Agent guide](https://halfrare.com/agent.md)
- [Full public-page corpus](https://halfrare.com/llms-full.txt)
- [API documentation](https://halfrare.com/api-docs.md)
- [API catalogue](https://halfrare.com/.well-known/api-catalog)
- [OpenAPI description](https://halfrare.com/openapi.json)
- [Authentication policy](https://halfrare.com/auth.md)
- [MCP Server Card](https://halfrare.com/.well-known/mcp/server-card.json)
- [Agent Skills index](https://halfrare.com/.well-known/agent-skills/index.json)
- [Sitemap](https://halfrare.com/sitemap.xml)
- [Crawler policy](https://halfrare.com/robots.txt)
- [IndexNow ownership key](https://halfrare.com/ff2324c801774bec8859f636225cf775.txt)

Every canonical public HTML page is listed in the sitemap and supports `Accept: text/markdown` negotiation. Internal Markdown assets and confirmation pages remain noindex.

## Errors and limits

Unknown routes or unsupported methods return an HTTP or JSON-RPC error. Use bounded timeouts, respect `429` responses, and never treat public discovery as an account, application, order or payment system.