> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> Select a date-versioned API contract with the Brightalk-Version header.

Brightalk uses date-based contract versions so a server can choose the API behavior it integrates against.

## Use an unversioned URL

All requests use the production base URL `https://api.brightalk.ai`. Version numbers are not part of the path; for example, create a call at `POST /calls`.

## Send Brightalk-Version

Send the supported date version explicitly on every request:

```http theme={null}
Brightalk-Version: 2026-07-16
```

Every response echoes the version actually applied in its `Brightalk-Version` header. Keep the header value in configuration so an intentional contract upgrade can be reviewed and tested.

## Understand omission and defaults

Each organization has a pinned default API version. If a request omits `Brightalk-Version`, Brightalk uses that pinned default and still returns the applied version in the response header. Omission does not select an arbitrary newest version.

## Handle an unsupported version

An unknown or retired value returns `400 unsupported_version`. The optional machine-readable details list supported versions:

```json theme={null}
{
  "error": {
    "code": "unsupported_version",
    "message": "The requested API version is not supported.",
    "request_id": "req_demo_001",
    "details": {
      "supported_versions": ["2026-07-16"]
    }
  }
}
```

Breaking response or behavior changes require another date version. Additive response fields may appear within a version, so clients should ignore unknown response fields.