# Porkbun API v3 — Sandbox

> Isolated sandbox/test environment (sandbox API keys, pk1_sb_…).

Part of the Porkbun API v3.62. Topic index: https://porkbun.com/llms · Full reference: https://porkbun.com/llms-full.txt · Overview: https://porkbun.com/llms.txt · OpenAPI spec: https://porkbun.com/api/json/v3/spec

**Auth:** send `X-API-Key` / `X-Secret-API-Key` headers (preferred) or `apikey` / `secretapikey` in the JSON body. Create keys at https://porkbun.com/account/api

---

# Endpoints

## POST /api/json/v3/sandbox/topup

**Sandbox: add fake credit**

Sandbox only (requires a `pk1_sb_` key). Grants fake account credit so paid operations can keep being exercised after funds run out. Optional `amount` in US cents (default 100000 = $1000, capped 1,000,000).

**Key permission needed:** `account`

| Parameter | In | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | Optional, recommended on every purchase and write. Send a unique value (a UUID) per intended operation. Repeating the request with the same key and an identical body within 24 hours returns the original response instead of doing it again, so a retry after a timeout cannot double-charge or double-apply. The same key with a different body returns 409 IDEMPOTENCY_KEY_MISMATCH; while the first request is still running, 409 IDEMPOTENCY_KEY_IN_USE. |

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `amount` | integer | no | Fake credit to add in US cents (default 100000; max 1000000). |

Response fields:

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `granted` | integer |  |
| `balance` | integer |  |
| `display` | string |  |
| `sandbox` | boolean |  |

## POST /api/json/v3/sandbox/reset

**Sandbox: reset to a clean slate**

Sandbox only (requires a `pk1_sb_` key). Wipes the sandbox account's simulated state (domains, DNS, orders, credit) and re-grants $1000 fake credit.

**Key permission needed:** `account`

| Parameter | In | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | Optional, recommended on every purchase and write. Send a unique value (a UUID) per intended operation. Repeating the request with the same key and an identical body within 24 hours returns the original response instead of doing it again, so a retry after a timeout cannot double-charge or double-apply. The same key with a different body returns 409 IDEMPOTENCY_KEY_MISMATCH; while the first request is still running, 409 IDEMPOTENCY_KEY_IN_USE. |

Response fields:

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `message` | string |  |
| `domainsCleared` | integer |  |
| `balance` | integer |  |
| `sandbox` | boolean |  |

## POST /api/json/v3/sandbox/triggerWebhook

**Sandbox: fire a sample webhook event**

Sandbox only (requires a `pk1_sb_` key). Enqueues a signed sample webhook event to your registered endpoints so you can test your handler and signature verification for any event type on demand — including cron-driven events like `domain.expiring` that don't result from a single API call. Register an endpoint first with `POST /webhook/create`.

**Key permission needed:** `account`

| Parameter | In | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | Optional, recommended on every purchase and write. Send a unique value (a UUID) per intended operation. Repeating the request with the same key and an identical body within 24 hours returns the original response instead of doing it again, so a retry after a timeout cannot double-charge or double-apply. The same key with a different body returns 409 IDEMPOTENCY_KEY_MISMATCH; while the first request is still running, 409 IDEMPOTENCY_KEY_IN_USE. |

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `eventType` | string | yes | Event type to emit. |
| `domain` | string | no | Domain used in the sample payload (default example.com). |

Response fields:

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `event` | string |  |
| `data` | object |  |
| `endpointsRegistered` | integer |  |
| `message` | string |  |
| `sandbox` | boolean |  |

---

## More

- Guides (how-tos): https://porkbun.com/llms/guides
- Topic index: https://porkbun.com/llms
- Full reference (one file): https://porkbun.com/llms-full.txt
- OpenAPI spec (full schemas): https://porkbun.com/api/json/v3/spec
- Short overview: https://porkbun.com/llms.txt
- Official MCP server: https://porkbun.com/mcp (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api