Workspaces
The workspaces your key can reach: list, read and update them.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
workspaceId | path | integer (int64) | required | The workspace id. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | 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 date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
List workspaces
/v1/workspacesworkspaces.list- Permission
- Any signed-in caller
- Rate limit
- 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:limitorcursoris invalid.
Open to any signed-in caller.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | optional | Only the workspaces whose name contains this text, ignoring case. Omit it for every workspace. |
limit | query | integer (int32) | optional | Number of workspaces per page, from 1 to 200, default 50. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/workspaces?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02"Response 200
data is a list of WorkspaceSummary. Each item has these fields. The response also carries pagination.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a workspace
/v1/workspaces/{workspaceId}workspaces.get- Permission
- Any workspace member except a Network member
- Rate limit
- 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.
curl -X GET "https://api.ken.so/v1/workspaces/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02"Response 200
data is a Workspace.
Show the 29 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a workspace
/v1/workspaces/{workspaceId}workspaces.update- Permission
- The
workspace_settingspermission - Rate limit
- 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. ForreplyTo, the detail codeinvalidmeans the address is malformed,not_connectedmeans no mailbox of the workspace has it, andnot_ingestedmeans Kenso does not read replies from that mailbox. ForinstagramUrl,xUrl,youtubeUrlandgithubUrl, the detail codewrong_platformmeans the link is on another site,not_a_profilemeans it is a post, video or other page rather than a profile, andinvalid_urlmeans 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.linkedinCompanyUrlis 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.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | 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 | optional | The company's website. |
linkedinCompanyUrl | string | optional | The URL of the company's LinkedIn page. |
instagramUrl | string | optional | The company's Instagram profile. Any other link is refused. |
xUrl | string | optional | The company's X profile. Kenso stores a twitter.com link as https://x.com/{handle}. |
youtubeUrl | string | optional | The company's YouTube channel, not a video. |
githubUrl | string | optional | The company's GitHub user or organization. |
companyContext | string | optional | Background about the company that Ken uses as context. |
pauseSendingOnUsHolidays | boolean | optional | 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 | optional | 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) | optional | The reply rate benchmark, in percent from 0 to 100. |
replyRateTarget | number (double) | optional | The reply rate target, in percent from 0 to 100. |
positiveReplyRateBenchmark | number (double) | optional | The interested reply rate benchmark, in percent from 0 to 100. |
positiveReplyRateTarget | number (double) | optional | The interested reply rate target, in percent from 0 to 100. |
meetingsPerMonthBenchmark | number (double) | optional | The benchmark for meetings booked per month, from 0 to 10,000. |
meetingsPerMonthTarget | number (double) | optional | The target for meetings booked per month, from 0 to 10,000. |
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
}'Response 200
data is a Workspace.
Show the 29 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Workspace and account:Your accountSandboxesMembersPermission templatesAccess requestsCreditsCredit estimatesCredit ledgerCredit rate cardCredit savingsCredit savings rowsCredit spendWhite-label brandsCLI loginBug reportsAll resources