For the last two years, every "AI agent gets a research API" story has had the same friction at step one: a human has to sign up. Open a browser, click through Google OAuth, fill in an org name, paste the key back into the terminal. For an autonomous agent — Claude Code halfway through a research task, a Cursor session running customer-discovery questions, an unattended cron job assembling competitive intelligence — that human-in-the-loop step kills the workflow.
We removed it. Today, AI agents provision their own FishDog free-tier API key directly from the terminal, in one HTTPS round-trip, with zero human intervention.
The one command
If you're running Claude Code, this is the entire onboarding flow:
curl -sL https://cat.fish.dog/scripts/agent-register.sh | bash
Under five seconds later, you have a working rk_free_* key saved to ~/.ditto_free_tier.env and a sample query you can run against the API. No browser opened. No callback URL captured. No copy-paste. No credit card. No registration form.
What's actually happening
Claude Code already stores your Anthropic-account identity locally in ~/.claude.json — your account UUID, your email, and a per-install fingerprint. Those happen to be exactly the fields FishDog needs to issue a free-tier key. So instead of bouncing through a browser, the script reads what's already on your machine and POSTs it directly to a new endpoint, POST /cli/auth/agent-register. The endpoint validates, mints, and returns. Total wall-clock: typically under three seconds; cap of five.
The key the agent receives is a regular rk_free_* key with the free:ask scope. It authenticates against POST /v1/free/questions (submit a research question to a shared panel of ~12 demographically-balanced US adult personas) and GET /v1/jobs/{job_id} (poll for results). It's the same key, the same API surface, the same response shape that browser-OAuth users have had for months — just provisioned in a single round-trip instead of three.
Why this matters for AI agents
This is the difference between "an agent can use FishDog if a human sets it up first" and "an agent can use FishDog autonomously." The implications stack up quickly:
Claude Code workflows that involve research. A skill like
ditto-product-researchcan now bootstrap itself the first time it's invoked. No "first, please get an API key" warning. The agent reads~/.claude.json, registers, and starts the study.Headless / CI / cron contexts. An unattended agent on a server (no human present, no browser) can register itself with the same one-liner. As long as
~/.claude.jsonexists from the Claude Code install, it works.Try-before-you-buy at the speed of curiosity. A developer prototyping an AI-agent integration with FishDog doesn't need to commit a credit card, fill in a sales form, or wait for an account-provisioning email. They run one command and they're querying personas.
Agent-to-agent composition. Other AI agents — Cursor, Copilot, custom orchestrators — can POST directly to
/cli/auth/agent-registerwith whatever identity fields they expose. The endpoint is identity-agnostic; only theagent-register.shhelper script is Claude-Code-specific.
The pattern we're committing to here is broader than this single release. Identity that already exists on the machine should be sufficient for agents to bootstrap their own access to agent-friendly APIs. We expect this to become the default pattern across the AI-agent ecosystem; we want FishDog to be one of the first APIs that ships it cleanly.
What re-running does
If you re-run the script — same machine, same identity, fresh shell — the prior free-tier key is revoked and a new one is minted. The response carries previous_key_revoked: true so callers can detect the rotation. Replace any cached credentials.
Critically, rotation does not invalidate access to your prior work. A replacement free-tier key for the same FishDog user can still poll free-tier jobs that were created with the prior key (GET /v1/jobs/{job_id} returns 200, not 403). Research groups, studies, direct-question runs, and asked questions were always user/org-scoped and survive rotation the same way. If your agent rotates keys mid-task, the task keeps working.
What happens on a paid account
If your Anthropic account is linked to a FishDog organisation that's already on a paid plan, the endpoint detects it and the response depends on your billing mode:
Stripe-billed paid orgs: the endpoint returns a managed paid
rk_live_*key with broader scopes. Your agent gets a working paid key without a re-OAuth or dashboard round-trip. This is the post-upgrade refresh path — designed exactly for the moment a user upgrades and wants their agent to keep working.Invoiced or other non-Stripe paid orgs: the endpoint returns
status="login_required". Manage keys through the FishDog dashboard; the account manager handles issuance.
Fallback for non-Claude-Code clients
If ~/.claude.json isn't present on the machine — you're not running Claude Code — the script detects it and prints the existing browser-OAuth one-liner. The OAuth path is unchanged and remains fully supported. There is no broken signup path.
Where to start
The fastest way to try this: open a Claude Code terminal and paste the one-liner above. Then read the full guide for the contract details, rate limits, FAQ, and the integration patterns that work best with synthetic-persona research.
---