Sandbox keys

Build and test an integration for nothing: a sandbox key works with every tool in your organization's sandbox, answered from recordings, with nothing charged.

A sandbox key lets you build and test an integration for nothing. Every tool works with it as it does live, but in your organization's sandbox: a separate organization whose work is answered from a recording of real runs, so no model or provider is called and no credits are held or charged.

Create a sandbox key

Create the key

In the studio, open Settings → Connections, choose Create API key and tick Sandbox. Give it a name, and Make changes if it should create and run things. A sandbox key takes no Space: it reaches the whole sandbox. One that makes changes also confirms the spends it prepares, since they charge nothing.

Copy it once

It starts with prb_test_, so your code, your logs and secret scanners can tell it from a live prb_ key. Like any key, it's shown once and Probably keeps only a hash of it.

Call it as a live key

Send it as Authorization: Bearer prb_test_... to the HTTP API or the MCP server. Switching to live is changing the key.

A first call with a sandbox key

export PROBABLY_API_URL="https://studio.probably.co"
export PROBABLY_API_KEY="prb_test_..."

curl -s "$PROBABLY_API_URL/api/v1/tools/get_connection" \
  -H "Authorization: Bearer $PROBABLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

get_connection answers with the sandbox's organizationId, which isn't your organization's. The first sandbox key anyone in your organization creates makes the sandbox; until Probably has published a recording for sandbox keys, creating one is refused with "The sandbox isn't available yet." Sandbox keys are listed and revoked with your other keys in Settings → Connections, marked Sandbox key.

What the sandbox is

Its own data. The sandbox has its own Spaces, videos, library and events, and none of your organization's: a video or Space of your real organization reads as not-found there. A key that may make changes creates the Spaces it needs with create_space.
Your organization's members. Everyone in your organization is a member of its sandbox, with the same role, and nobody else. A key there acts as its member, never past their role, and stops working when they leave your organization, or when the organization is deleted.
Not in the studio. The sandbox isn't in the organization switcher and the studio never opens it; read what it made through the API.

What the recording answers

Every sandbox replays the recording Probably published for sandbox keys: a product-demo video made start to finish, and the four stage primitives on one video. Each run replays it from its first entry, whatever else runs in the sandbox, so the same calls give the same results. It answers:

Work	Tools
A new video: the planner, copywriter, media producer and reviewers, a still, a clip, a voiceover and the finished cut	`prepare_video`, `confirm_spend`, `get_video`, `wait_for_video`, `get_media`, `share_video`
Research	`research`, `get_stage`
Hooks	`brainstorm`, `get_stage`
A script and its critics	`write_script`, `get_stage`
The critics on a revision	`review` with a `revision`, `get_stage`

Reading, saving records, sharing and the other free tools work as they do live. Anything the recording doesn't hold fails as not recorded: the run or stage stops blocked, and its outcome says "Not recorded". That includes the generate_clip and storyboard stages, which the recording doesn't hold yet, swaps, Reference mode rehearsals, product stills, persona headshots, voice builds, reviewing an uploaded video, and searches for ads and references. It never falls through to a real provider. Results are realistic, not tailored to your brief: test the shape of your integration in the sandbox, and the quality of the results live.

Seeing what it made

When wait_for_video or get_video says the run is completed, get_media gives short-lived links to the video and its poster frame; share_video gives a lasting link to send someone. A stage's result is in get_stage.

Prices and previews

Nothing is charged. No credits are needed, held or captured, and no spend cap or free first draft is used.
Previews say so. Every prepare_* and stage preview carries "sandbox": true, always fits (fits, covered), never uses the free first draft (freeDraft is false), and shows what the call would have charged live: the price (quote), or on the meter a run's estimatedCredits and a change's credits per step, and a stage's cap (capCredits). availableCredits is the sandbox's own balance, which is always 0; it doesn't need any.

A stage's preview through a sandbox key

{
  "preview": {
    "kind": "stage",
    "stage": "research",
    "capCredits": 100,
    "availableCredits": 0,
    "fits": true,
    "sandbox": true
  }
}

Limits, events and webhooks

Rate limits are a live key's: the same per-connection limits (see Rate limits). A sandbox also confirms at most 50 spends a day across its keys. Sandbox keys count separately toward the number of keys a member may hold.
Events are the sandbox's own: GET /api/v1/events with a sandbox key reads the sandbox's journal, run.started and the rest, by cursor (see Events and webhooks).
Webhooks aren't available in the sandbox yet; read its events by cursor.

Sandbox keys

Create a sandbox keyCopy Anchor Link

What the sandbox isCopy Anchor Link

What the recording answersCopy Anchor Link

Seeing what it madeCopy Anchor Link

Prices and previewsCopy Anchor Link

Limits, events and webhooksCopy Anchor Link