REST API

The Phantom REST API lets your own services read state from and act on the servers you administer through Phantom — moderation cases, economy balances, levelling, tickets, giveaways, the Phantom Network — and lets you receive outbound webhooks when interesting things happen.

It's designed for server-to-server integrations (your backend, a Zap, an n8n flow, a custom dashboard). It is not a browser API — there is no CORS, no cookie auth, and no JavaScript client SDK. Use a bearer token from a server you control.

At a glance

Base URL	https://phantombot.gg/api/v1
Auth	Authorization: Bearer phk_live_…
Transport	HTTPS only (HTTP is rejected)
Format	JSON in, JSON out
Versioning	URL-prefixed (/api/v1)
Rate limits	Per-token, separate read/write buckets
Idempotency	Stripe-style Idempotency-Key on writes
Webhooks	HMAC-SHA256 signed, retried with exponential backoff

What you can do today

Resource	Read	Write
Guild metadata + settings	✅	—
Moderation cases	✅	✅ (note/warn)
Economy wallets + leaderboard	✅	✅ (adjust balance)
Levelling XP + leaderboard	✅	—
Tickets	✅	(reply/close — coming soon)
Giveaways	✅	(end/reroll — coming soon)
Phantom Network lookup	✅	—

Every endpoint is scope-gated — see Authentication.

Five-minute quickstart

1. Mint a token. Open your server's Developer → API Tokens page. Click Mint a token, give it a name, pick the smallest set of scopes you need, and click Create token. Copy the token immediately — it's only shown once.
2. Confirm it works.

   curl https://phantombot.gg/api/v1/me \
       -H "Authorization: Bearer phk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

   You should see your token's preview, scopes and guild id.
3. Read something.

   curl 'https://phantombot.gg/api/v1/cases?per_page=5' \
       -H "Authorization: Bearer phk_live_…"

4. Subscribe to events. Open Developer → Webhooks, add an endpoint, copy the signing secret, and have your receiver verify the Phantom-Signature header — see Webhooks.

Response shape

Every response is JSON. Successful responses carry the resource directly or under a data key for collections:

{
  "data": [ /* … */ ],
  "page": 1,
  "per_page": 25,
  "has_more": true
}

Errors always look like this:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Missing required scope: cases:write.",
    "required_scope": "cases:write"
  }
}

See Errors for the full code catalogue.

What's next?

• Authentication — token format, scopes, IP allowlists
• Rate limits — buckets, headers, 429 handling
• Idempotency — making writes safe to retry
• Endpoints — full resource reference
• Webhooks — receiving events, signature verification
• Event catalogue — every event you can subscribe to
• Errors — every error code and what it means
• Security model — what the API can and can't protect you from