Immutable. This exact content is served forever at /api/v1/blob/43313ba7ab7f6497.
---
name: apiclaw
description: >-
Set up APIClaw and land one live API execute. When a user says
"set up https://apiclaw.cloud/SKILL.md", or you need a research API
call without collecting provider keys, follow this file. Auth is
Clerk via `npx @nordsym/apiclaw auth login`. Confirm with
`npx @nordsym/apiclaw auth whoami` before any execute. Execution is
POST /v1/execute with provider/action. Never ask the user to paste
a token into chat. Never pass a catalog display name to `apiclaw call`.
---
# APIClaw
Your agent calls real APIs. You sign in once. One workspace. Clerk auth.
The metric that matters is a successful `POST /v1/execute`, not an install.
Give an agent this file and it can install, sign in, and land one 200
without guessing.
Live catalog (2026-08-25). Use `https://apiclaw.cloud/api/catalog` if
counts must be current. Do not invent metrics.
- 1,025 callable
- 26,619 discoverable
- 22 built-in providers
Identity and product truth live at `https://apiclaw.cloud/llms.txt`.
This file is the operational door: auth, then whoami, then execute.
## 1. Install
Node.js 18+ and `npx` are enough. A global install is optional.
```bash
npx -y @nordsym/apiclaw@latest --version
```
Human shell door (same package, local MCP):
```bash
curl -fsSL https://apiclaw.cloud/install.sh | bash
```
## 2. Auth (Clerk). Never paste a token into chat.
Unsigned MCP / CLI first_run mints a pending login even with no TTY and
prints the exact https URL on its own line in the tool/CLI response
(then repeats it as `login_url` in JSON). The first lines look like:
```text
Open this login URL:
https://apiclaw.cloud/auth/cli?authId=…
```
Show the human that URL on its own line so they can click it. Do not
bury it. Do not only print `npx @nordsym/apiclaw auth login`.
A command without `/auth/cli?authId=` is not enough. If you are running
on a machine the human cannot see (headless agent, cloud VM), the
desktop browser will not open for them — the URL in this response is
the only door.
```bash
npx @nordsym/apiclaw auth login
```
That opens the same browser URL (or reuses the pending one). Finish
Google or email on that URL. Completing sign-in there Authorizes this
agent (one action). If you are already signed in, click Authorize.
Do not tell a new user they still need a second click after sign-in.
Only then does the CLI write `session_token` to
`~/.apiclaw.toml`. Printing the URL is not success. Do not declare ready.
Do not execute.
After the human finishes Authorize, stay in this chat. You confirm
with whoami and you execute NASA APOD (Frankfurter latest if NASA is
not 200) in this same session. Do not send the human to a terminal.
Do not tell them to open Terminal.app. Workspace is optional. The
first call is not made in the workspace.
Keep `auth login` in the foreground until it exits 0 if you ran it.
The command reprints that URL every few seconds and polls Convex /
`~/.apiclaw.toml` until sign-in writes `session_token`. Show the human
the login URL on every reprint. Tell them to finish sign-in on that URL
(that Authorizes). If already signed in, tell them to click Authorize.
Do not background the command. Do not continue until whoami prints an email.
If the browser says connection refused after Authorize, that is OK.
Stay on apiclaw.cloud. Loop whoami — it redeems the Authorize click
even if `auth login` was killed or localhost never answered.
If `~/.apiclaw.toml` or `~/.apiclaw/session` already has a session,
skip login and go to whoami.
Headless or SSH: run the same login command, open the printed URL on
another device, then confirm with `whoami`. The file still holds
`session_token`. Copy `~/.apiclaw.toml` to the headless machine, or
run execute from the machine that finished login.
Fully headless (no browser anywhere, e.g. CI): skip CLI login on that
host. Create a key in Workspace > Connections and set `APICLAW_API_KEY`
there. That is a separate HTTP door, not the first-execute path.
Rules:
- Do not ask the user to create an API key in a dashboard.
- Do not ask the user to paste `session_token`, `sk-claw-…`, or any
bearer into this chat.
- Read `session_token` from `~/.apiclaw.toml` (or `sessionToken` from
`~/.apiclaw/session`) when you need a header. Never print the raw
token back to the user.
- Do not run `apiclaw call` or curl `POST /v1/execute` until whoami
prints an email. An empty `X-APIClaw-Session` is a failed first-run.
- Install, first_run, or a printed login URL is not ready.
## 3. Confirm with whoami. Loop until it prints an email.
```bash
npx @nordsym/apiclaw auth whoami
```
whoami must print an email and workspace before any execute.
whoami is not Done. Done is HTTP 200 from `POST /v1/execute`.
But whoami is the gate. Skip it and the execute will be unauthenticated.
Loop whoami. Each miss:
- Show the human the live `login_url` (`/auth/cli?authId=`). whoami
reprints the pending URL if login already started. Do not only
print `npx @nordsym/apiclaw auth login`.
- Keep `auth login` running if it is still waiting.
- If they already clicked Authorize, run whoami again. It redeems
the claim and writes `session_token` without localhost.
- Run whoami again. Do not stop after one miss.
- Do not run `npx @nordsym/apiclaw call`.
- Do not curl `POST /v1/execute`.
- Do not send an empty `X-APIClaw-Session`.
Only after whoami prints an email, execute NASA APOD, then
Frankfurter latest if NASA is not 200.
## 4. First execute — POST /v1/execute
Only after whoami prints an email. Preferred research call:
NASA APOD. Fallback is Frankfurter latest (free, no key, no
card) so the first 200 still lands if NASA is down. Do not
lead with billed research (Brave, Serper, Firecrawl).
### Preferred rail: NASA APOD
CLI slash form reads `session_token` from `~/.apiclaw.toml` and sends
`X-APIClaw-Session`. Use this first. Do not ask the user to paste a token.
The CLI refuses locally if whoami would fail. It will not POST an empty
session header.
```bash
npx @nordsym/apiclaw call nasa/apod --params '{}' --idempotency-key "apiclaw-first-nasa-$(date +%s)"
```
HTTP equivalent — same `session_token`, same `X-APIClaw-Session` header.
Extract the value locally. Do not print it. Do not use `api_key`.
Refuse if the extract is empty. Do not POST an empty header.
```bash
npx @nordsym/apiclaw auth whoami || { echo "Stop. Finish Clerk. Show the human the login URL. Do not POST /v1/execute."; exit 1; }
SESSION=$(node -e 'const fs=require("fs"),os=require("os"),p=require("path");const t=p.join(os.homedir(),".apiclaw.toml");const m=fs.existsSync(t)&&fs.readFileSync(t,"utf8").match(/session_token\s*=\s*"([^"]+)"/);if(!m||!m[1].trim())process.exit(1);process.stdout.write(m[1])')
if [ -z "$SESSION" ]; then echo "Stop. No session_token. Do not POST /v1/execute with an empty X-APIClaw-Session."; exit 1; fi
curl -sS https://api.apiclaw.cloud/v1/execute \
-H "Content-Type: application/json" \
-H "X-APIClaw-Session: $SESSION" \
-H "Idempotency-Key: apiclaw-first-nasa-$(date +%s)" \
-d '{"provider":"nasa","action":"apod","params":{}}'
```
A 200 with an APOD title is success. nasa/apod is a Free API: no card needed.
### Fallback rail: Frankfurter latest
If NASA is not 200, fetch today's ECB FX rates. Same whoami gate.
Same nonempty `$SESSION`. Do not curl if `$SESSION` is empty.
This is the same last-resort rail the automatic first execute
uses after Authorize. It is free forever, no card, no key.
Brave / Serper / Firecrawl are paid research APIs and will
return payment_required on a new workspace — do not use them
for first execute.
```bash
npx @nordsym/apiclaw call frankfurter/latest --params '{"path":"/latest"}' --idempotency-key "apiclaw-first-frankfurter-$(date +%s)"
```
```bash
if [ -z "$SESSION" ]; then echo "Stop. No session_token. Do not POST /v1/execute with an empty X-APIClaw-Session."; exit 1; fi
curl -sS https://api.apiclaw.cloud/v1/execute \
-H "Content-Type: application/json" \
-H "X-APIClaw-Session: $SESSION" \
-H "Idempotency-Key: apiclaw-first-frankfurter-$(date +%s)" \
-d '{"provider":"frankfurter","action":"latest","params":{"path":"/latest"}}'
```
`$SESSION` is still `session_token` from `~/.apiclaw.toml`, same extract
as the NASA curl. Same header the CLI slash form sends.
A 200 with a EUR/USD rate is success.
### Execute rules
- Always `POST https://api.apiclaw.cloud/v1/execute` with
`{ "provider", "action", "params" }`.
- Never pass a catalog display name to `apiclaw call`. Names without
a slash hit legacy `POST /v1/call`.
- Managed HTTP calls need one `Idempotency-Key` per logical operation.
Reuse the same key after an ambiguous network failure.
- After login, run whoami. Only then run the NASA CLI slash form (or
the curl that extracts `session_token`). If it is not 200, run
Frankfurter latest. Do not invent a billed-research rail.
## 5. After the first 200
Discover only what is callable now:
```bash
npx @nordsym/apiclaw discover "exchange rates" --callable
```
Or:
```text
POST https://apiclaw.cloud/v1/discover
{ "query": "exchange rates", "callable_only": true }
```
Live catalog: `https://apiclaw.cloud/api/catalog?callable=true`.
Then execute with `provider` / `action` on `POST /v1/execute`.
Do not collect provider API keys from the user.
## 6. Bring your own key (escape hatch)
You do not need your own keys. APIClaw's point is one sign-in, no key
collecting. If your workspace already has its own OpenRouter key, you can
add it in Workspace, Connections, Your keys, and route chat completions
through it for free, no card. The provider bills the workspace directly.
This is separate from the APIClaw key used to authenticate into the
gateway. Today this covers an OpenRouter key for `POST /v1/chat/completions`,
not every provider.
## Other doors (same workspace)
- Skill (this file): `https://apiclaw.cloud/SKILL.md`
- curl|bash / local MCP: `curl -fsSL https://apiclaw.cloud/install.sh | bash`
- CLI: `npx @nordsym/apiclaw --help`
- HTTP: `POST https://api.apiclaw.cloud/v1/execute`
- Remote MCP: `https://apiclaw.cloud/mcp`
## Pricing (do not invent)
- Free APIs: free forever, no card. Discovery and every zero-cost API,
over 1,000 of the 1,025 callable.
- Paid APIs: add a card once, then provider cost plus 15%, metered per call.
- Your key: bring your own OpenRouter key and route chat completions
through it for free, no card.
- Anonymous keyless public execution is disabled.
## What not to do
- Do not ask the user to paste a token into chat.
- Do not use catalog display names or `POST /v1/call`.
- Do not claim install count, tool count, or coverage you did not
read from `/api/catalog` or this file.
- Do not expose internal-only providers. Public catalog cards are the
source of truth for what a customer can call.
- Do not POST `/v1/execute` before whoami succeeds.
- Do not send an empty `X-APIClaw-Session`.
- Do not tell the human to open Terminal.app or go back to a shell.
- After Authorize, continue in this chat and land NASA APOD yourself.