--- title: "Test mode and sandboxes" description: "What you can exercise without live effects, and what is real from the first call." canonical: "https://boltclaw.ai/docs/testing" last-updated: "2026-11-05" --- # Test mode and sandboxes What you can exercise without live effects, and what is real from the first call. There is no separate sandbox host and no test key. Every key is `bc_live_`, belongs to one real workspace, and acts on it. What you can do is exercise most of the API in ways that have no live effect: referral programs have a full test mode, webhooks have a test event, billing and payout connections have sandbox switches, and pages and posts can be made without anyone seeing them. This page lists each one, and the few things that are real from the first call. ## Start with reads Every `GET` is safe to repeat and changes nothing. `GET /v1/ping` checks a key, `GET /v1/workspace` names the workspace it acts in, and `GET /v1/usage` shows what the plan allows. The documentation itself needs no key at all: the documentation MCP server at `/docs/mcp-server` and the A2A agent at `/docs/a2a` answer questions from these pages and can never see or change an account. ## Referral test mode A referral program keeps TEST data apart from live data, in the database: - **A test sale.** `POST /v1/referrals/programs/{id}/test-sale` runs the real path step by step (a click on the program's test partner's link, a signup, a sale of 100.00 with two items, then a partial refund of 25.00) and answers with what each step caused: the conversion, its commissions and rewards, the friend's offer, and the webhook deliveries it queued. - **Your own test conversions.** Send `"test": true` on `POST /v1/referrals/conversions`. The conversion is credited to the program's test partner whoever's code it carries. A test `event_id` and a live one never collide, and neither do test and live customers. - **What test data never does.** It is never payable, never counts toward a limit or a total, emails nobody, and reaches only webhook endpoints that receive test events. A program holds at most 1,000 test conversions and 1,000 test clicks. - **Clearing it.** `DELETE /v1/referrals/programs/{id}/test-data` deletes every test row of the program and its test partner. Live data is never touched. An AI assistant's key is always asked to get a person's approval first. ## Test webhook events - `POST /v1/webhooks/{id}/test` queues a `webhook.test` delivery to that one endpoint, signed exactly as a real event is, whatever it subscribed to. Use it to prove your receiver checks the signature before a real event arrives. - Set `test_events: true` on an endpoint to also receive TEST events (referral test sales, `test: true` conversions, test-mode and sandbox events from a billing system). A test delivery's body carries `"test": true`; a live one never does. ## Sandbox connections - **Billing systems.** A referral program's billing integration has a Sandbox switch (`test_mode`): every event it receives is recorded as test data. A test-mode Stripe event is test data too. - **Payout providers.** A payout account connected in `sandbox` mode never pays a batch. ## Pages and posts - **A page starts unpublished.** `POST /v1/pages` without `"published": true` creates a page nobody can open; publishing is a separate, deliberate change. The slug is still taken for everyone, and the page counts toward the plan's page allowance, so delete a test page when you are done with it. - **A post can be a draft.** `POST /v1/posts` with `"draft": true` is never sent to a network, and a draft can be changed or deleted. Anything else publishes, now or at `scheduled_for`. ## What is real from the first call - Publishing a page, a post or a reply, sending a message, and anything that moves money. An AI assistant's key cannot do any of these without a person approving that exact request first (`428 APPROVAL_REQUIRED`, see [Errors](https://boltclaw.ai/docs/errors)); a key a person made for their own server can. - Plan allowances. A request that creates something draws on the organisation's allowance whether you meant it as a test or not. - Posting to X, which is billed per call on top of the plan. When in doubt, retry with the same `Idempotency-Key` ([Retrying safely](https://boltclaw.ai/docs/idempotency)): a repeated request is never done twice.