API conventions
Every Spamgone API endpoint follows these rules.
Versions
All endpoints live under a version prefix, starting with /v1. Breaking changes only ship under a new version. An old version keeps working for at least 6 months after its deprecation is announced in the changelog.
Authentication
Send your API key as a bearer token:
Authorization: Bearer sg_live_...Keys are secret. Only call the API from your server, never from a browser. The API sends no CORS headers, so browsers can't read its responses.
Errors
Every error uses the same JSON body:
{
"statusCode": 422,
"name": "validation_error",
"message": "`text` is required."
}name is stable, so you can rely on it in code. message is for people and may change.
name |
Status | Meaning |
|---|---|---|
validation_error |
422 | A field is missing or invalid. The message names it. |
text_too_long |
422 | text is longer than 10,000 characters. |
missing_api_key |
401 | No API key was sent. |
invalid_api_key |
403 | The key is unknown or was revoked. |
restricted_api_key |
403 | The key's permission doesn't allow this endpoint. |
admin_required |
403 | Only team admins can do this. |
email_not_verified |
403 | Verify your email address first. |
free_team_limit_reached |
403 | You already have the most Free teams allowed. Upgrade one to create another. |
api_key_limit_reached |
422 | The team has the most API keys its plan allows. Revoke one first. |
overage_not_available |
422 | The team's plan doesn't offer pay-as-you-go checks. |
webhook_limit_reached |
422 | The team has the most webhook endpoints its plan allows. Delete one first. |
member_limit_reached |
422 | The team has the most members its plan allows. |
not_found |
404 | The endpoint or resource doesn't exist. |
method_not_allowed |
405 | The endpoint doesn't support this HTTP method. |
idempotency_key_reused |
409 | The Idempotency-Key was already used with a different body. |
idempotency_key_in_use |
409 | A request with this Idempotency-Key is still running. Retry shortly. |
already_processed |
409 | This request already succeeded, and its response showed a secret once. List what it created instead of repeating it. |
rate_limit_exceeded |
429 | Too many requests per second. Wait for retry-after. |
daily_quota_exceeded |
429 | The daily check limit is used up. |
monthly_quota_exceeded |
429 | The monthly check limit is used up. |
overage_cap_reached |
429 | Pay-as-you-go checks reached the cap the team set. |
internal_server_error |
500 | Something failed on our side. Retry, and contact support with the request ID if it continues. |
model_unavailable |
503 | Checks are temporarily unavailable. Wait for retry-after. |
capacity_paused |
503 | Checks that need the AI model are paused for a moment. Rule matches, cached results and test keys keep working. Wait for retry-after. |
billing_unavailable |
503 | Online payments aren't switched on. Contact us to change plans. |
Request IDs
Every response has an x-request-id header. Include it when you contact support, so we can find the exact call.
Idempotency
Every POST request accepts an Idempotency-Key header (1 to 255 characters). For 24 hours:
- If you repeat a request with the same key and body, you get the first response back, with
idempotent-replayed: true. Nothing runs twice, and nothing is counted twice. - If you reuse a key with a different body, you get
409 idempotency_key_reused. - Server errors (5xx) are not kept, so you can retry them with the same key.
- Responses that show a secret once are never stored: creating or rotating an API key, and creating a webhook endpoint or rotating its secret. Repeating one of those gets
409 already_processedinstead, so list your keys or endpoints to find what it created.
Keys are scoped to your team and to the endpoint.
Pagination
List endpoints accept:
limit: 1 to 100, default 20afterorbefore: an item ID to page from (not both)
Responses look like this:
{ "object": "list", "data": [], "has_more": false }To get the next page, pass the last item's id as after.
Rate-limit headers
Authenticated responses include ratelimit-limit, ratelimit-remaining and ratelimit-reset. A 429 response also includes retry-after, in seconds.