Skip to main content

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.

Every Partner API request needs a bearer key. You get a live key (pk_live_…) and a sandbox key (pk_test_…) from the Partner portal. Sandbox completes orders instantly with synthetic data and never bills. Switch to live once shapes match.

​
Get a key

1

Open the Partner portal

Go to Settings → API.
2

Create a key

Pick New key, label it, and choose a permission preset. You’ll see the secret once — copy it now.
3

Pick the environment

pk_live_… runs against production. pk_test_… runs against sandbox. Same base URL: https://api.peeker.ai/api/partner/v1.

​
Send the key on every request

curl https://api.peeker.ai/api/partner/v1/me \
  -H "Authorization: Bearer pk_test_<your-key>"
The header format is exactly Authorization: Bearer <key>. No other auth schemes are accepted.

​
Verify with GET /me

GET /me returns the partner record and the key’s environment + preset. It’s the cheapest possible health check — use it as your first call. 
curl https://api.peeker.ai/api/partner/v1/me \
  -H "Authorization: Bearer pk_test_<your-key>"
Response: 
{
  "data": {
    "api_key": {
      "environment": "test",
      "permission_preset": "full"
    },
    "partner": {
      "id": "org_01HZX0OG1A2B3C4D5E6F7G8H",
      "name": "Acme Resellers"
    }
  }
}
A 200 with api_key.environment: "test" confirms you’re hitting sandbox routes.

​
Permission presets

Keys are scoped at creation time. The active preset shows up on GET /me as api_key.permission_preset.
PresetReadsWrites
fullAll resourcesEverything — users, bundles, domains, orders, swaps, imports, forwarding.
limitedAll resourcesDomain availability and quote estimates only. No order creation, swaps, users, bundles, or forwarding.
readAll resourcesNone — every write returns 403 forbidden.
To change a key’s preset, create a new key with the preset you want and revoke the old one — presets are locked at creation.

​
Rotate a key without downtime

1

Create the replacement

Open the Partner portal → API → New key. The new key is valid immediately.
2

Roll your deployment

Push the new key to your environment. Both keys work in parallel during the rollout window.
3

Revoke the old key

Once traffic has moved over, revoke the old key. Revocation is immediate — any in-flight request signed with the old key returns 401 unauthorized.
Revoke immediately if a key leaks. There is no soft-revoke window — the next request after revocation fails with 401 unauthorized.

​
Track requests with Peeker-Request-Id

Every response — success or error — includes a Peeker-Request-Id header. Log it. When you contact support, this is what we look up. 
HTTP/1.1 200 OK
Peeker-Request-Id: req_01HZX0E5K7N9P2Q4R6S8T0U1V3
Content-Type: application/json

​
What an unauthorized response looks like

{
  "error": {
    "code": "unauthorized",
    "message": "API key is missing, malformed, or revoked"
  }
}
Status: 401 Unauthorized. Common causes: missing Authorization header, malformed prefix, or revoked key. A 403 forbidden response means the key is valid but doesn’t have permission for the action. Use a full key (or rotate the existing one to full) for write endpoints. 
{
  "error": {
    "code": "forbidden",
    "message": "API key does not have permission for order_create"
  }
}
Last modified on May 14, 2026