git:20261016.39f91d5 to git:20261026.03f7d4f

# APIClaw Complete Reference

> Your agent calls real APIs. You sign in once.

> https://apiclaw.cloud

## Canonical endpoints

- Website: https://apiclaw.cloud

- Skill: https://apiclaw.cloud/SKILL.md

- Docs: https://apiclaw.cloud/docs

- Catalog: https://apiclaw.cloud/catalog

- Workspace: https://apiclaw.cloud/workspace

- Gateway: https://api.apiclaw.cloud

- Remote MCP: https://apiclaw.cloud/mcp

- npm: https://npmjs.com/package/@nordsym/apiclaw

- GitHub: https://github.com/nordsym/apiclaw

## Current product truth

- Discoverable API definitions: 27,483

- Exact-name source-verified catalog entries: 689

- Managed provider adapter inventory: 22

- Customer-executable provider rails: 19

- Managed execution: available only where a server-side provider is live

- Anonymous keyless public execution: disabled

- Discovery: free after signup

- Free APIs: free forever, no card. Discovery and every zero-cost API, plus up to 25 managed calls capped at $1 provider cost after login.

- Paid APIs: add a card once, then provider cost plus 15%, metered per call.

- Unknown-cost paid actions: blocked rather than estimated

- Anonymous execution: unavailable

Source verification means a current public catalog entry maps to verification evidence by exact name. It does not mean APIClaw will proxy the definition. Runtime execution readiness is shown separately.

## Access paths

### Local MCP

On a machine the human can see:

```bash

npm install -g @nordsym/apiclaw

npx @nordsym/apiclaw auth login

```

On Grok, cloud, or headless: do not run `auth login`. Show the first-line `https://apiclaw.cloud/auth/cli?authId=…` URL from unsigned first_run and stop. After Authorize, whoami + first call in this same chat. Workspace is optional. Terminal.app is not the product.

Best for local MCP-compatible agents. The verified workspace credential is stored in `~/.apiclaw.toml`.

### CLI

```bash

apiclaw --help

```

Best for terminal use, scripts, and CI/CD.

### ACP (Agent Client Protocol)

```bash

npx @nordsym/apiclaw acp

```

Best for Buzz (block.xyz) and other ACP-speaking clients. The ACP client spawns this over stdio; same session-token auth as the CLI. Show the first-line login URL; do not only run `apiclaw auth login`. Prompt grammar: `help`, `discover <query>`, `details <provider>[/<action>]`, `call <provider>/<action> [json]`, `balance`, `status`.

### HTTP gateway

```text

POST https://api.apiclaw.cloud/v1/discover

POST https://api.apiclaw.cloud/v1/execute

POST https://api.apiclaw.cloud/v1/chat/completions

POST https://api.apiclaw.cloud/v1/embeddings

```

Authentication after `apiclaw auth login` (first execute):

```text

X-APIClaw-Session: <session_token from ~/.apiclaw.toml>

```

HTTP/CI key door (not the first-execute path):

```text

Authorization: Bearer sk-claw-...

```

### Remote MCP

```text

https://apiclaw.cloud/mcp

```

Remote MCP supports OAuth 2.1 with PKCE S256 and Streamable HTTP. Public dynamic client registration is closed. Sign in and generate a workspace connector for a new client. Already-registered clients keep working.

Discovery documents:

```text

https://apiclaw.cloud/.well-known/mcp

https://apiclaw.cloud/.well-known/oauth-authorization-server

https://apiclaw.cloud/.well-known/oauth-protected-resource

```

## Authentication

- Signup is required for discovery and execution.

- Unsigned MCP/CLI first_run mints `https://apiclaw.cloud/auth/cli?authId=…` and returns it as the first line of the tool text (and as `login_url`) even with no TTY. Show that first line. Do not only print `npx @nordsym/apiclaw auth login`. Completing Clerk on the login URL Authorizes (one action). If already signed in, click Authorize. After Authorize, retry in this chat: whoami then first call. Confirm with `npx @nordsym/apiclaw auth whoami` — it redeems Authorize without localhost.

- On Grok, cloud, or headless: show the first-line URL and stop. Do not run `auth login` there — that opens a browser they will never get. They open the URL on another device. Workspace is optional. Terminal.app is not the product.

- On a machine with a browser: `npx @nordsym/apiclaw auth login` writes `session_token` to `~/.apiclaw.toml` only after Authorize. The next `POST /v1/execute` sends that value as `X-APIClaw-Session`. On a machine with no browser access at all: create a key in Workspace > Connections and set `APICLAW_API_KEY` in the environment (HTTP/CI door, not first execute).

- Workspace keys use the `sk-claw-...` bearer format.

- Provider credentials remain server-side.

## Discovery

Use `discover_apis(query)` or `POST /v1/discover` to search the registry by capability.

- `callable_only=true` means managed rails or workspace-authenticated public/no-key origins APIClaw can execute now.

- Use `get_api_details` to inspect auth, docs, params, and readiness before execution.

## Managed execution

Use `call_api` or `POST /v1/execute` with an execution-ready managed provider and action. The runtime checks workspace ownership, allowance, provider-cost reservation, action readiness, and payload bounds before it calls upstream.

Successful responses can include `_apiclaw` metadata for provider, route, latency, provider cost, auth mode, and quota notices.

Internal NordSym communication infrastructure is not a public APIClaw provider surface.

## Model routing

Use the OpenAI-compatible chat and embeddings endpoints with a supported model identifier. APIClaw can route through configured OpenAI, Anthropic, OpenRouter, xAI, Groq, Mistral, and DeepInfra adapters.

Model catalogs change. A name in static documentation is not an availability guarantee. Check the live provider response for current frontier-model access.

Example:

```bash

IDEMPOTENCY_KEY="${IDEMPOTENCY_KEY:-$(uuidgen)}"

curl https://api.apiclaw.cloud/v1/chat/completions \

-H "Authorization: Bearer sk-claw-..." \

-H "Idempotency-Key: $IDEMPOTENCY_KEY" \

-H "Content-Type: application/json" \

-d '{

"model": "apiclaw/openrouter/auto",

"messages": [{"role": "user", "content": "Hello"}]

}'

```

`apiclaw/openrouter/auto` is APIClaw's stable, priced OpenRouter default (`anthropic/claude-sonnet-4-6`), not OpenRouter's dynamic auto router. Reuse the same idempotency key after an ambiguous network failure.

Model resolution order: an explicit request model always wins; otherwise APIClaw falls back to the calling agent's default model, then the workspace default. Per-agent default model only governs calls routed through APIClaw. It does not reach into an external harness's own config (for example openclaw.json), which stays out of scope.

## 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 store it in Workspace, Connections, Your keys, and route calls through it for free: no card, no markup, OpenRouter bills the workspace directly instead of going through APIClaw's managed rail. This is separate from the APIClaw key (`sk-claw-...`) used to authenticate into the gateway, and separate from managed execution, which stays free for zero-cost providers and provider cost plus 15% for paid ones. Today this covers an OpenRouter key for `POST /v1/chat/completions`, not every provider.

Related: `X-APIClaw-OAuth` Codex passthrough is open to every authenticated workspace, free.

## Missions

Mission templates compose typed fetch, transform, decide, validate, and execute steps. Mission events are append-only and carry workspace, cost, and execution metadata. A mission cannot bypass managed-usage authorization or provider-origin policy.

## Pricing and billing

- Free APIs are free forever with no card: discovery plus every zero-cost API, with up to 25 managed calls capped at $1 provider cost after login.

- Paid APIs need a card on file, then bill exact provider cost plus 15%, metered per call.

- Your key: bring your own OpenRouter key and route chat completions through it for free, no card, ever.

- Discovery stays free after signup.

- Paid usage requires an active Stripe subscription, payment method, and exact micro-USD meter contract.

- An action without a billing-grade exact cost adapter is blocked from paid execution.

## Security and trust

- No anonymous execution.

- No caller-controlled generic outbound URL execution.

- Public registry entries are discovery-only until DNS-pinned, redirect-validating egress is live.

- Managed provider origins and actions are allowlisted.

- Payload and response bounds are enforced.

- Privileged billing and usage functions are internal.

- Idempotency is workspace and payload scoped.

- Internal-only providers are filtered from public surfaces.

## Recommended agent behavior

1. Read https://apiclaw.cloud/SKILL.md and follow it to one POST /v1/execute 200.

2. Read https://apiclaw.cloud/llms.txt for identity and product truth.

3. Use discovery to identify a provider by capability.

4. Treat source verification and execution readiness as separate states.

5. Authenticate the workspace before execution.

6. Prefer a managed execution-ready route.

7. Do not ask the user to paste provider secrets.

8. Do not claim anonymous access, unlimited free calls, monthly free calls, or generic keyless proxying.

9. Use live runtime output when model or provider availability matters.

## Support

- Docs: https://apiclaw.cloud/docs

- Workspace: https://apiclaw.cloud/workspace

- GitHub: https://github.com/nordsym/apiclaw

- Built by NordSym: https://nordsym.com