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

# Workspaces

> **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 workspaces your key can reach: list, read and update them.

Workspace and account. 3 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/workspaces/openapi.json](/docs/api/workspaces/openapi.json).

- `GET /v1/workspaces` - List workspaces (`workspaces.list`): [/docs/api/workspaces/list.md](/docs/api/workspaces/list.md)
- `GET /v1/workspaces/{workspaceId}` - Get a workspace (`workspaces.get`): [/docs/api/workspaces/get.md](/docs/api/workspaces/get.md)
- `PATCH /v1/workspaces/{workspaceId}` - Update a workspace (`workspaces.update`): [/docs/api/workspaces/update.md](/docs/api/workspaces/update.md)

## List workspaces

`GET /v1/workspaces` - operationId `workspaces.list`

| Permission | Rate limit |
| --- | --- |
| Any signed-in caller | 12,000 requests a minute per API key |

Returns the workspaces the caller belongs to, ordered by id.

`q` keeps only the workspaces whose name contains it, ignoring case. `limit` is from 1 to 200, and the
default is 50.

Errors:

- `400 validation_failed`: `limit` or `cursor` is invalid.

Open to any signed-in caller.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/workspaces/GET/v1/workspaces)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | no | Only the workspaces whose name contains this text, ignoring case. Omit it for every workspace. |
| `limit` | query | integer (int32) | no | Number of workspaces per page, from 1 to 200, default 50. |
| `cursor` | query | string | no | The `nextCursor` from the previous page. Omit it for the first page. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |

### Response 200

`data` is a list of `WorkspaceSummary`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The workspace id. |
| `name` | string | The workspace's name. |
| `isActive` | boolean | Whether the workspace is active. |
| `logoUrl` | string | The URL of the workspace's square icon. Omitted when none is set. |
| `wordmarkUrl` | string | The URL of the workspace's wide logo. Omitted when none is set. |
| `wordmarkDarkUrl` | string | The URL of the workspace's wide logo for dark backgrounds, usually a white version of the wide logo. Booking pages in dark mode show it in place of the wide logo. Null when none is set. |
| `parentWorkspaceId` | integer (int64) | For a white-label client workspace, the workspace that manages it. Omitted otherwise. |
| `brandHostname` | string | The verified custom hostname of the workspace's white-label brand. Omitted when there is none. |
| `isDemo` | boolean | True only on Kenso's demo workspace. |
| `isSandbox` | boolean | True on a developer sandbox: a workspace of your own where sends are simulated and nothing leaves Kenso. |
| `demoBuildsPlayBack` | boolean | Only on Kenso's own demo workspace: true when a new campaign build runs there, with every paid step answered from a recorded real build. Omitted on every other workspace. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/workspaces?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": 812,
      "name": "Northwind Outbound",
      "isActive": true,
      "logoUrl": "https://cdn.example.com/workspaces/812/icon.png",
      "isDemo": false,
      "isSandbox": false
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Get a workspace

`GET /v1/workspaces/{workspaceId}` - operationId `workspaces.get`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 12,000 requests a minute per API key |

Returns the workspace's company details, goals, default Reply-To and brand.

Errors:

- `403 forbidden`: the caller does not belong to the workspace.

Open to any workspace member.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/workspaces/GET/v1/workspaces/%7BworkspaceId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | integer (int64) | yes | The workspace id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |

### Response 200

`data` is a `Workspace`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The workspace id. |
| `name` | string | The workspace's name. |
| `isActive` | boolean | Whether the workspace is active. |
| `website` | string | The company's website. |
| `linkedinCompanyUrl` | string | The URL of the company's LinkedIn page. |
| `instagramUrl` | string | The company's Instagram profile, such as https://www.instagram.com/acme. |
| `xUrl` | string | The company's X profile, such as https://x.com/acme. |
| `youtubeUrl` | string | The company's YouTube channel, such as https://www.youtube.com/@acme. |
| `githubUrl` | string | The company's GitHub user or organization, such as https://github.com/acme. |
| `companyContext` | string | Background about the company that Ken uses as context when it works for this workspace. |
| `ownerLink` | string | Whether Kenso linked the owner named when the workspace was created: `linked`, `already_member`, `user_not_found`, `email_unverified` (a Kenso user holds the email but never verified it, so it was not linked) or `failed`. Omitted otherwise. |
| `logoUrl` | string | The URL of the workspace's square icon. Omitted when none is set. |
| `wordmarkUrl` | string | The URL of the workspace's wide logo. Omitted when none is set. |
| `wordmarkDarkUrl` | string | The URL of the workspace's wide logo for dark backgrounds, usually a white version of the wide logo. Booking pages in dark mode show it in place of the wide logo. Null when none is set. |
| `pauseSendingOnUsHolidays` | boolean | Whether Kenso pauses the workspace's campaigns on US federal holidays. At 11:00 UTC on the holiday (its date in Eastern time) Kenso pauses every campaign sending at that moment, except trigger campaigns, and resumes the ones it paused at 11:00 UTC on the next non-holiday day. A campaign that starts sending later that day still sends, and one a member paused stays paused. Whatever this says, a campaign that sends in each lead's time zone also skips a lead's local public holidays when Kenso knows the lead's country. |
| `replyRateBenchmark` | number (double) | The reply rate benchmark, in percent, so 2.5 is 2.5%. Null when not set. |
| `replyRateTarget` | number (double) | The reply rate target, in percent. Null when not set. |
| `positiveReplyRateBenchmark` | number (double) | The interested reply rate benchmark, in percent. Null when not set. |
| `positiveReplyRateTarget` | number (double) | The interested reply rate target, in percent. Null when not set. |
| `meetingsPerMonthBenchmark` | number (double) | The benchmark for meetings booked per month. Null when not set. |
| `meetingsPerMonthTarget` | number (double) | The target for meetings booked per month. Null when not set. |
| `replyTo` | string | The Reply-To address on the workspace's cold emails, unless a campaign sets its own. Omitted when none is set. |
| `parentWorkspaceId` | integer (int64) | For a white-label client workspace, the workspace that manages it. Omitted otherwise. |
| `isChild` | boolean | True for a white-label client workspace. |
| `hasClients` | boolean | True when the workspace has at least one active Client seat or manages at least one white-label client workspace. |
| `brand` | WorkspaceBrand | The brand the workspace shows, which is the managing workspace's for a white-label client workspace. Omitted when Kenso cannot read it. |
| `isDemo` | boolean | True only on Kenso's demo workspace. |
| `isSandbox` | boolean | True on a developer sandbox: a workspace of your own where sends are simulated and nothing leaves Kenso. |
| `demoPersona` | DemoPersona | Only on Kenso's own demo workspace: the sample member whose calendar, meetings, notes and call queue the demo shows. Omitted on every other workspace. |
| `demoBuildsPlayBack` | boolean | Only on Kenso's own demo workspace: true when a new campaign build runs there, with every paid step answered from a recorded real build. Omitted on every other workspace. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/workspaces/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02"
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "name": "Northwind Outbound",
    "isActive": true,
    "website": "https://northwind-outbound.example.com",
    "companyContext": "Northwind Outbound runs cold email for B2B SaaS companies selling to engineering leaders in North America.",
    "logoUrl": "https://cdn.example.com/workspaces/812/icon.png",
    "pauseSendingOnUsHolidays": true,
    "replyRateBenchmark": 3.5,
    "replyRateTarget": 5,
    "positiveReplyRateBenchmark": 1.2,
    "positiveReplyRateTarget": 2,
    "meetingsPerMonthBenchmark": 8,
    "meetingsPerMonthTarget": 12,
    "replyTo": "replies@mail.example.com",
    "isChild": false,
    "hasClients": false,
    "isDemo": false,
    "isSandbox": false
  }
}
```

## Update a workspace

`PATCH /v1/workspaces/{workspaceId}` - operationId `workspaces.update`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 4,800 requests a minute per API key |

Changes the fields you send and leaves the rest as they are. Returns the updated workspace.

`name` is trimmed and must keep 1 to 50 characters: it cannot be cleared, and a new name cannot contain a
link. Null or an empty string clears `website`, `linkedinCompanyUrl`, `companyContext` and
`replyTo`. A `website` on a free-mail, disposable, relay or agent domain (gmail.com) is not a company's
website, so it clears `website` too.

The reply rate and interested reply rate benchmarks and targets are percents from 0 to 100, counted per person
contacted, not as a share of replies. The meetings per month benchmark and target are from 0 to 10,000. Kenso
keeps two decimals, and null clears one.

`replyTo` must be a mailbox connected to this workspace that Kenso reads replies from. A request with an
invalid field changes nothing.

Errors:

- `400 validation_failed`: a field is invalid. For `replyTo`, the detail code `invalid` means
the address is malformed, `not_connected` means no mailbox of the workspace has it, and
`not_ingested` means Kenso does not read replies from that mailbox.
For `instagramUrl`, `xUrl`, `youtubeUrl` and `githubUrl`, the detail code
`wrong_platform` means the link is on another site, `not_a_profile` means it is a post, video or other
page rather than a profile, and `invalid_url` means it is not a link. Kenso stores each link in one
canonical form (twitter.com becomes x.com), and null or an empty string clears it. `linkedinCompanyUrl` is
stored canonical when it is a LinkedIn company, school or showcase page, and as sent otherwise.
- `403 forbidden`: the caller does not belong to the workspace.

Requires the `workspace_settings` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/workspaces/PATCH/v1/workspaces/%7BworkspaceId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | integer (int64) | yes | The workspace id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The workspace's name, from 1 to 50 characters after trimming. It cannot be cleared, and a new name cannot contain a link. |
| `website` | string | no | The company's website. |
| `linkedinCompanyUrl` | string | no | The URL of the company's LinkedIn page. |
| `instagramUrl` | string | no | The company's Instagram profile. Any other link is refused. |
| `xUrl` | string | no | The company's X profile. Kenso stores a twitter.com link as https://x.com/{handle}. |
| `youtubeUrl` | string | no | The company's YouTube channel, not a video. |
| `githubUrl` | string | no | The company's GitHub user or organization. |
| `companyContext` | string | no | Background about the company that Ken uses as context. |
| `pauseSendingOnUsHolidays` | boolean | no | True to pause the workspace's sending campaigns at 11:00 UTC on each US federal holiday (its Eastern date) and resume them the next non-holiday day, false to keep sending. A campaign that starts sending after the pause still sends that day. |
| `replyTo` | string | no | The default Reply-To address: a mailbox connected to this workspace that Kenso reads replies from, not a member's own mailbox. |
| `replyRateBenchmark` | number (double) | no | The reply rate benchmark, in percent from 0 to 100. |
| `replyRateTarget` | number (double) | no | The reply rate target, in percent from 0 to 100. |
| `positiveReplyRateBenchmark` | number (double) | no | The interested reply rate benchmark, in percent from 0 to 100. |
| `positiveReplyRateTarget` | number (double) | no | The interested reply rate target, in percent from 0 to 100. |
| `meetingsPerMonthBenchmark` | number (double) | no | The benchmark for meetings booked per month, from 0 to 10,000. |
| `meetingsPerMonthTarget` | number (double) | no | The target for meetings booked per month, from 0 to 10,000. |

### Response 200

`data` is a `Workspace`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The workspace id. |
| `name` | string | The workspace's name. |
| `isActive` | boolean | Whether the workspace is active. |
| `website` | string | The company's website. |
| `linkedinCompanyUrl` | string | The URL of the company's LinkedIn page. |
| `instagramUrl` | string | The company's Instagram profile, such as https://www.instagram.com/acme. |
| `xUrl` | string | The company's X profile, such as https://x.com/acme. |
| `youtubeUrl` | string | The company's YouTube channel, such as https://www.youtube.com/@acme. |
| `githubUrl` | string | The company's GitHub user or organization, such as https://github.com/acme. |
| `companyContext` | string | Background about the company that Ken uses as context when it works for this workspace. |
| `ownerLink` | string | Whether Kenso linked the owner named when the workspace was created: `linked`, `already_member`, `user_not_found`, `email_unverified` (a Kenso user holds the email but never verified it, so it was not linked) or `failed`. Omitted otherwise. |
| `logoUrl` | string | The URL of the workspace's square icon. Omitted when none is set. |
| `wordmarkUrl` | string | The URL of the workspace's wide logo. Omitted when none is set. |
| `wordmarkDarkUrl` | string | The URL of the workspace's wide logo for dark backgrounds, usually a white version of the wide logo. Booking pages in dark mode show it in place of the wide logo. Null when none is set. |
| `pauseSendingOnUsHolidays` | boolean | Whether Kenso pauses the workspace's campaigns on US federal holidays. At 11:00 UTC on the holiday (its date in Eastern time) Kenso pauses every campaign sending at that moment, except trigger campaigns, and resumes the ones it paused at 11:00 UTC on the next non-holiday day. A campaign that starts sending later that day still sends, and one a member paused stays paused. Whatever this says, a campaign that sends in each lead's time zone also skips a lead's local public holidays when Kenso knows the lead's country. |
| `replyRateBenchmark` | number (double) | The reply rate benchmark, in percent, so 2.5 is 2.5%. Null when not set. |
| `replyRateTarget` | number (double) | The reply rate target, in percent. Null when not set. |
| `positiveReplyRateBenchmark` | number (double) | The interested reply rate benchmark, in percent. Null when not set. |
| `positiveReplyRateTarget` | number (double) | The interested reply rate target, in percent. Null when not set. |
| `meetingsPerMonthBenchmark` | number (double) | The benchmark for meetings booked per month. Null when not set. |
| `meetingsPerMonthTarget` | number (double) | The target for meetings booked per month. Null when not set. |
| `replyTo` | string | The Reply-To address on the workspace's cold emails, unless a campaign sets its own. Omitted when none is set. |
| `parentWorkspaceId` | integer (int64) | For a white-label client workspace, the workspace that manages it. Omitted otherwise. |
| `isChild` | boolean | True for a white-label client workspace. |
| `hasClients` | boolean | True when the workspace has at least one active Client seat or manages at least one white-label client workspace. |
| `brand` | WorkspaceBrand | The brand the workspace shows, which is the managing workspace's for a white-label client workspace. Omitted when Kenso cannot read it. |
| `isDemo` | boolean | True only on Kenso's demo workspace. |
| `isSandbox` | boolean | True on a developer sandbox: a workspace of your own where sends are simulated and nothing leaves Kenso. |
| `demoPersona` | DemoPersona | Only on Kenso's own demo workspace: the sample member whose calendar, meetings, notes and call queue the demo shows. Omitted on every other workspace. |
| `demoBuildsPlayBack` | boolean | Only on Kenso's own demo workspace: true when a new campaign build runs there, with every paid step answered from a recorded real build. Omitted on every other workspace. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/workspaces/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "website": "https://example.com",
  "linkedinCompanyUrl": "https://example.com",
  "instagramUrl": "https://example.com",
  "xUrl": "https://example.com",
  "youtubeUrl": "https://example.com",
  "githubUrl": "https://example.com",
  "companyContext": "string",
  "pauseSendingOnUsHolidays": true,
  "replyTo": "string",
  "replyRateBenchmark": 0.5,
  "replyRateTarget": 0.5,
  "positiveReplyRateBenchmark": 0.5,
  "positiveReplyRateTarget": 0.5,
  "meetingsPerMonthBenchmark": 0.5,
  "meetingsPerMonthTarget": 0.5
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "name": "Northwind Outbound",
    "isActive": true,
    "website": "https://northwind-outbound.example.com",
    "companyContext": "Northwind Outbound runs cold email for B2B SaaS companies selling to engineering leaders in North America.",
    "logoUrl": "https://cdn.example.com/workspaces/812/icon.png",
    "pauseSendingOnUsHolidays": true,
    "replyRateBenchmark": 3.5,
    "replyRateTarget": 5,
    "positiveReplyRateBenchmark": 1.2,
    "positiveReplyRateTarget": 2,
    "meetingsPerMonthBenchmark": 8,
    "meetingsPerMonthTarget": 12,
    "replyTo": "replies@mail.example.com",
    "isChild": false,
    "hasClients": false,
    "isDemo": false,
    "isSandbox": false
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### WorkspaceBrand

The brand a workspace shows: its product name, logos, app address and accent color.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `productName` | string | no | The product name the workspace shows. |
| `logoUrl` | string | no | The URL of the brand's logo. |
| `faviconUrl` | string | no | The URL of the brand's favicon. |
| `appUrl` | string | no | The base URL of the app for this workspace, such as `https://app.ken.so`. |
| `accentColor` | string | no | The accent color as uppercase `#RRGGBB`. Omitted when Kenso's default color applies. |
| `clientSeats` | WhiteLabelClientSeats | no | The Client seat settings of the white-label workspace behind the brand. Omitted when Kenso cannot read them. |
| `clientApprovalLinks` | boolean | no | The "Client approval links" setting of the white-label workspace behind the brand. Omitted when Kenso cannot read it. |

### DemoPersona

The sample member a demo workspace shows.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memberId` | integer (int64) | no | The member's id. |
| `email` | string | no | The member's email address. |

### WhiteLabelClientSeats

The Client seat settings a white-label workspace chose for its client workspaces.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `readReplies` | boolean | no | "Clients can read replies", the Client template's default: true gives Inbox edit and the `reply` permission, false turns Inbox off. Default false. An edited Client template keeps its edit. |

All resources: [/docs.md](/docs.md).
