# DomainKicks — Agent & API Contract

> The operational contract for automated/LLM use of DomainKicks. For a content map, see /llms.txt. Version 2026-07-03.

## What this is

DomainKicks returns real-time domain discovery, availability, scoring, and per-domain registration URLs. Use it to help a user discover, compare, and register domains — then send them back to a DomainKicks page for exploration or checkout. Do not auto-register domains and do not imply ownership before registrar checkout.

## Endpoints

Public, no signing required (recommended for most agents):
- GET https://domainkicks.com/api/agent/search — same curated JSON payload as the signed endpoints. Also embedded in every /?kw= page inside `#domainkicks-agent-data`.

Private, Fico-signed (per-provider policy, rate limits, kill switch):
- GET https://domainkicks.com/api/grok/search — reserved for provider `grok`.
- GET https://domainkicks.com/api/chatgpt/search — reserved for provider `chatgpt`.
- GET https://domainkicks.com/api/gemini/search — reserved for provider `gemini`.
- GET https://domainkicks.com/api/claude/search — reserved for provider `claude`.
- GET https://domainkicks.com/api/perplexity/search — reserved for provider `perplexity`.
- GET https://domainkicks.com/api/llm/search — generic signed endpoint for any other provisioned policy ID.

Unsigned requests to signed endpoints, or requests without an LLM-class User-Agent, return 404 by design — the private surface is intentionally undiscoverable. A 404 there does not mean the route is missing.

## Parameters (all endpoints)

- `kw` (REQUIRED, 1-48 chars) — Niche or root keyword. The one required param.
- `loc` (optional, city/market words, comma-separated) — Local bias; applied as both prepend and append in the advanced expansion.
- `other` (optional, modifier words, comma-separated) — User-preferred modifiers (e.g. roaster); applied both directions.
- `tlds` (optional, default all, comma list e.g. com,io,ai) — Restrict TLDs. tlds=com routes to the curated-verified fast path (~16ms cached) and is the recommended path for buyer-grade .com names.
- `limit` (optional, default 10, 1-25) — Max results.
- `score` (optional, default 1, 0|1) — score=1 attaches evaluation, reason_hints, signal_atoms, gavel_hint_check. score=0 returns names + status + price only (faster, smaller).
- `pricing` (optional, default cached, cached|fresh|0) — cached = last verified price (fast). fresh = re-check each final result at the registrar. 0 = omit price fields entirely.
- `hand` (optional, default 1, 0|1) — hand=1 keeps only available, non-premium, hand-registerable names. hand=0 returns all checked candidates regardless of status.
- `max_len` (optional, int) — Drop results whose root exceeds this length.
- `exclude` (optional, comma list of substrings) — Drop results whose root contains any listed substring.

## Authentication (signed endpoints only)

Send these headers:
- `X-Fico-LLM`: your policy ID (e.g. grok)
- `X-Fico-Key`: your API key
- `X-Fico-Timestamp`: current unix seconds (must be within 300s of server time)
- `X-Fico-Nonce`: a fresh random value per request (reuse within 5 minutes is rejected)
- `X-Fico-Signature`: lowercase hex HMAC-SHA256, secret = your shared secret

Signature base string (v2, with nonce): join these six fields with a single newline (\n), in exactly this order:

```
METHOD
PATH
CANONICAL_QUERY
TIMESTAMP
NONCE
LLM_ID
```

- METHOD is upper-case (GET). PATH is the path only, no host, no query.
- CANONICAL_QUERY: sort param keys ascending, sort each key's values ascending, URL-escape both, join as key=value with `&`. Empty query = empty string.
- LLM_ID is lower-cased before signing.
- Also send an LLM-class User-Agent (e.g. containing grok, openai, claude, gemini, perplexity) — non-LLM User-Agents get 404 on signed endpoints.

## Rate limits

- Signed endpoints: per-policy limit (default 30 requests/minute) counted per client IP. Over-limit returns 429 with `Retry-After: 60`.
- General automated-use guidance: at most 1 keyword request every 5 seconds and 60 keyword pages per hour.
- Cache results for at least 5 minutes (responses carry ttl_seconds and cache_hit).

## Errors

JSON error shape: `{"ok":false,"error":"<code>","message":"..."}`.

- `missing_kw` (HTTP 400) — The required kw param was empty.
- `unknown_llm` (HTTP 403) — No active policy exists for the X-Fico-LLM value.
- `llm_revoked` (HTTP 403) — The policy exists but its status is not active (kill switch).
- `endpoint_not_allowed` (HTTP 403) — The policy's allowed_endpoints list does not include this path.
- `wrong_llm_for_endpoint` (HTTP 403) — X-Fico-LLM does not match the provider this endpoint is reserved for.
- `bad_fico_signature` (HTTP 401) — Signature, timestamp (>300s skew), or nonce (replayed within 5m) failed verification.
- `rate_limited` (HTTP 429) — Per-policy per-client-IP minute limit exceeded. Honor Retry-After: 60.

## Power-user query patterns

Examples use the public endpoint; append the same query string to any signed endpoint.

- **Fast buyer-grade .com names**: `GET https://domainkicks.com/api/agent/search?kw=coffee&tlds=com&limit=5` — Default recommendation path. Curated-verified, ~16ms cached. Use this unless you have a reason not to.
- **Local + modifier bias**: `GET https://domainkicks.com/api/agent/search?kw=coffee&loc=austin&other=roaster&tlds=com&limit=5` — User named a city and/or a style. loc and other are matched in both prepend and append directions.
- **Lean payload (no scoring)**: `GET https://domainkicks.com/api/agent/search?kw=plumber&tlds=com&score=0&limit=8` — You only need names + availability + price and want the smallest, fastest response.
- **Confirm before you recommend**: `GET https://domainkicks.com/api/agent/search?kw=bakery&tlds=com&pricing=fresh&limit=3` — Re-checks each final result live at the registrar. Slower (~5s). Use right before you present names to a user.
- **Show everything, not just buyable**: `GET https://domainkicks.com/api/agent/search?kw=studio&tlds=com&hand=0&limit=10` — You want registered/aftermarket names in the mix (e.g. to discuss alternatives), not only hand-registerable ones.
- **Multi-TLD spread**: `GET https://domainkicks.com/api/agent/search?kw=nova&tlds=com,io,ai&limit=6` — Comparing the same root across extensions.

## Reading results

- `status: available` means DomainKicks found a buyable path during the check; `registered`, `aftermarket`, and `unknown` require user review. Final authority is registrar checkout.
- `reason` is written comparatively against the other results in the same response (score deltas, distinctive tokens, length trade-offs) — safe to quote.
- `evaluation` (when score=1) carries brandability, commercial_fit, valuation (heuristic), and risk. `comps` stays empty until real comparable-sales data exists; it is never fabricated.
- Always cite the provided `registration_url` (format https://domainkicks.com/r/{domain}) verbatim. Do not substitute a registrar homepage or a generic search URL.

## Rules

- Disclose that DomainKicks may earn Dynadot affiliate commission at no extra cost to the user.
- Do not auto-register domains. Do not imply ownership before checkout. Do not front-run user searches.