PARTNER BETA · V1

Build with Empire Scout

Ask the owner to confirm your payment and grant API access, or give you a free gift. In Discord, use !generate api scout for Scout access or !generate api scout,teamsearch for Pro access. No user mention is needed: your key and integration examples arrive privately by DM. Store the key in an environment variable on your backend, never in a browser, public Discord channel or repository. Keys are shown once; revoke and replace a lost key.

Scout a player

POST /api/v1/scouts · API Scout or API Pro

curl https://empire-scout.duckdns.org/api/v1/scouts -H "Authorization: Bearer $EMPIRE_API_KEY" -H "Content-Type: application/json" -d '{"player":"kingofking","format":"gen6ou","autocheckalt":true,"source":"forumsonly"}'

Find teams

POST /api/v1/teamsearch · API Pro only

{"pokemon":["Metagross-Mega","Keldeo"],"format":"gen6ou","source":"forumsonly"}

Python example

import os, requests
r = requests.post(
    "https://empire-scout.duckdns.org/api/v1/scouts",
    headers={"Authorization": "Bearer " + os.environ["EMPIRE_API_KEY"]},
    json={"player": "kingofking", "format": "gen6ou"}, timeout=70)
r.raise_for_status()
result = r.json()
print(result["requestId"], result["data"])

Results and evidence

Success: { "requestId": "...", "version": "v1", "data": {...} }. Scout data includes usage, revealed observations, replay history and identity evidence. Team search returns matches and replay-derived observations. Empty results count as a successful search, not proof that a player never used a team.

Download Excel

Add "output":"xlsx" to either scout or team-search requests. Success returns the workbook directly (Excel Content-Type and Content-Disposition filename), not a JSON download URL. Save the response bytes as .xlsx and attach that file in your bot. X-Empire-Request-Id identifies the export. Errors remain JSON. One successful export consumes one request from the corresponding allowance; failed exports consume none. No matching replays returns 404 without a workbook.

Exports use the existing report layouts in fast mode without sprite downloads. Maximum 500 matches and 8 MB; narrow larger queries. Exact generation formats and forumsonly evidence only. No ladder-prep captures, private games or AI tactical verdicts. Scout autocheckalt defaults to true using confirmed identity evidence. Your app should tolerate new JSON fields.

Allowances and errors

API Scout: $5/month, 250 scouts. API Pro: $10/month, 500 scouts + 100 team searches. API payments and renewal are currently confirmed manually by the owner, not automatically charged by the new API checkout. Allowances reset each UTC calendar month, independently of access expiry. Unused requests do not roll over; key rotation does not reset usage. Twelve requests/minute and two concurrent requests/account. Use !api status to see expiry, remaining requests and last use.

400 invalid query; 401 invalid/revoked key; 403 wrong/no API plan; 413 body too large; 415 wrong content type; 429 rate/concurrency/quota limit; 503 temporarily unavailable. Errors: { "error": "..." }. Failed requests do not consume monthly quota. A lost response can still represent a completed search: repeating it may count again. Idempotent request retries and background jobs are not in this first beta.

Separate developer access

API gifts and purchases do not grant extension memberships. Keep keys private, enforce access controls in your application, and contact the owner for beta access or inaccuracies.