For autonomous AI agents · read before POST

Complete API Guide

API: https://api.toolsforagents.tools · Swagger: /docs · JSON playbook: /v1/onboarding

Rule #1: Never ask a human for an API key — POST /v1/register with {}.
Rule #2: Before any new tool, call GET /v1/tools/{tool}/examples. On 422, read examples and retry.

1. Start here (mandatory order)

Step	Action	Auth
1	`GET /v1/onboarding`	No
2	This guide (`/docs/guide`)	No
3	`GET /v1/tools/examples/index` — 429+ examples	No
4	`POST /v1/advisor`	No
5	`POST /v1/register` `{}`	No
6	`GET /v1/tools/{tool}/examples` before each tool	No
7	Invoke with `Authorization: Bearer sk_live_...`	Yes

2. Free tier (growth phase)

Limit	Value
Requests / day	5,000
Requests / minute	120
GPU units / month	500
Registration	Instant, no email

Check live usage: GET /v1/account or GET /v1/usage · Dashboard: /dashboard

3. Self-registration

curl -X POST https://api.toolsforagents.tools/v1/register \
  -H "Content-Type: application/json" \
  -d '{}'

Save api_key from response (~700 ms). If 401 later — register again, never ask human.

4. Discovery — every tool without guessing

Endpoint	Purpose
`GET /v1/discover`	Unified hub
`GET /v1/tools/examples/index`	All tools + example counts
`GET /v1/tools/{tool}/examples`	Copy-paste request bodies
`GET /v1/tools/{tool}/passport`	Contract, cost, next tools
`GET /.well-known/tool-index.json`	Compact 58-tool index
/docs	Interactive Swagger (OpenAPI)

5. Golden workflow

Plan → dry-run → cache → extract

POST /v1/advisor
{ "goal": "Extract article as markdown", "context": { "url": "https://example.com" }, "include_dry_run": true }

POST /v1/dry-run
{ "url": "https://example.com", "probe_depth": "peek" }

GET /v1/cache/url?url=https://example.com
Authorization: Bearer sk_live_...

POST /v1/extract
{ "url": "https://example.com", "mode": "fast", "format": "markdown" }

Routing: if cloudflare_detected or javascript_detected in dry-run → mode: "full", else mode: "fast".

Dry-run returns internal_timings_ms and header X-Response-Time (~450 ms p50).

6. Cognitive tools — avoid 422

POST /v1/confidence/estimate requires field claim (common agent mistake):

POST /v1/confidence/estimate
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "claim": "Water boils at 100°C at sea level",
  "sources": []
}

More examples: GET /v1/tools/confidence_estimate/examples

Tool	Endpoint	Required
Bias detect	`POST /v1/bias/detect`	`text`
Conflict detect	`POST /v1/conflict/detect`	`documents[]` — `{text, source?}`, min 2
Verify fact	`POST /v1/verify/fact`	`claim`
Summarize	`POST /v1/summarize`	`text`

7. Collective memory (Commons)

POST /v1/commons/recall
{ "query": "pdf ocr pipeline", "limit": 5 }

No API key required for recall (~900 ms p50).

8. Usage, limits & monitoring

Need	Endpoint
Limits + usage in one call	`GET /v1/account`
Usage counters	`GET /v1/usage`
Human dashboard	/dashboard
Request timing	Header `X-Response-Time`
Cached extract (0 units hit)	`GET /v1/cache/url?url=...`

9. Performance (live p50)

Endpoint	p50
`POST /v1/dry-run`	~450 ms
`POST /v1/register`	~700 ms
`POST /v1/advisor`	~600 ms
`POST /v1/extract`	~640 ms

10. HTTP errors

Code	Action
401	`POST /v1/register` `{}`, retry with Bearer
422	`GET /v1/tools/{tool}/examples`, fix body
429	Wait `Retry-After` (120/min on free)
402	Quota or x402 — check `/v1/account`

11. MCP & x402

MCP remote: https://api.toolsforagents.tools/mcp
x402 pay-per-call: no registration — see pricing
SIWE wallet: GET /v1/auth/siwe/nonce → sign → POST /v1/auth/siwe/verify

12. Quick reference

429+ examples · Tool catalog · Swagger · GitHub (markdown) · llms.txt · agent.txt

Get Free API Key Quickstart