Versioning

Overview

The BlueAI API uses Stripe-style date-based versioning. All endpoints are served under the /api/v1/ prefix, and breaking changes are controlled via the BlueAI-Version header.

BlueAI-Version Header

Include the BlueAI-Version header in your request to pin the API behavior to a specific version. The format is YYYY-MM-DD.

curl https://api.blueai.jp/api/v1/crm/deals \
  -H "BlueAI-Version: 2026-02-22" \
  -H "Authorization: Bearer sk_live_xxx"

Version Resolution Order

The API version is resolved in the following priority order:

1. BlueAI-Version request header (if explicitly provided)
2. Organization default version (set via metadata.api_version)
3. Latest version (currently: 2026-02-22)

Response Header

Every response includes a BlueAI-Version header indicating the version that was actually used.

< HTTP/2 200
< BlueAI-Version: 2026-02-22
< Content-Type: application/json

Current Version

The current latest version is 2026-02-22.

Changelog Endpoint

GET /api/v1/changelog returns the version history and changes for each version.

curl https://api.blueai.jp/api/v1/changelog

{
  "object": "list",
  "data": [
    {
      "version": "2026-02-22",
      "date": "2026-02-22",
      "description": "Initial API version",
      "changes": [
        "Stable release of all v1 endpoints",
        "Stripe-style date-based versioning introduced",
        "BlueAI-Version header support",
        "Organization default API version via metadata"
      ]
    }
  ],
  "latest_version": "2026-02-22",
  "current_version": "2026-02-22",
  "all_versions": ["2026-02-22"]
}

Backward Compatibility

We maintain backward compatibility within the same version. The following changes are treated as non-breaking:

• Adding new fields to responses
• Adding new endpoints
• Adding optional request parameters
• Adding new values to enums

Breaking Changes

When breaking changes are necessary, a new date version is introduced. Requests using older versions maintain existing behavior, and only requests that explicitly specify the new version get the updated behavior.