Perspective API shuts down on December 31, 2026.Switch by changing one URL

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_processed instead, 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 20
  • after or before: 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.