Skip to Content
Workspace and account

Workspaces

The workspaces your key can reach: list, read and update them.

Workspace and account3 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
workspaceIdpathinteger (int64)requiredThe workspace id.

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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

GET/v1/workspacesworkspaces.list
Permission
Any signed-in caller
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Parameters

NameInTypeRequiredDescription
qquerystringoptionalOnly the workspaces whose name contains this text, ignoring case. Omit it for every workspace.
limitqueryinteger (int32)optionalNumber of workspaces per page, from 1 to 200, default 50.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
Request
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

GET/v1/workspaces/{workspaceId}workspaces.get
Permission
Any workspace member except a Network member
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

PATCH/v1/workspaces/{workspaceId}workspaces.update
Permission
The workspace_settings permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringoptionalThe workspace's name, from 1 to 50 characters after trimming. It cannot be cleared, and a new name cannot contain a link.
websitestringoptionalThe company's website.
linkedinCompanyUrlstringoptionalThe URL of the company's LinkedIn page.
instagramUrlstringoptionalThe company's Instagram profile. Any other link is refused.
xUrlstringoptionalThe company's X profile. Kenso stores a twitter.com link as https://x.com/{handle}.
youtubeUrlstringoptionalThe company's YouTube channel, not a video.
githubUrlstringoptionalThe company's GitHub user or organization.
companyContextstringoptionalBackground about the company that Ken uses as context.
pauseSendingOnUsHolidaysbooleanoptionalTrue 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.
replyTostringoptionalThe default Reply-To address: a mailbox connected to this workspace that Kenso reads replies from, not a member's own mailbox.
replyRateBenchmarknumber (double)optionalThe reply rate benchmark, in percent from 0 to 100.
replyRateTargetnumber (double)optionalThe reply rate target, in percent from 0 to 100.
positiveReplyRateBenchmarknumber (double)optionalThe interested reply rate benchmark, in percent from 0 to 100.
positiveReplyRateTargetnumber (double)optionalThe interested reply rate target, in percent from 0 to 100.
meetingsPerMonthBenchmarknumber (double)optionalThe benchmark for meetings booked per month, from 0 to 10,000.
meetingsPerMonthTargetnumber (double)optionalThe target for meetings booked per month, from 0 to 10,000.
Request
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.


On this page