Test mode and sandboxes

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); 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): a repeated request is never done twice.