> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peeker.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Replace burned domains
> Starts one job that swaps every replaceable burned domain.
Send exactly one `replacement_domains` entry per burned domain
(alphabetically paired), or send `[]` to learn the required count
from a `domain_count_mismatch` error. One job runs at a time.
Poll `GET /domains/burned/replace/{id}`, then page
`.../results` for every row. Each swap also emits `swap.created`.
Only Peeker-bought domains can be replaced. Send
`replacement_domains: []` first if you do not know the count. The
`domain_count_mismatch` error lists every burned domain and how many
replacements you need.
## OpenAPI
````yaml /openapi.yaml post /domains/burned/replace
openapi: 3.1.0
info:
title: Peeker Partner API
version: 1.0.0
description: >
White-label Peeker's email infrastructure: Google Workspace and Microsoft
365 inboxes, deliverability monitoring, and self-healing domain swaps,
from your own app. Create a provider workspace target, order licenses with
imported or
Peeker-managed domains, and Peeker's backend handles provisioning,
DNS, forwarding, and lifecycle webhooks.
Create a provider workspace target with `POST /workspaces`, then send its
`wrk_...` ID to `POST /orders`. For Smartlead, create one main workspace,
then add `client_id` to an order only when it should go to a client
workspace. Omit it to order into the main workspace.
## Read first
- **[Authentication](/authentication)**: bearer keys, live vs sandbox,
request IDs.
- **[Rate limits](/rate-limits)**: 600/min per key, 429 backoff.
- **[Webhooks](/webhooks)**: signed events and delivery rules.
- **[Async jobs](/concepts/async-jobs)**: what to poll vs subscribe to.
- **[Best practices](/best-practices)**: errors, paging, idempotency.
## Concepts
- **[Orders](/concepts/orders)**: statuses, sizing, pending actions, cancel.
- **[Domains](/concepts/domains)**: inventory, `usable_for`, import,
forwarding.
- **[Bundles](/concepts/bundles)**: saved templates and capacity.
- **[Swaps](/concepts/swaps)**: standard vs premium, renames.
## Workflow guides
- **[Provider ordering](/guides/provider-ordering)** — create a provider
workspace target and order through it.
- **[Buying domains & ordering](/guides/buying-domains)** — the default
flow: bundle, availability, order, webhooks.
- **[Importing domains](/guides/importing-domains)** — bring in existing
customer domains.
- **[Forwarding](/guides/forwarding)** — point a domain at a marketing site.
- **[How to implement domain swaps](/guides/domain-swaps)** — standard vs
premium swaps.
- **[Renaming inbox senders](/guides/user-name-swaps)** — change mailbox
personas on a warm domain.
## Public ID prefixes
| Prefix | Resource |
| --- | --- |
| `cus_` | Customer tracking record |
| `wrk_` | Provider workspace |
| `bun_` | Bundle |
| `ord_` | Order |
| `dom_` | Domain |
| `pcl_` | Pool reservation |
| `prp_` | Pool replacement |
| `prl_` | Pool release |
| `imp_` | Domain import job |
| `fwj_` | Domain forwarding job |
| `brj_` | Burned-domain replacement job |
| `swp_` | Domain swap |
| `act_` | Pending action |
| `evt_` | Webhook event |
servers:
- url: https://api.peeker.ai/partner/v1
description: >-
Same base URL for live and sandbox. The key prefix (`pk_live_…` /
`pk_test_…`) picks the environment.
security:
- BearerAuth: []
tags:
- name: Account
x-group: Account
description: >
Confirm an API key with `GET /me`. Returns environment (live or sandbox),
permission preset, and the partner profile. See
[Authentication](/authentication).
- name: Provider workspaces
x-group: Provider workspaces
description: |
A provider workspace is one reusable provider connection. Create it once,
keep the returned `wrk_...` ID, and use it in orders and pool attach.
Optional customer tracking stays on the target. Provider credentials stay
internal and are never echoed.
EmailBison requires a workspace API-user key. Super-admin keys are
rejected. Instantly and Smartlead connections require `api_key`.
Smartlead workspace creation takes a main API key and a label. Do not send
`client_id` or customer data. Its login email and password are optional,
but must be sent together. Google orders do not need the pair, and orders
never accept it. Smartlead Microsoft orders and pool attach still use the
workspace-saved pair. Add
`client_id` to the order destination when the order belongs to a client
workspace; omit it for the main workspace.
PlusVibe setup requires `api_key`, remote `workspace_id`, and its login
email/password pair so orders and pool attach work immediately. Instantly
login credentials belong on an order destination.
- name: Bundles
x-group: Bundles
description: |
Saved order template sized by monthly sending volume (`bun_…`). Pass
`bundle_id` on an order instead of custom license counts.
Lifecycle: [How bundles work](/concepts/bundles).
- name: Domains
x-group: Domains
description: >
Sending domains in your partner account (`dom_…`). Same ID whether or not
the domain is on an order.
**Status values**
| Value | What it means |
| --- | --- |
| `available` | The domain is in inventory but not on an order yet. |
| `in_progress` | We're setting it up. |
| `active` | Live and warming or healthy. |
| `failed` | Something broke that we can't fix automatically. |
| `action_required` | We need your help (e.g. update nameservers). |
**Inventory vs connected**
- `category=inventory` — yours but not on any order. Inventory rows
don't include `provider`.
- `category=connected` — on an active order. The row carries the link
fields `provider`, `customer_id`, `order_id`, `usable_for`, and
`forwarding_url`.
**`usable_for` matrix**
When you check a domain's availability:
| Who's on the domain | `usable_for` |
| --- | --- |
| Nobody, or just Google | `["google", "microsoft"]` |
| Microsoft (or both) | `["google"]` |
| Premium / invalid / errored | not orderable; `available: false` with a
`reason` |
**Imports and forwarding are jobs**
Both **import** and **forwarding** are async jobs. Posting to those
endpoints starts the job and gives you back a row with `status:
"in_progress"`. Poll the job's GET endpoint to see when it finishes:
- Import jobs: prefix `imp_…`. Includes the `nameserver_groups` your
customer needs to set at their registrar.
- Forwarding jobs: prefix `fwj_…`. Already-correct domains are
returned in `completed` with newly updated domains.
- name: Domain pool
x-group: Domain pool
description: |
Assign an exact quantity from pre-warmed Google inventory. Each domain
needs at least one active Google inbox on a paid Google order (commonly
two), complete provider mailbox identity, and no explicit burned provider
result. Attach is all-or-nothing: full quantity or
`insufficient_inventory` with no pool change. Attach and release are
async. Poll the resource or subscribe to `pool.*` webhooks.
Guide: [Pre-warmed pool](/guides/pre-warmed-pool).
- name: Orders
x-group: Orders
description: |
One purchase of domains plus Google and/or Microsoft licenses for one
customer (`ord_…`). Use a saved `bundle_id` **or** custom license counts,
never both. Requires `Idempotency-Key`.
Lifecycle: [How orders work](/concepts/orders).
- name: Domain swaps
x-group: Domain swaps
description: |
Replace a domain inside an existing order without losing the order
(`swp_…`). For persona-only changes use `POST /swaps/user_names`.
Statuses and standard vs premium: [How swaps work](/concepts/swaps).
- name: Webhooks
x-group: Webhooks
description: |
Signed JSON POSTs for orders, domains, imports, forwarding, pool, and
swaps. Register the URL and secret in the
[Partner portal](https://app.peeker.ai/partner/webhooks). Event IDs look
like `evt_01HZX`.
Delivery is at least once (up to 5 attempts). Verify `Peeker-Signature`
and dedupe `Peeker-Event-Id` for at least 24 hours.
Full catalog: [Webhooks](/webhooks).
paths:
/domains/burned/replace:
post:
tags:
- Domains
summary: Replace burned domains
description: |
Starts one job that swaps every replaceable burned domain.
Send exactly one `replacement_domains` entry per burned domain
(alphabetically paired), or send `[]` to learn the required count
from a `domain_count_mismatch` error. One job runs at a time.
Poll `GET /domains/burned/replace/{id}`, then page
`.../results` for every row. Each swap also emits `swap.created`.
operationId: replaceBurnedDomains
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- replacement_domains
properties:
replacement_domains:
type: array
description: >-
One new domain per replaceable burned domain. Send an empty
array to discover the required count via the
`domain_count_mismatch` error.
items:
type: string
examples:
two_replacements:
summary: Replace two burned domains
value:
replacement_domains:
- acme-fresh.com
- team-acme-2.com
discover_count:
summary: Discover how many replacements are needed
value:
replacement_domains: []
responses:
'202':
description: Replacement job accepted; poll it for progress.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/BurnedReplaceJob'
examples:
accepted:
summary: Job accepted for two burned domains
value:
data:
id: brj_01HZX0BR1A2B3C4D5E6F7G8H
status: in_progress
submitted_count: 2
completed_count: 0
failed_count: 0
results_returned_count: 0
results_limit: 5000
results_truncated: false
completed: []
failed: []
created_at: '2026-05-08T12:00:00Z'
'400':
description: Wrong replacement count, or another replace job is already running.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
count_mismatch:
summary: Submit exactly the required number of domains
value:
error:
code: domain_count_mismatch
message: >-
You have 2 burned domains eligible for replacement.
Submit exactly 2 replacement domains (got 0).
field: replacement_domains
details:
required: 2
submitted: 0
burned_domains:
- acme-mail.com
- imported-acme.com
job_in_progress:
summary: A replace-all job is already running
value:
error:
code: invalid_request
message: >-
A burned-domain replacement job is already in progress.
Poll it until it finishes.
details:
job_id: brj_01HZX0BR1A2B3C4D5E6F7G8H
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
SuccessEnvelope:
type: object
required:
- data
properties:
data: {}
BurnedReplaceJob:
type: object
required:
- id
- status
- submitted_count
- completed_count
- failed_count
- results_returned_count
- results_limit
- results_truncated
- completed
- failed
- created_at
properties:
id:
type: string
example: brj_01HZX0BR1A2B3C4D5E6F7G8H
status:
type: string
enum:
- in_progress
- completed
- failed
- partial_success
example: completed
submitted_count:
type: integer
example: 2
completed_count:
type: integer
example: 2
failed_count:
type: integer
example: 0
results_returned_count:
type: integer
description: >-
Number of rows embedded across `completed` and `failed` in this
response.
example: 2
results_limit:
type: integer
description: >-
Maximum combined number of rows embedded across `completed` and
`failed`.
example: 5000
results_truncated:
type: boolean
description: >-
`true` if more results exist than the embedded arrays show. Page
`/results` for the full set.
example: false
completed:
type: array
description: >-
Preview of created swaps. `completed` and `failed` share the
combined `results_limit` (counts stay exact). Each swap also emits
`swap.created`.
items:
type: object
required:
- domain
- replacement_domain
- swap_id
properties:
domain:
type: string
example: acme-mail.com
replacement_domain:
type: string
example: acme-fresh.com
swap_id:
type: string
example: swp_01HZX0SW1A2B3C4D5E6F7G8H
failed:
type: array
description: >-
Preview of failed rows. `completed` and `failed` share the combined
`results_limit`. Page `/results` for every failure.
items:
type: object
required:
- domain
- replacement_domain
- reason
properties:
domain:
type: string
example: bad-acme.com
replacement_domain:
type: string
example: acme-fresh-2.com
reason:
type: string
example: This domain already has a swap in progress.
created_at:
type: string
format: date-time
example: '2026-05-08T12:00:00Z'
completed_at:
type: string
format: date-time
example: '2026-05-08T12:01:30Z'
ErrorEnvelope:
type: object
additionalProperties: false
required:
- error
properties:
error:
type: object
additionalProperties: false
required:
- code
- message
- request_id
properties:
code:
type: string
description: Stable machine-readable code. Branch on this field.
enum:
- invalid_request
- unauthorized
- forbidden
- not_found
- rate_limited
- provider_not_supported
- provider_mismatch
- provider_credentials_invalid
- provider_login_credentials_required
- provider_unavailable
- emailbison_super_admin_key
- smartlead_connection_required
- smartlead_client_id_required
- smartlead_client_not_found
- idempotency_key_required
- idempotency_conflict
- idempotency_in_progress
- workspace_promotion_required
- workspace_credentials_conflict
- order_shape_conflict
- domain_count_mismatch
- insufficient_inventory
- domain_not_imported
- domains_not_submittable
- premium_domain_not_supported
- domain_not_usable_for_provider
- domain_already_in_active_order
- internal_error
example: emailbison_super_admin_key
message:
type: string
description: Human-readable explanation. Wording may change.
example: >-
Use an EmailBison workspace/user API key; super-admin keys are
not accepted.
request_id:
type: string
description: >-
Stable request identifier, identical to the `Peeker-Request-Id`
response header.
example: 550e8400-e29b-41d4-a716-446655440000
field:
type: string
description: Dot path to the invalid request property, when applicable.
example: credentials.api_key
details:
type: object
additionalProperties: true
description: Structured context specific to `error.code`.
responses:
Unauthorized:
description: Missing, invalid, or revoked API key.
headers:
Peeker-Request-Id:
$ref: '#/components/headers/PeekerRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
Forbidden:
description: Valid key, but it doesn’t allow this action.
headers:
Peeker-Request-Id:
$ref: '#/components/headers/PeekerRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
RateLimited:
description: Too many requests. Wait `error.details.retry_after_seconds`, then retry.
headers:
Peeker-Request-Id:
$ref: '#/components/headers/PeekerRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
InternalError:
description: Unexpected server error. Retry with backoff and keep the request ID.
headers:
Peeker-Request-Id:
$ref: '#/components/headers/PeekerRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
headers:
PeekerRequestId:
description: Stable request identifier. Log it with the status and response body.
schema:
type: string
example: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: |
Partner API key (`pk_live_…` or `pk_test_…`).
x-default: Bearer pk_test_
````