Auth · errors · conventions
Verification
All /api/v1/* is Authorization: Bearer sd_live_… authenticate with a header. API keys are scoped to a workspace and act with admin permissions. The web app uses the same API with session cookies.
curl https://send.ad/api/v1/me -H "Authorization: Bearer $SEND_API_KEY"
Error
Failures return { "error": "human-readable message", "code": "machine_code" } . Codes you'll see often:
| code | HTTP | Meaning |
|---|---|---|
| bad_api_key | 401 | Key is missing or revoked |
| admin_only | 403 | Admin-only action (sending · settings · billing) |
| insufficient_balance | 402 | Insufficient balance — /api/v1/billing/topup |
| sender_profile_incomplete | 400 | Company name, address, or contact is empty |
| night_consent_required | 400 | Scheduled for 9pm–8am without the night-time consent box checked |
| rate_limited | 429 | Too many requests |
Conventions
IDs are UUIDs, times are ISO 8601, money is stored as whole units, and emails are stored lowercase. Lists accept ?page=&limit=(default 50 · max 500) and return { items, total, page, limit } .