Start
Base URL https://usedefeated.com/api. Every response is JSON with an ok boolean. The public API lives under /api/v1 and takes a key; the account endpoints under /api take a session cookie and are what the dashboard uses.
Authentication
Send your key as a bearer token on every /api/v1 request:
Keys are stored as a SHA-256 hash. We can show you the prefix and the date it was issued; we cannot show you the key again. If you lose it, rotate it from the dashboard.
Keys
| Format | dft_live_ followed by 48 hexadecimal characters — 57 characters total. |
|---|---|
| Issued | Once on sign-up, and on every rotation. Rotating invalidates the previous key immediately. |
| Scope | One key per account. It identifies the account; it does not carry roles. |
| Storage | Treat it like a password. Never put it in client-side code or a public repository. |
GET/api/v1/ping
Proves the key works and tells you which account it belongs to. Counts as one request.
GET/api/v1/usage
Requests per day for the last 30 days, and the total. Counts as one request.
Account endpoints
These use an HttpOnly session cookie set by sign-up or sign-in, so they are meant for the dashboard rather than for scripts. Sessions last 30 days.
| Endpoint | Body / result |
|---|---|
POST/api/signup | { email, password } → { ok, email, api_key, key_prefix }. Password must be 10+ characters. 409 if the email exists. |
POST/api/signin | { email, password } → { ok, email } and the session cookie. |
POST/api/signout | Ends the session and clears the cookie. |
GET/api/me | { ok, email, key_prefix, key_created, created_at, requests_30d } |
POST/api/key/rotate | → { ok, api_key, key_prefix }. The old key stops working at once. |
Errors
Failures return a non-2xx status and { "ok": false, "error": "…" }. The message is meant to be shown to a person.
| Status | Meaning |
|---|---|
400 | Bad or missing input. The message says which field. |
401 | No valid key or session. |
404 | Unknown endpoint. |
409 | Sign-up with an email that already has an account. |
429 | Rate limited. Wait for the window to pass. |
Rate limits
| Sign-up | 5 per 10 minutes per address |
|---|---|
| Sign-in | 10 per minute per address |
| /api/v1 | No fixed ceiling on v1 today; usage is counted per key per day and visible at /api/v1/usage. Limits will be announced here before they apply. |
Buying
The API key is free. Verdicts, analyst time and higher rate limits are sold by request — email support@usedefeated.com with what you want settled and we will quote it.