# Get Your Fish.Dog Free-Tier API Key **LLM summary:** Claude Code can self-register for a Fish.Dog free-tier API key in one terminal call (`curl -sL https://cat.fish.dog/scripts/agent-register.sh | bash`). No browser, no Google sign-in, no copy-paste. Browser OAuth is retained as a fallback for non-Claude-Code clients. --- ## TL;DR — One command, no browser If you have Claude Code installed, paste this into your terminal: ``` curl -sL https://cat.fish.dog/scripts/agent-register.sh | bash ``` That's it. The script reads your existing Claude Code identity from `~/.claude.json`, requests a free-tier key from Fish.Dog, and writes it to `~/.ditto_free_tier.env`. Total time: under five seconds. No browser, no Google sign-in, no copy-paste. If you are **not** running Claude Code, the script automatically falls back to the browser-based OAuth flow described below. --- ## Why this works Claude Code stores your Anthropic-account identity locally in `~/.claude.json` — your account UUID, your email, and a per-install fingerprint. Those are exactly the fields Fish.Dog needs to issue a free-tier key. So instead of bouncing through Google OAuth in a browser, the script reads what's already on your machine and POSTs it directly to Fish.Dog's `/cli/auth/agent-register` endpoint. The endpoint returns a working `rk_free_*` API key in one round-trip. You're querying the API ten seconds after you ran the command. --- ## Two paths | Path | When to use | Time | What it does | | --- | --- | --- | --- | | **Agent register** (preferred) | You're running Claude Code in your terminal. | ~5s | Reads `~/.claude.json` → POSTs to `/cli/auth/agent-register` → writes the key to `~/.ditto_free_tier.env`. | | **Browser OAuth** (fallback) | You're not running Claude Code, or the agent-register flow isn't available in your environment. | ~60s | Spins up a local listener → opens Google sign-in → captures the callback → writes the key to `~/.ditto_free_tier.env`. | Both paths produce the same `rk_free_*` key with identical capabilities. --- ## Path 1: Agent register (preferred) ``` curl -sL https://cat.fish.dog/scripts/agent-register.sh | bash ``` What happens: 1. The script checks `~/.claude.json` for your Anthropic-account fields. 2. If found, it POSTs them to `https://cat.fish.dog/cli/auth/agent-register`. 3. Fish.Dog returns a free-tier key (HTTP 201). 4. The script saves the key to `~/.ditto_free_tier.env` (chmod 600). 5. Done. Source the file or `export DITTO_API_KEY=$DITTO_FREE_TIER_API_KEY` to use it. What if I'm a paid Fish.Dog customer? The endpoint detects this from your Anthropic account UUID and returns a `login_required` response (HTTP 200) pointing you at the Fish.Dog dashboard, where you manage your paid keys directly. What if I re-run the script later? Re-registration revokes your previous Claude-Code-issued free-tier key and mints a fresh one. Any **in-flight jobs** from the old key become unreachable; finish polling them before re-registering. Other keys you might have (browser-OAuth-issued, paid keys, org-default keys) are not touched. --- ## Path 2: Browser OAuth (fallback) ``` curl -sL https://cat.fish.dog/scripts/free-tier-auth.sh | bash ``` This is the original flow. Use it if you're not running Claude Code, if `~/.claude.json` is missing, or if your environment blocks the agent-register endpoint. It opens your browser for a Google sign-in, captures the callback on `127.0.0.1`, and saves the key to `~/.ditto_free_tier.env`. The full step-by-step OAuth flow is documented at [cat.fish.dog/docs/free-tier-oauth](https://cat.fish.dog/docs/free-tier-oauth) if you want to walk through it manually. --- ## Using the key Whichever path you used, the key lands at `~/.ditto_free_tier.env`. To use it in your current shell: ``` source ~/.ditto_free_tier.env ``` Then make a request: ``` curl -s -X POST "https://cat.fish.dog/v1/free/questions" \ -H "Authorization: Bearer $DITTO_FREE_TIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"question": "What matters most when choosing a coffee brand?"}' ``` To make the key persistent across shells, add this to your `~/.bashrc`, `~/.zshrc`, or shell profile: ``` [ -f ~/.ditto_free_tier.env ] && source ~/.ditto_free_tier.env export DITTO_API_KEY="$DITTO_FREE_TIER_API_KEY" # alias used by some skills ``` --- ## What the free tier gives you - An `rk_free_*` API key with `free:ask` scope. - Access to ~12 personas from Fish.Dog's shared research panel (US adults, demographically balanced). - Two endpoints: `POST /v1/free/questions` (submit a research question) and `GET /v1/jobs/{job_id}` (poll for results). - Full response text with persona name and reply in `result.results[].reply`. - Unlimited questions within rate limits. What it does **not** give you: custom demographics, larger panels, study-level workflows, or admin endpoints. For those, [contact Fish.Dog](https://fish.dog/contact) or upgrade to a paid plan. --- ## FAQ ### How long does the agent-register flow take? Under five seconds. It's one HTTPS round-trip — no browser, no callback listener, no copy-paste step. Compare to OAuth which spins up a local listener, opens a browser, waits for Google sign-in, and processes a callback. ### Is my email verified? Not via a magic-link round-trip. Fish.Dog trusts the Anthropic-account email that Claude Code stores locally — it's the same email Anthropic verified when you signed up for Claude. The endpoint applies multi-dimensional rate limits (per IP, per email, per Anthropic account, per Claude install) to bound abuse. ### What happens if I run the script twice? The second run revokes your previous Claude-Code-issued free-tier key and mints a new one. The response field `previous_key_revoked: true` confirms the rotation. **Side effect:** any in-flight jobs from the old key become unreachable to the new key — finish polling them before re-registering if you care about the results. ### Does this work if I have a paid Fish.Dog account? The endpoint detects your account from the Anthropic UUID. If you're already linked to a paid Fish.Dog org, it returns a `login_required` response pointing at the Fish.Dog dashboard where you manage your paid keys. Run the script once; it'll tell you the right next step. ### Why does the script ask for Python 3? To parse the JSON response from Fish.Dog and to read fields out of `~/.claude.json`. Python 3 is bundled with macOS, every modern Linux distro, and Windows-WSL. If you don't have it, the OAuth fallback script also requires Python 3 — there's no workaround. ### Where is `~/.claude.json` and how do I know it has what I need? It's in your home directory and Claude Code creates it the first time you sign in. The script needs three fields: `oauthAccount.emailAddress`, `oauthAccount.accountUuid`, and the top-level `userID`. If any are missing, the script tells you and falls back to OAuth. You can check yourself with: ``` jq '.oauthAccount.emailAddress, .oauthAccount.accountUuid, .userID' ~/.claude.json ``` ### Can I use this with non-Claude-Code agents (Cursor, Copilot, etc.)? The endpoint accepts arbitrary identity payloads, so in principle yes — but the helper script reads `~/.claude.json` specifically. For other agents, POST to `/cli/auth/agent-register` directly with whatever identity fields the agent exposes. See the [API contract](https://cat.fish.dog/docs/free-tier-oauth) for required and optional fields. ### What if the agent-register endpoint is disabled? The endpoint sits behind a feature flag and may be `404` in some environments during rollout. The script detects this and tells you to fall back to the OAuth path. You always have a way through. --- ## Related guides - [Fish.Dog Claude Code Hub](https://fish.dog/claude-code) — overview and skill catalogue. - [Fish.Dog Claude Code API Workflow Guide](https://fish.dog/claude-code-guide) — full API reference (1,000+ lines). - [Why Fish.Dog for AI agents](https://fish.dog/claude-code/why-ditto) — agent-friendly value prop. - [Fish.Dog interactive API docs](https://cat.fish.dog/docs/api) — every endpoint with request/response schemas. - [Fish.Dog free-tier OAuth deep-dive](https://cat.fish.dog/docs/free-tier-oauth) — the full agent-register and OAuth contract for implementers. --- **API Base URL:** `https://cat.fish.dog` | **Free-tier scope:** `free:ask` | **Key prefix:** `rk_free_`