# 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:

```json
{
  "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:

```json
{ "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.
