---
title: API versioning | SafetyKit
description: How SafetyKit API versions work, the current and superseded versions, and how to upgrade.
---

API versioning applies to the Content API (`POST /v1/content`). Other endpoints are not versioned yet and ignore the version header. Versions are named by release date. A new version is released only for a backwards-incompatible change. Additive changes, such as new optional fields, ship under the existing version.

Each Content API request resolves its version in this order:

1. The `SafetyKit-Version` request header, for example `SafetyKit-Version: 2026-08-05`. An unknown value returns a 400 with the list of valid versions.
2. Your account’s pinned version. Accounts are pinned to the version that was current when they integrated. Contact <support@safetykit.com> to change your pin.
3. The latest version.

Every Content API response includes a `SafetyKit-Version` header naming the version that served it.

To test an upgrade, send the `SafetyKit-Version` header with the new version on individual requests before changing your account pin.

## Versions

| Version                                                          | Status     | Notes                                                                                                              |
| ---------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
| `2026-08-11`                                                     | Current    | Content API: request takes a `content` array of typed parts; response returns `labels` with a `type` discriminator |
| [`2026-08-05`](/api-versions/2026-08-05/content/create/index.md) | Superseded | Original content API shape                                                                                         |

## 2026-08-11

Breaking changes to `POST /v1/content`:

- Request: the `text` and `images` fields are replaced by a `content` array of typed parts. Each part carries an optional `key` naming where it came from.
- Response: the `policies` and `reference_set_matches` arrays are replaced by a single `labels` array. Each entry has a `type`: `classifier` entries carry `label` and a nullable `score`; `similarity` entries carry `set_id` and appear only when a reference set matched. The per-policy `version` field is removed and the response includes the API `version` that served it.

See the [Content reference](/api/resources/content/methods/create/index.md) for the current shapes.

## 2026-08-05 (superseded)

`POST /v1/content` with the `SafetyKit-Version: 2026-08-05` header or a pinned account.

Request:

```
{
  "user_id": "user_123",
  "content_id": "post_42",
  "text": "Hey, is this still available?",
  "images": ["data:image/jpeg;base64,/9j/4AAQSkZJRg..."],
  "metadata": { "channel": "marketplace_dm" }
}
```

`text` and `images` are each optional. At least one is required. Text at most 16,000 characters, at most 20 images, 5MB per image, 6MB per request.

Response:

```
{
  "content_id": "post_42",
  "user_id": "user_123",
  "policies": [
    {
      "policy_id": "phishing",
      "version": "v3",
      "score": 0.12,
      "decision": "not_match",
      "escalation": "none"
    }
  ],
  "reference_set_matches": [{ "set_id": "known_scam_messages", "similarity": 0.94 }]
}
```

`decision` is `match`, `not_match`, or `review`. `escalation` is `none`, `completed`, or `error`. `score` is null when no classifier scored the policy. Full reference: [Classify content (2026-08-05)](/api-versions/2026-08-05/content/create/index.md).

## Backwards-compatible changes

The following never create a new version:

- Adding new API endpoints
- Adding new optional request fields
- Adding new fields to responses
- Adding new values to enums
- Adding new label or policy identifiers
- Changing the length or format of opaque identifiers and error messages