> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [https://api.ken.so/v1/docs/openapi.json](https://api.ken.so/v1/docs/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Versioning and compatibility

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

The Kenso API is versioned by date: a version is the day it shipped, as `YYYY-MM-DD`, and the newest is `2026-11-02`. Every endpoint stays under `https://api.ken.so/v1`: the version goes in a header, never in the URL.

## The Ken-Version header

```http
GET /v1/campaigns HTTP/1.1
Host: api.ken.so
Authorization: Bearer <your_api_key>
Ken-Version: 2026-11-02
X-Ken-Workspace-Id: 812
```

Send the newest, `2026-11-02`, when you start building, spelled exactly like that: `2026-11-2` and `v1.1` are not versions, and answer `400 unsupported_version`. `1.1` is an older name for the first dated version and works for as long as that version does.

When a request runs on a dated version, the response carries a `Ken-Version` header with the version that answered it.

## Your API key's version

A new key is pinned to the newest version by default. A request with that key and no `Ken-Version` header gets the key's version. A header always wins over the key's version. See or change a key's version in the Kenso app under [Settings > Integrations > API keys](https://app.ken.so/settings/api-keys).

- Keys created before dated versions have no version: the app shows them as Legacy. A request with such a key and no header gets the legacy response shape, as it always did. Send the header, or give the key a version.
- To move to a newer version, send the new date in the header from one client first. When it works, change the key's version.

## Legacy: 1.0

`Ken-Version: 1.0` asks for the legacy shape that some paths served before this reference, even with a key that has a version. Legacy is not a dated version and is not documented here. Use it only for old integrations.

## Version errors

| Status | `code` | When |
| --- | --- | --- |
| 400 | `unsupported_version` | The header is not a Kenso API version, such as an unknown date or a typo like `2026-11-2`. `details` lists the versions you can send. |
| 400 | `version_retired` | The version in your header, or your key's version, has retired. `details` names it and the oldest and newest versions you can move to. |

## How a version retires

A version keeps working for 12 months after the next version ships, then retires. The newest version never retires. Once a newer version ships, responses on the older one carry two headers:

```http
Deprecation: true
Sunset: Wed, 01 Mar 2028 00:00:00 GMT
```

`Sunset` is the date the version retires. From then on, a request on it answers `400` with the code `version_retired`. Every change, and the version it shipped in, is in the [changelog](/docs/changelog).

## What changes without a new version

A version keeps its shape until it retires. New fields, endpoints and enum values can appear in it at any time. Removing or renaming something, or changing what it means, ships only in a new version.

- Ignore fields you do not know: new ones appear without notice.
- Treat an unknown enum value as possible: enums gain values.

## How responses look

A single resource comes back in `data`:

```json
{ "success": true, "data": { "id": 812, "name": "Q4 SaaS founders" } }
```

- Fields are camelCase. Ids are integers, except thread (`thr_...`), message (`msg_...`) and attachment (`att_...`) ids, which are opaque strings.
- Times are UTC ISO 8601 (`2026-09-23T15:02:11Z`). Calendar dates are `YYYY-MM-DD`.
- Enums are lowercase snake_case strings.
- Fields that are `null` are left out of the response. Treat a missing optional field as `null`.

Lists add a `pagination` object: see [Pagination](/docs/pagination).

## Client API v2

The older Client API v2 stays available, frozen. Its reference is at [api.ken.so/v2/docs](https://api.ken.so/v2/docs/). New integrations should use this API.

## More guides

- [Authentication](/docs/authentication.md)
- [Workspaces](/docs/workspaces.md)
- [Pagination](/docs/pagination.md)
- [Errors](/docs/errors.md)
- [Rate limits](/docs/rate-limits.md)
- [Idempotency](/docs/idempotency.md)
- [Webhooks](/docs/webhooks.md)
- [Changelog](/docs/changelog.md)
- [API reference](/docs.md)
