API versioning

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	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 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).

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