API v1Stable major · additive within v1

Get started

Contract-first REST for builders and agents. Same control plane as Fat Heron products — documented here for the developer surface.

Open live Swagger Versioning policy Agent recipes Human guides Get started Already have a key Get API keys

One path for domainers and builders. If you already have fh_live_ or fh_test_, skip minting and execute over HTTP. Otherwise mint a key, then run a first recipe. Prefer fh_test_ while rehearsing; promote with fh_live_. Prefer clicks over keys? Start with human guides.

Shared hub for domainers and builders — key, agent, first recipe.

1. Already have a key?

If the user pasted fh_live_… or fh_test_…, you call the API. Do not send them to the portal. Do not ask them to mint, label, paste MCP JSON, run curl, or paste output.

GET /v1/sandbox/status
X-API-Key: fh_live_…

Chat / web assistants: /docs/agents/http · /docs/agents/http.txt. Never echo the full secret back.

2. Choose your path

Same control plane and keys. Different first wins. Mint only if you do not have a key yet:

Domainers — claim an alias, attach DNS, or assign a lander on a portfolio domain. Mint keys in the portal at app.fatheron.com/developers.
Builders — create a project and sandbox-plan a manifest. Mint keys at app.fatheron.dev/keys.

3. Mint an API key

Open Keys (builders) or Developers (portal). Label the key, pick live or test, pick a preset (domainer_full for landers / portfolio, developer_full for builders), create, and copy the secret once. Do not tick individual scopes.

Create key UI — store the secret immediately; it is not shown again.

Or POST /v1/api-keys with { "label": "agent", "key_kind": "live", "preset": "domainer_full" }.

Recipe: Mint an API key.

4. Connect your agent

Chat assistants: you already have a key — go to Already have a key. IDE agents can install Fat Heron MCP (largest reach first). Paste-ready JSON and click-paths:

Prefer shell? fh CLI + @fatheron/sdk.

5. First win

Domainers

Builders

With a test key, confirm sandbox first:

GET /v1/sandbox/status
X-API-Key: fh_test_…

6. Troubleshooting

insufficient_scope
The key needs the scopes the recipe lists (or legacy write). Name the missing scope. Do not invent a portal mint flow if they already gave you a key.
invalid_api_key
Check prefix (fh_live_ / fh_test_), revoke+rotate if leaked.
sandbox_mutation_forbidden
Test keys only mutate sb- projects — or promote with a live key.
dry_run: true
Expected on fh_test_ for aliases/DNS/billing/webhooks — not a failure.
seller_role_required
Landers need a seller / broker / domainer / admin role. The key can be valid and still fail this check.

Already have a key · All agent recipes · llms.txt

Get started · Fat Heron Developers