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

API keys

Every API request needs an API key. Create keys in the dashboard under API keys, or through the API with a full-access key.

Using a key

Send the key as a bearer token:

Authorization: Bearer sg_live_...

Keys are secret. Use them only from your server, never in a browser or a mobile app. The full key is shown once, when you create it. After that, Spamgone shows only a short prefix such as sg_live_AbCd, and stores nothing that can be turned back into the key.

Modes

Mode Prefix What it does
live sg_live_ Real checks, counted toward your plan.
test sg_test_ Fixed results that are never counted and never call the AI model. For building and for CI.

A test key can only create, rotate or revoke other test keys, so a leaked one can't affect live traffic.

Permissions

Permission Allowed
full_access Every team endpoint that isn't for admins only, including managing keys.
check_only Creating checks, sending feedback on its own checks, and the Perspective-compatible endpoints.

Give the key inside your app check_only, so a leak can't be used to read your history or manage your account.

Managing keys through the API

All of these need a full-access key.

Method and path What it does
POST /v1/api-keys Creates a key from name, mode (default live) and permission (default full_access). The response includes token, the full key, once.
GET /v1/api-keys Lists the keys that still work, with prefix, last_used_at and request_count.
DELETE /v1/api-keys/{id} Revokes a key. It stops working within a minute.
POST /v1/api-keys/{id}/rotate Creates a new key with the same name, mode and permission. Send overlap_seconds (up to 86400) to keep the old key working that long.

Each plan sets how many keys that still work a team can have: 25 on Free and Pro, 100 on Scale, and no limit on Enterprise. People must verify their email address before they create keys.

Usage

last_used_at and request_count update within a minute of each request.

Errors

name Status Meaning
missing_api_key 401 No key was sent in the Authorization header.
invalid_api_key 403 The key is unknown, revoked or past its rotation overlap.
restricted_api_key 403 The key's permission or mode doesn't allow this request.
api_key_limit_reached 422 The team already has the most keys its plan allows.
email_not_verified 403 The person creating the key hasn't verified their email address.