Kenso
Get early access

Versioning and compatibility

The Kenso API is versioned by date. The newest version is 2026-11-02. Every endpoint stays under https://api.ken.so/v1: the version goes in a header, never in the URL.

Ken-Version: 2026-11-02

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

A version is the date it shipped, as YYYY-MM-DD. Send the newest when you start building. 1.1 is another 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.

  • 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 date is not a Kenso API version. 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.

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.

Client API v2

The older Client API v2 stays available, frozen, as Legacy v2 on developer.ken.so. New integrations should use this API.

More guides

AuthenticationWorkspacesPaginationErrorsChangelogAPI reference