Documentation

Quickstart

Give your agent one key and a safe path to real-world actions. Discover tools, get a quote, approve, execute, and verify with a signed receipt.

1 · Get an API key

Request early access at toolcallstore.com/signup or email hello@toolcallstore.com and we'll provision one. Keys look like this:

tc_live_xxxxxxxxxxxxxxxxxxxx   # production
tc_test_xxxxxxxxxxxxxxxxxxxx   # sandbox (mocked providers)

Send it as a bearer token on every request:

Authorization: Bearer tc_live_xxxxxxxxxxxx

2 · Try your first tool call

Ask the store which tools fit your intent. No charge, no approval — just discovery.

POST /v1/tools/searchcurl

curl https://toolcallstore.com/v1/tools/search \
  -H "Authorization: Bearer tc_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"intent": "register a domain and set up business email"}'

→ {
  "tools": ["domains.search", "domains.register",
            "email.create_mailbox", "dns.apply_template"],
  "next": "POST /v1/quotes"
}

3 · The quote → approve → execute loop

Every billable action follows the same three steps. Here's registering a domain end to end.

a. Get a quote

POST /v1/quotes

curl https://toolcallstore.com/v1/quotes \
  -H "Authorization: Bearer tc_live_xxxxxxxxxxxx" \
  -d '{"items": ["domain:mysaas.com"]}'

→ { "quote_id": "q_abc", "total_estimate_usd": 7.30,
    "requires_approval": true, "expires_at": "2026-06-28T18:30:00Z" }

b. Request approval

POST /v1/approvals

curl https://toolcallstore.com/v1/approvals \
  -H "Authorization: Bearer tc_live_xxxxxxxxxxxx" \
  -d '{"quote_id": "q_abc", "reason": "New SaaS onboarding flow"}'

→ { "approval_id": "appr_xyz", "status": "pending" }
# An email (or webhook) goes to the account owner. The agent polls until approved.

c. Execute

POST /v1/execute

curl https://toolcallstore.com/v1/execute \
  -H "Authorization: Bearer tc_live_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 7c1f...uuid" \
  -d '{"approval_id": "appr_xyz"}'

→ { "receipt_id": "rcpt_123", "status": "processing" }

4 · Understanding receipts

Poll GET /v1/receipts/<id> until status is completed. Every receipt is a verifiable record of what happened.

Field	Type	Meaning
`receipt_id`	string	Stable ID for this action.
`action`	string	e.g. `domains.register`.
`status`	string	`processing` · `completed` · `failed` · `rolled_back`.
`provider_id`	string	The provider's own reference (e.g. `OP-29793388`).
`cost_usd`	number	What it cost you.
`sell_usd`	number	What you charged downstream (if set).
`timestamp`	string	ISO-8601 completion time.
`dns_verified`	boolean	For domains: A record resolved and confirmed.
`rollback_hint`	string	How to reverse this action (or why it's terminal).
`proof[]`	array	Raw provider responses / DNS lookups backing the receipt.

Scopes

Keys carry only the scopes you grant. A missing scope returns 403 — it never silently no-ops.

Scope	Grants	Approval?
`domains:read`	Search domain availability	—
`domains:buy`	Register / renew domains	yes
`dns:write`	Apply DNS records / templates	yes
`email:write`	Create / delete mailboxes	yes
`llm:call`	Route LLM requests	—
`media:generate`	Generate images / video	—
`approvals:create`	Open approval requests	—
`receipts:read`	Fetch receipts and proof	—
`providers:read`	List providers and status	—
`providers:keys`	Manage your BYOK provider keys	—

Error codes

Code	Meaning	What to do
400	Bad request	Malformed body — fix and resend.
401	No / invalid auth	Check your bearer token.
402	Insufficient balance	Add funds — see `add_funds_url`.
403	Scope missing	Grant the scope to this key.
404	Not found	Bad ID or path.
409	Duplicate idempotency key	Already processed — read the original receipt.
422	Validation error	Field-level issue — see `errors[]`.
429	Rate limited	Back off 60s, then retry.
500	Provider error	Retry with exponential backoff.

Idempotency

Send an Idempotency-Key: <uuid> header on every POST /v1/execute and POST /v1/domains/register call. If the network drops, retry with the same key — you'll get the original receipt back instead of a second charge. Reusing a key with a different body returns 409.

Idempotency-Key: 7c1f9b2e-3a44-4d10-8c2e-9f0b1a2c3d4e

Webhooks

POST → your webhook_url

{
  "approval_id": "appr_xyz",
  "status": "approved",
  "quote_id": "q_abc",
  "timestamp": "2026-06-28T18:12:04Z"
}

We also emit events on execute and receipt completion. Verify the X-TCS-Signature header against your signing secret.

BYOK — bring your own keys

Already have provider accounts? Register your own keys and pay only an orchestration + safety fee — provider charges go straight to your account.

POST /v1/providers/keys

curl https://toolcallstore.com/v1/providers/keys \
  -H "Authorization: Bearer tc_live_xxxxxxxxxxxx" \
  -d '{"provider": "stability", "api_key": "sk-..."}'

→ { "provider": "stability", "status": "active", "key_id": "pk_9f2" }

Your provider keys are encrypted at rest. We never store them in plaintext and never return them after registration.

Read the full worked example →