DevelopersReference
Sandbox
What a test key sees, and how to put it back the way it started.
Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.
What a test key is looking at
GET /sandbox
Scope: any key (a test key is what proves the caller). Operation id: getSandbox.
Needs a spk_test_ key. Returns the sandbox workspace id and the fixture
counts it was seeded with. A live key gets 403 sandbox-only.
Example request
curl "https://api.showpilot.com/v1/sandbox" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The sandbox
Sandbox
| Field | Type | Always | Meaning |
|---|---|---|---|
mode | test | yes | |
livemode | boolean | yes | |
workspaceId | string | yes | The sandbox's own workspace id (it starts with sbx_). |
seededAt | string (date-time) | no | When the fixtures were (re)seeded; present after a reset. |
fixtures | object | yes | How many of each object the seed creates. |
Errors
| Status | When |
|---|---|
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |
Drop the sandbox and seed it again
POST /sandbox/reset
Scope: any key (a test key is what proves the caller). Operation id: resetSandbox.
Needs a spk_test_ key and an Idempotency-Key. Everything written to
the sandbox is discarded and the fixtures come back fresh. A live key
gets 403 sandbox-only; the live workspace can never be reset this way.
Example request
curl "https://api.showpilot.com/v1/sandbox/reset" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The fresh sandbox
Sandbox
| Field | Type | Always | Meaning |
|---|---|---|---|
mode | test | yes | |
livemode | boolean | yes | |
workspaceId | string | yes | The sandbox's own workspace id (it starts with sbx_). |
seededAt | string (date-time) | no | When the fixtures were (re)seeded; present after a reset. |
fixtures | object | yes | How many of each object the seed creates. |
Errors
| Status | When |
|---|---|
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |