Workspace workspace
Workspaces. get, update and the tracking operations take workspace_id.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through workspace_read and changes through workspace_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: members-create, create, delete-logo, get, get-tracking, list, replace-logo, replace-tracking, test-tracking, update, delivery_health, get_my_workspaces, set_logo_from_url, test_delivery
members-create
Write. POST https://api.ken.so/v1/members
Body (json): userId integer
Add an existing Kenso user to the current workspace, with no email invite. New members get role member. Requires a workspace admin. Outside Kenso staff, only a user who already shares a workspace with the caller.
POST /api/v1/members {userId} with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. The backend requires a workspace
admin. Replaces legacy POST /v1/clients/{id}/users.
user_id is the Kenso user id and becomes the member id. A new member returns
201 with Location /v1/members/{memberId} and role member. A user who is
already a member returns 200 with the same body and the stored role
unchanged, so the call is safe to repeat. Unless the caller is Kenso staff,
the user must already share a workspace with the caller; an unknown user
and a user the caller shares no workspace with are both not_found.
Outside Kenso's own workspaces a Kenso staff account is not_found too,
whoever the caller is. A credential with no Kenso user behind it is
forbidden. Invite anyone else by
email with the invitations operations instead.
To promote the member, call members(operation="update") afterwards.
Envelope: success plus data (the member).
create
Write. POST https://api.ken.so/v1/workspaces
Body (json): name string, turnstileToken string
Create a workspace for the caller. An existing workspace with this setup is returned again.
POST /api/v1/workspaces with Ken-Version 1.1. Internal exposure. name is required. Idempotent: an existing workspace comes back with HTTP 200, and a new workspace with HTTP 201. Both use the canonical resource envelope.
delete-logo
Write. DELETE https://api.ken.so/v1/workspaces/{workspaceId}/logo
Path: workspaceId
Remove the workspace logo (the square icon). Empty success means the logo was removed. The wide logo stays.
DELETE /api/v1/workspaces/{workspaceId}/logo with Ken-Version 1.1.
Internal exposure. The backend returns 204 with an empty body.
get
Read. GET https://api.ken.so/v1/workspaces/{workspaceId}
Path: workspaceId
Return one workspace. Non-members receive 403, including super admins.
GET /api/v1/workspaces/{workspaceId} with Ken-Version 1.1. Public.
workspace_id is the path id. Non-members receive 403. Staff
cross-workspace access stays on /v1/admin. Response envelope:
success plus data. replyTo is the workspace default Reply-To on Kenso
Sequencer cold emails (omitted when unset). hasClients is true when the
workspace has an active member with the Client role or a child
workspace.
The workspace's benchmark and target are always present, null when
not set: replyRateBenchmark, replyRateTarget,
positiveReplyRateBenchmark and positiveReplyRateTarget are percent
of people contacted (2.5 means 2.5%); meetingsPerMonthBenchmark and
meetingsPerMonthTarget are meetings booked per month.
get-tracking
Read. GET https://api.ken.so/v1/workspaces/{workspaceId}/tracking
Path: workspaceId
Return the workspace tracking settings. Secrets are write-only and are not returned.
GET /api/v1/workspaces/{workspaceId}/tracking with Ken-Version 1.1.
Internal exposure. The backend requires a workspace admin.
Response envelope: success plus data.
list
Read. GET https://api.ken.so/v1/workspaces
Query: cursor string, limit integer, q string
List the caller's workspaces. q matches the workspace name. Cursor pages are ordered by id.
GET /api/v1/workspaces with Ken-Version 1.1. Public. q matches the workspace name. limit is 1..200; omit it to use the backend default of 50. cursor is the opaque pagination cursor from pagination.nextCursor. The envelope is a canonical list: success, data (array), and pagination.hasMore / pagination.nextCursor.
replace-logo
Write. PUT https://api.ken.so/v1/workspaces/{workspaceId}/logo
Path: workspaceId
Replace the workspace logo (the square icon) from an image or a source URL. Pass file_content_base64 plus file_name, or source_url, not both. Images are PNG, JPEG, or WebP. The wide logo is members operation workspaces-replace-wordmark.
PUT /api/v1/workspaces/{workspaceId}/logo with Ken-Version 1.1.
Internal exposure. The backend requires a workspace admin.
This is the square icon, shown in small spots such as the workspace
switcher; the response returns it as logoUrl. The wide logo (wordmark)
that booking pages show first is members operation
workspaces-replace-wordmark.
file_content_base64 is the image bytes in base64 and file_name its name;
they upload multipart field file (PNG, JPEG, or WebP, under 10 MB).
The hosted MCP refuses file_path, because it cannot read your machine;
off the hosted MCP, file_path opens only a file inside the MCP export
directory. source_url sends JSON sourceUrl instead. Provide exactly one
source. Response envelope: success plus the workspace resource.
replace-tracking
Write. PUT https://api.ken.so/v1/workspaces/{workspaceId}/tracking
Path: workspaceId
Body (json): adrollId string, ga4ApiSecret string, googleAnalyticsId string, googleTagManagerId string, isGa4DeliveryEnabled boolean, isMetaDeliveryEnabled boolean, metaCapiToken string, metaPixelId string
Replace workspace tracking settings. Absent fields stay unchanged. Empty string clears an id or secret. Secrets are write-only.
PUT /api/v1/workspaces/{workspaceId}/tracking with Ken-Version 1.1.
Internal exposure. The backend requires a workspace admin.
Omit a field to leave it unchanged. An empty string clears an id or
secret. Delivery flags are booleans. Secrets are write-only on later
reads. Response envelope: success plus data.
test-tracking
Write. POST https://api.ken.so/v1/workspaces/{workspaceId}/tracking/test
Path: workspaceId
Body (json): provider string, testEventCode string
Send a tracking test event for ga4 or meta. test_event_code is required when provider is meta.
POST /api/v1/workspaces/{workspaceId}/tracking/test with Ken-Version 1.1.
Internal exposure. The backend requires a workspace admin.
provider is ga4 or meta. test_event_code is required for meta and
optional for ga4. Response envelope: success plus data
(provider, isDelivered, statusCode, providerResponse, testEventId, sentAt).
update
Write. PATCH https://api.ken.so/v1/workspaces/{workspaceId}
Path: workspaceId
Body (json): companyContext string, githubUrl string, instagramUrl string, linkedinCompanyUrl string, meetingsPerMonthBenchmark number, meetingsPerMonthTarget number, name string, pauseSendingOnUsHolidays boolean, positiveReplyRateBenchmark number, positiveReplyRateTarget number, replyRateBenchmark number, replyRateTarget number, replyTo string, website string, xUrl string, youtubeUrl string
Update a workspace. Absent fields stay unchanged. Empty string clears a string other than name. Name cannot be cleared. reply_to sets the default Reply-To address on the workspace's cold emails.
PATCH /api/v1/workspaces/{workspaceId} with Ken-Version 1.1. Public
in the catalog. The backend still requires a workspace admin.
Omit a field to leave it unchanged. An empty string clears website,
linkedin_company_url, instagram_url, x_url, youtube_url, github_url,
company_context, or reply_to. name cannot be blank.
pause_sending_on_us_holidays is a boolean. When true, at 11:00 UTC on
each US federal holiday (its Eastern date) Kenso pauses the workspace's
campaigns that are sending at that moment, except trigger campaigns, and
resumes the ones it paused at 11:00 UTC the next non-holiday day. Emails
sent earlier that day already went out, and a campaign that starts
sending after the pause still sends that day, so do not promise that
nothing sends on the holiday. A campaign a member pauses stays paused.
Whatever it 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.
Profile links: instagram_url, x_url, youtube_url and github_url are the
company's own profiles. Kenso stores each in one canonical form
(twitter.com becomes https://x.com/<handle>, github.com/orgs/<owner>
becomes https://github.com/<owner>). A link on another site, or a post,
video or search page instead of a profile, is 400 validation_failed with
detail code wrong_platform, not_a_profile or invalid_url on instagramUrl,
xUrl, youtubeUrl or githubUrl. linkedin_company_url is stored canonical
when it is a LinkedIn company, school or showcase page, else as sent.
reply_to is the default Reply-To on every Kenso Sequencer cold email this
workspace sends. Replies go to that address instead of the sending inbox,
so it survives send-inbox and domain rotation. A campaign can override it
with campaigns(operation="update", reply_to=...), and a send from a
sending provider identity on a reply_to_inbox connection takes the
connection's Reply-To inbox first. The address must be a live mailbox
connected to this same workspace that Kenso reads replies from, or a sending
provider identity whose provider receives its replies, not a member's own
mailbox (so stop-on-reply and the Master Inbox
keep working), else 400 validation_failed on field replyTo with detail
code not_connected or not_ingested. Kenso brand domains (ken.so,
getken.ai, ...) are refused. When it equals the sending inbox no header is
written. An empty string clears it. The workspace response carries replyTo
(omitted when unset).
Benchmark and target: reply_rate_* and positive_reply_rate_* are replies
and interested replies per person contacted, in percent, 0 to 100 (2.5
means 2.5%), not the share of replies; meetings_per_month_* are meetings
booked per month, 0 to 10000. Out of range is 400 validation_failed.
clear_goals names the ones to set back to null, e.g. ["reply_rate_target"].
Set them only from a number the user gave, with its source.
Response envelope: success plus data.
delivery_health
Write.
Test server-side GA4/Meta click delivery and read its delivery health. Ops: test_delivery, delivery_health.
Workspace-level server-side ad-network click delivery (GA4 Measurement
Protocol + Meta Conversions API).
Routes (workspace id = client_id):
- POST /v1/workspaces/{id}/tracking/test
- GET /v1/workspaces/{id}/tracking/delivery-health
Authorization: client admin of the workspace (or SuperAdmin). Path client_id is
the workspace id. Both operations require client-admin (backend
TenantAccessGuard.HasClientAdminAccessAsync); the MCP policy layer surfaces
a clean validation error for members rather than a raw backend 403.
Operations:
-----------
test_delivery:
POST a synthetic click through the real provider clients so operators can
verify credentials BEFORE enabling production delivery. Delivery enable
flags are ignored - only account id + stored secret are required.
provider: "ga4" | "meta" (required).
- ga4: posts to GA4 Measurement Protocol /debug/mp/collect (validation mode;
nothing lands in production GA4). No test_event_code.
- meta: posts to Meta Conversions API. test_event_code is REQUIRED so the
event routes to Meta Events Manager > Test events and never lands as a
live conversion. Get a code from Meta Events Manager > Test events.
Envelope semantics: top-level success=true means "the test ran". Inspect
data.delivered for provider acceptance. A provider rejection returns
delivered=false with success=true - surface as information, not an error.
data shape:
{ provider, delivered, statusCode, providerResponse, testEventId, sentAtUtc }
Example GA4: operation="test_delivery", client_id=42, provider="ga4"
Example Meta: operation="test_delivery", client_id=42, provider="meta",
test_event_code="TEST12345"
delivery_health:
GET per-provider delivery health over a trailing window (default 7 days,
clamp 1..30 via window_days). Always returns both ga4 and meta cards.
Envelope data shape (array of two provider cards, NOT an object keyed by
provider name):
{
"providers": [
{"provider": "ga4", "configured": bool, "deliveryEnabled": bool,
"lastSuccessfulTestAt": str|null, "pending": n, "delivered": n,
"failed": n, "deadLettered": n, "suppressed": n,
"lastDeliveredAt": str|null, "missingBrowserIdentifiers": n,
"recentFailures": [...]},
{"provider": "meta", ...}
],
"windowDays": n
}
Each provider card includes: configured, deliveryEnabled, lastSuccessfulTestAt,
status bucket counts (pending/delivered/failed/deadLettered/suppressed),
lastDeliveredAt, missingBrowserIdentifiers (Meta _fbp/_fbc gaps in the
window; 0 for GA4; not a delivery gate), and recentFailures (max 10;
error strings pre-scrubbed; optional matchQualityNotes).
Example: operation="delivery_health", client_id=42, window_days=14
Parameters:
-----------
client : KenAPIClient
Injected automatically - do not pass.
operation : str
test_delivery | delivery_health
client_id : int
Workspace (client) id - required for all operations.
provider : "ga4" | "meta", optional
Required for test_delivery.
test_event_code : str, optional
Required when provider="meta" on test_delivery. Ignored for ga4.
window_days : int, optional
Trailing window for delivery_health (default 7, clamped 1..30 by backend).
Returns:
--------
Kenso response envelope: {"success": bool, "message": str, "data": ...}
get_my_workspaces
Read.
Manage Kenso clients/tenants (workspaces): delete, archive, campaigns, contacts, users, logo. Client-facing: get_my_workspaces, set_logo_from_url.
Manage clients (tenants) in Kenso platform.
Clients are the top-level organizational units representing companies or customers
using the Kenso platform. Each client can have multiple campaigns, and contacts
are deduplicated based on the client's duplicate treatment settings.
Client-facing sub-surface (task 15 / D6):
----------------------------------------
On the client-facing host, non-staff principals may only use:
get_my_workspaces, set_logo_from_url.
- set_logo_from_url POSTs a public image URL; the backend fetches it server-side
behind its SSRF guard (the agent never uploads bytes).
set_logo_from_url needs the workspace_settings permission in the pinned workspace.
Staff / internal host keep the full SuperAdmin ClientController surface.
Operations:
-----------
delete:
Delete a client (soft delete).
Example: operation="delete", client_id=42
archive:
Archive (deactivate) a client by setting active=false. Use when cancelling a client.
The client data is preserved but the client is marked as inactive.
Example: operation="archive", client_id=42
get_campaigns:
Get all campaigns for a client.
Example: operation="get_campaigns", client_id=42
get_contacts:
Get contacts for a client with pagination.
Example: operation="get_contacts", client_id=42, page_index=1
get_my_workspaces:
Get all workspaces (clients) the current user has access to.
Optionally include inactive workspaces. No client_id required.
Example: operation="get_my_workspaces", include_inactive=True
assign_user:
Assign a user to a client. Admin-only. Requires client_id and user_id.
Outside Kenso's own workspaces a Kenso staff account is not found,
whoever the caller is.
Example: operation="assign_user", client_id=42, user_id=123
Canonical replacement: workspace(operation="members-create") (POST /v1/members, Ken-Version 1.1).
remove_user:
Remove a user from a client. Admin-only. Requires client_id and user_id.
Example: operation="remove_user", client_id=42, user_id=123
set_logo_from_url:
Set the workspace company logo from a public HTTPS image URL.
Backend fetches the URL behind its SSRF guard and stores the image.
Requires client_id and logo_url, and the workspace_settings permission.
Example: operation="set_logo_from_url", client_id=42,
logo_url="https://cdn.example.com/logo.png"
Parameters:
-----------
client : KenAPIClient
API client instance
operation : str
The operation to perform
client_id : int, optional
Client ID (required for delete, archive, get_campaigns, get_contacts,
assign_user, remove_user, set_logo_from_url)
user_id : int, optional
User ID to assign or remove (assign_user, remove_user)
logo_url : str, optional
Public HTTPS URL of a logo image (set_logo_from_url only)
include_inactive : bool, optional
For get_my_workspaces: include inactive workspaces (default False)
page_index : int, default=1
Page number for get_contacts (1-based)
page_size : int, default=20
Items per page for get_contacts (max 100)
Returns:
--------
dict
API response with structure:
{
"success": bool,
"message": str,
"data": {
"id": int,
"name": str,
"email": str,
"clientServerFilepath": str,
"userId": int,
"active": bool,
"contactName": str,
"monthlyTargetContactVolume": int,
"duplicateTreatment": int, # 0-5
"website": str,
"createdDatetime": str,
"isDeleted": bool,
"campaignCount": int, # Number of campaigns
"contactCount": int # Total contacts across campaigns
}
}
Examples:
---------
Get client campaigns:
>>> await client_manage(operation="get_campaigns", client_id=42)
Get client contacts:
>>> await client_manage(
... operation="get_contacts",
... client_id=42,
... page_index=1,
... page_size=50
... )
Archive (cancel) a client:
>>> await client_manage(operation="archive", client_id=42)
Set logo from URL:
>>> await client_manage(
... operation="set_logo_from_url",
... client_id=42,
... logo_url="https://cdn.example.com/logo.png",
... )
set_logo_from_url
Write.
Manage Kenso clients/tenants (workspaces): delete, archive, campaigns, contacts, users, logo. Client-facing: get_my_workspaces, set_logo_from_url.
Manage clients (tenants) in Kenso platform.
Clients are the top-level organizational units representing companies or customers
using the Kenso platform. Each client can have multiple campaigns, and contacts
are deduplicated based on the client's duplicate treatment settings.
Client-facing sub-surface (task 15 / D6):
----------------------------------------
On the client-facing host, non-staff principals may only use:
get_my_workspaces, set_logo_from_url.
- set_logo_from_url POSTs a public image URL; the backend fetches it server-side
behind its SSRF guard (the agent never uploads bytes).
set_logo_from_url needs the workspace_settings permission in the pinned workspace.
Staff / internal host keep the full SuperAdmin ClientController surface.
Operations:
-----------
delete:
Delete a client (soft delete).
Example: operation="delete", client_id=42
archive:
Archive (deactivate) a client by setting active=false. Use when cancelling a client.
The client data is preserved but the client is marked as inactive.
Example: operation="archive", client_id=42
get_campaigns:
Get all campaigns for a client.
Example: operation="get_campaigns", client_id=42
get_contacts:
Get contacts for a client with pagination.
Example: operation="get_contacts", client_id=42, page_index=1
get_my_workspaces:
Get all workspaces (clients) the current user has access to.
Optionally include inactive workspaces. No client_id required.
Example: operation="get_my_workspaces", include_inactive=True
assign_user:
Assign a user to a client. Admin-only. Requires client_id and user_id.
Outside Kenso's own workspaces a Kenso staff account is not found,
whoever the caller is.
Example: operation="assign_user", client_id=42, user_id=123
Canonical replacement: workspace(operation="members-create") (POST /v1/members, Ken-Version 1.1).
remove_user:
Remove a user from a client. Admin-only. Requires client_id and user_id.
Example: operation="remove_user", client_id=42, user_id=123
set_logo_from_url:
Set the workspace company logo from a public HTTPS image URL.
Backend fetches the URL behind its SSRF guard and stores the image.
Requires client_id and logo_url, and the workspace_settings permission.
Example: operation="set_logo_from_url", client_id=42,
logo_url="https://cdn.example.com/logo.png"
Parameters:
-----------
client : KenAPIClient
API client instance
operation : str
The operation to perform
client_id : int, optional
Client ID (required for delete, archive, get_campaigns, get_contacts,
assign_user, remove_user, set_logo_from_url)
user_id : int, optional
User ID to assign or remove (assign_user, remove_user)
logo_url : str, optional
Public HTTPS URL of a logo image (set_logo_from_url only)
include_inactive : bool, optional
For get_my_workspaces: include inactive workspaces (default False)
page_index : int, default=1
Page number for get_contacts (1-based)
page_size : int, default=20
Items per page for get_contacts (max 100)
Returns:
--------
dict
API response with structure:
{
"success": bool,
"message": str,
"data": {
"id": int,
"name": str,
"email": str,
"clientServerFilepath": str,
"userId": int,
"active": bool,
"contactName": str,
"monthlyTargetContactVolume": int,
"duplicateTreatment": int, # 0-5
"website": str,
"createdDatetime": str,
"isDeleted": bool,
"campaignCount": int, # Number of campaigns
"contactCount": int # Total contacts across campaigns
}
}
Examples:
---------
Get client campaigns:
>>> await client_manage(operation="get_campaigns", client_id=42)
Get client contacts:
>>> await client_manage(
... operation="get_contacts",
... client_id=42,
... page_index=1,
... page_size=50
... )
Archive (cancel) a client:
>>> await client_manage(operation="archive", client_id=42)
Set logo from URL:
>>> await client_manage(
... operation="set_logo_from_url",
... client_id=42,
... logo_url="https://cdn.example.com/logo.png",
... )
test_delivery
Write.
Test server-side GA4/Meta click delivery and read its delivery health. Ops: test_delivery, delivery_health.
Workspace-level server-side ad-network click delivery (GA4 Measurement
Protocol + Meta Conversions API).
Routes (workspace id = client_id):
- POST /v1/workspaces/{id}/tracking/test
- GET /v1/workspaces/{id}/tracking/delivery-health
Authorization: client admin of the workspace (or SuperAdmin). Path client_id is
the workspace id. Both operations require client-admin (backend
TenantAccessGuard.HasClientAdminAccessAsync); the MCP policy layer surfaces
a clean validation error for members rather than a raw backend 403.
Operations:
-----------
test_delivery:
POST a synthetic click through the real provider clients so operators can
verify credentials BEFORE enabling production delivery. Delivery enable
flags are ignored - only account id + stored secret are required.
provider: "ga4" | "meta" (required).
- ga4: posts to GA4 Measurement Protocol /debug/mp/collect (validation mode;
nothing lands in production GA4). No test_event_code.
- meta: posts to Meta Conversions API. test_event_code is REQUIRED so the
event routes to Meta Events Manager > Test events and never lands as a
live conversion. Get a code from Meta Events Manager > Test events.
Envelope semantics: top-level success=true means "the test ran". Inspect
data.delivered for provider acceptance. A provider rejection returns
delivered=false with success=true - surface as information, not an error.
data shape:
{ provider, delivered, statusCode, providerResponse, testEventId, sentAtUtc }
Example GA4: operation="test_delivery", client_id=42, provider="ga4"
Example Meta: operation="test_delivery", client_id=42, provider="meta",
test_event_code="TEST12345"
delivery_health:
GET per-provider delivery health over a trailing window (default 7 days,
clamp 1..30 via window_days). Always returns both ga4 and meta cards.
Envelope data shape (array of two provider cards, NOT an object keyed by
provider name):
{
"providers": [
{"provider": "ga4", "configured": bool, "deliveryEnabled": bool,
"lastSuccessfulTestAt": str|null, "pending": n, "delivered": n,
"failed": n, "deadLettered": n, "suppressed": n,
"lastDeliveredAt": str|null, "missingBrowserIdentifiers": n,
"recentFailures": [...]},
{"provider": "meta", ...}
],
"windowDays": n
}
Each provider card includes: configured, deliveryEnabled, lastSuccessfulTestAt,
status bucket counts (pending/delivered/failed/deadLettered/suppressed),
lastDeliveredAt, missingBrowserIdentifiers (Meta _fbp/_fbc gaps in the
window; 0 for GA4; not a delivery gate), and recentFailures (max 10;
error strings pre-scrubbed; optional matchQualityNotes).
Example: operation="delivery_health", client_id=42, window_days=14
Parameters:
-----------
client : KenAPIClient
Injected automatically - do not pass.
operation : str
test_delivery | delivery_health
client_id : int
Workspace (client) id - required for all operations.
provider : "ga4" | "meta", optional
Required for test_delivery.
test_event_code : str, optional
Required when provider="meta" on test_delivery. Ignored for ga4.
window_days : int, optional
Trailing window for delivery_health (default 7, clamped 1..30 by backend).
Returns:
--------
Kenso response envelope: {"success": bool, "message": str, "data": ...}