Agent Team agent_team
Run Kenso's agent templates from your own AI tool: read each live campaign's lead runway and inbox health. Change campaigns only through these operations, and leave everything else as proposals for a person to approve in Kenso.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through agent_team_read and changes through agent_team_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: create-action, create-proposal, get-autopilot, get-runway, list-changes, list-proposals, replace-autopilot, undo-action
create-action
Write. Early access: needs agent_templates on for the workspace. POST https://api.ken.so/v1/agent-team/actions
Body (json): args object, campaignId integer, idempotencyKey string, kind string, reason string
Ask for one bounded change to a campaign: applied inside Autopilot and the bounds, else proposed. Kinds: cap_move, inbox_drop, inbox_restore, top_up, placement_test, make_default. The answer is applied (with an undo deadline), proposed (a person decides in Approvals) or refused.
POST /api/v1/agent-team/actions. Sends Ken-Version 1.1 and X-Ken-Actor agent. client_id is sent
as X-Ken-Workspace-Id. Needs Campaigns edit. 404 while the agent_templates flag is off for the
workspace.
kind and args:
- cap_move {newCap}: the campaign's daily cap.
- inbox_drop {inboxId, scope}: take a sick inbox off this campaign (scope "campaign", the
default when scope is left out) or off every campaign it sends on (scope "inbox"). Urgent
when it is proposed.
- inbox_restore {inboxId}: put back an inbox a team drop took off this campaign.
- top_up {count}: import count leads from the campaign's approved audience. Runs as a person, so
a Kenso API key with no user is refused needs_a_user, and the caller also needs Search view and
the Import permission (else 403 permission_denied).
- placement_test {} or {inboxId} or {domainId}: run a placement test of the campaign's copy.
{} tests from the campaign's busiest healthy inbox; inboxId must be an inbox the campaign
sends from and domainId the domain of one, at most one of the two. Cannot be undone.
- make_default {experimentId}: make the experiment's proven winner the default.
reason: why, in one or two sentences a person reads (up to 500 characters). idempotency_key: up
to 120 characters; a retry with the same key runs once. Without one, the same kind, campaign and
args run once per UTC day, and a try that failed runs again.
Returns data {status, actionId, undoUntil, summary, approvalId, why, code, message}. Every outcome
is 200: status applied (actionId, undoUntil when the kind has an undo, summary), proposed
(approvalId request_<id>, why: Autopilot is off, a standing rule holds the campaign, or the
change is outside the bounds; a person decides it in Approvals), or refused (code
unknown_kind, kind_not_allowed, invalid_args, campaign_not_found, campaign_paused,
workspace_suspended, apply_failed, needs_a_user, already_undone (this key's action was undone:
send a new key) or busy (another change to the campaign is being checked: retry), and message;
nothing changed). Undo an applied action with agent_team(operation="undo-action", action_id=...).
create-proposal
Write. Early access: needs agent_templates on for the workspace. POST https://api.ken.so/v1/agent-team/proposals
Body (json): args object, campaignId integer, clientYes string, kind string, reason string, title string, urgent boolean
Propose a change for a person to approve in Kenso: copy, an angle, a schedule, a pause, a client update and more. The proposal lands in Today and Approvals; nothing changes until a person approves it there.
POST /api/v1/agent-team/proposals. Sends Ken-Version 1.1 and X-Ken-Actor agent. client_id is
sent as X-Ken-Workspace-Id. Needs Campaigns edit. 404 while the agent_templates flag is off for
the workspace. Returns 201 with the proposal, as agent_team(operation="list-proposals") lists
it: {id request_<id>, kind, status, campaignId, title, reason, args, urgent, requiresClientYes,
requestedBy {kind, label}, createdAt, expiresAt, decidedAt, decidedBy, error}.
kind and args (the same args as create-action for the bounded kinds):
- cap_move {newCap}; top_up {count}; inbox_drop {inboxId, scope}; inbox_restore {inboxId};
placement_test {} or {inboxId} or {domainId}; make_default {experimentId}. A bounded
kind's args are checked against the campaign when it is proposed (an inbox it does not send
from is refused invalid_args).
- schedule {sendingDays?, startTime? "HH:mm", endTime? "HH:mm", timezone?, confirmWeekend?}:
adding Saturday or Sunday needs confirmWeekend true. pause {}; resume {}.
- audience {filters, summary}: the Kenso Search people filters lead top-ups come from.
- copy {segmentId, name, steps, sourceVersionId?}: a new email sequence version, steps as the
sequence versions route takes them. angle {summary, detail}.
- client_update {text}: an update for the client. Set campaign_id to the campaign the update is
about: only an update that names a campaign rides on that campaign's weekly share email.
- standing_rule {text, days 1..90, campaignId?}.
campaign_id: required except for standing_rule, client_update and angle. title: 1-120
characters. reason: why, 1-1000 characters. urgent: the card sorts first.
client_yes (up to 300 characters): on a client workspace a schedule or volume change
(cap_move, schedule, pause, resume) needs the client's yes. Quote who said it, where and when
("Dana on the Oct 19 call") only when a person gave you that source; never invent one. The
approver still confirms it on the card. Left out when not given.
400 with error code unknown_kind, kind_not_allowed or invalid_args and the reason (400
validation_failed when a field is missing or too long); 404 campaign_not_found when the campaign
is not in the workspace, deleted or archived. A new pending cap_move,
schedule, pause, resume, top_up, audience, placement_test or client_update replaces the older
pending one of the same kind on the campaign.
get-autopilot
Read. Early access: needs agent_templates on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/autopilot
Path: campaignId
Read a campaign's Autopilot: on or off, who turned it on, the client's yes, the audience and the top-up limit.
GET /api/v1/campaigns/{campaignId}/autopilot. Sends Ken-Version 1.1 and X-Ken-Actor agent.
client_id is sent as X-Ken-Workspace-Id. Needs Campaigns view. 404 while the agent_templates
flag is off for the workspace, or when the campaign is not in the workspace or deleted.
Returns data {campaignId, enabled, enabledBy {userId, name}, enabledAt, clientYes, audience
{filters, summary, approvedBy {userId, name}, approvedAt}, weeklyTopUpLimit}. A campaign that
never had Autopilot reads as off, with no audience and weeklyTopUpLimit 500. enabledBy,
enabledAt and clientYes are left out while it is off; enabledBy and approvedBy are also left
out when an API key with no user made the change. audience is left out when there is none.
get-runway
Read. Early access: needs agent_templates on for the workspace. GET https://api.ken.so/v1/agent-team/runway
Query: campaignId integer
Read how many days of leads each live campaign has left, and whether its inboxes can carry the send. Per campaign: Autopilot, leads waiting for their first email, the runway in days, the daily cap against the healthy inboxes, each inbox's health, the latest placement test and interested replies.
GET /api/v1/agent-team/runway. Sends Ken-Version 1.1 and X-Ken-Actor agent. client_id is sent
as X-Ken-Workspace-Id. Needs Campaigns view. 404 while the agent_templates flag is off for the
workspace.
Without campaign_id: the workspace's live campaigns (scheduled, sending, launching), newest
first, at most 50. With campaign_id: that campaign in any status (404 when it is not in the
workspace).
Returns data {workspace {targetInterestedPerWeek, runwayDays, clientWorkspace}, campaigns
[{campaignId, name, sendingStatus, autopilot {on, audienceApproved, weeklyTopUpLimit,
toppedUpLast7Days}, leads {notStarted, firstTouchesPerDay, runwayDays}, capacity {dailyCap,
rampFloor, inboxCapacity, healthyInboxCapacity, short}, inboxes [{inboxId, email, dailyLimit,
sends7d, bounceRate7d, sick, sickReason}], placement {completedAt, inboxRate, spamRate},
replies {interested7d, unansweredInterested}}]}.
workspace.runwayDays is how many days of leads the workspace wants ready on each campaign;
leads.runwayDays is how many it has: notStarted (ready leads still waiting for email 1) over
the first emails a day of the last 7 days, rounded down, and omitted when no first email went
out. firstTouchesPerDay is that rate to one decimal; runwayDays uses the exact rate. capacity.short is true when the healthy inboxes' daily limits add up
to less than dailyCap (the campaign's cap, else the inbox capacity); rampFloor is the ramped
cap while the campaign's ramp runs. An inbox is sick (sickReason, the first that holds) when
its status is not active (not_active), a member paused it (paused), a Kenso send block holds it
(auto_paused), at 5% bounces or more over at least 30 sends in 7 days (bounces), or when its
domain's latest health check is blocklisted or failed SPF, DKIM or MX (domain_health). Rates
are fractions 0-1. placement is omitted when the campaign has no completed test.
replies count email only: interested7d is distinct leads who replied Interested over the
last 7 days, unansweredInterested the Interested threads not archived and not answered since
the lead last wrote (a due reminder does not count one, unlike the To Reply tab). clientWorkspace is
omitted while staff have not decided; in a client workspace a schedule or volume change
needs the client's yes.
list-changes
Read. Early access: needs agent_templates on for the workspace. GET https://api.ken.so/v1/agent-team/changes
Query: campaignId integer, since date-time
Read what changed on the workspace's campaigns since this tool's last run: changes, actions, proposals, rules. Call it first on every run, so no state has to live in the agent.
GET /api/v1/agent-team/changes. Sends Ken-Version 1.1 and X-Ken-Actor agent. client_id is sent
as X-Ken-Workspace-Id. Needs Campaigns view. 404 while the agent_templates flag is off for the
workspace.
since: an ISO-8601 instant. Without it the read starts at this person's previous successful
list-changes call from the same AI tool (the MCP call log), else 7 days ago; it never reaches
back more than 30 days. So read once per run without since, and pass since for any fixed
window (the last 7 days): a second call without it sees only the seconds since the first. campaign_id narrows the changes, actions and proposals to that campaign
(and the rules to its own and the workspace-wide ones; a campaign of another workspace lists
nothing); without it changes cover the live campaigns (scheduled, sending, launching).
Returns data {since, until, truncated, changes [{campaignId, occurredAt, kind, actor {kind,
label}, requestId, diff}], actions [{actionId, kind, campaignId, status, appliedAt, undoUntil,
actorLabel, authority, keptLeads}], proposals {open [...], decided [...]}, standingRules
[{ruleId, campaignId, text, expiresAt, author}]}. changes is the campaign change log, newest
first, at most 200 (truncated is true when there were more); kind is what changed
(version_added, copy_edited, schedule_changed, volume_changed, inbox_added, inbox_removed,
list_imported, contacts_removed, status_changed, default_made, ...); actor.kind is user,
agent, workflow or system; requestId aact_<id> is an agent action and request_<id> an
applied proposal. The contacts_removed rows of one request on a campaign come back as one
entry: diff.count is the contacts removed, occurredAt the last removal. actions are the agent actions applied since then (status applied, undone,
undo_failed or failed); keptLeads is set on an undone top_up: the leads it added that stayed
because they had already started. proposals.open are every proposal still waiting (pending or
awaiting_client), proposals.decided those decided since then, each as
agent_team(operation="list-proposals") returns it; proposals is null unless the caller also
has Campaigns edit and the Approve permission, as Approvals. standingRules are the rules people gave the
team that still hold: respect them. Reads only.
list-proposals
Read. Early access: needs agent_templates on for the workspace. GET https://api.ken.so/v1/agent-team/proposals
Query: campaignId integer, cursor string, limit integer, status string
List the workspace's agent proposals, newest first: what waits for a person and what was decided. Read the open ones before proposing, and never propose again what is still open.
GET /api/v1/agent-team/proposals. Sends Ken-Version 1.1 and X-Ken-Actor agent. client_id is sent
as X-Ken-Workspace-Id. Needs Campaigns edit and the Approve permission (403 permission_denied
otherwise). 404 while the agent_templates flag is off for the workspace.
status: open (pending or awaiting_client), pending, awaiting_client (a client approval link
holds it), applied, rejected, expired, superseded or failed; every status when left out.
campaign_id narrows to one campaign. limit 1..100 (default 25); pass pagination.nextCursor
back unchanged as cursor while pagination.hasMore is true. A page can hold fewer items than
limit when status filters it; keep paging while hasMore is true.
Each proposal: {id request_<id>, kind, status, campaignId, title, reason, args, urgent,
requiresClientYes, requestedBy {kind, label}, createdAt, expiresAt, decidedAt, decidedBy
{userId, name}, error}. requestedBy.kind is agent (a Ken team specialist or an outside agent),
user or api_key. error says why an approved proposal failed to apply. Approving and skipping
happen in Kenso (Today or Approvals), never here.
replace-autopilot
Write. Early access: needs agent_templates on for the workspace. PUT https://api.ken.so/v1/campaigns/{campaignId}/autopilot
Path: campaignId
Body (json): audience object, clearAudience boolean, clientYes string, enabled boolean, weeklyTopUpLimit integer
Turn a campaign's Autopilot on or off, and set its audience and weekly lead top-up limit. On, Ken's team and the workspace's agents apply bounded changes to it without a person's approval. Only when a person asks, never to make your own proposal apply. In a client workspace client_yes says who gave the client's yes, where and when; never invent one.
PUT /api/v1/campaigns/{campaignId}/autopilot. Sends Ken-Version 1.1 and X-Ken-Actor agent.
client_id is sent as X-Ken-Workspace-Id. Needs Campaigns edit. 404 while the agent_templates
flag is off for the workspace, or when the campaign is not in the workspace or deleted.
enabled (required): true turns Autopilot on. While it is on, Ken's team and the workspace's
agents apply bounded changes to the campaign (agent_team(operation="create-action"): the daily
cap, a sick inbox, lead top-ups from the approved audience, placement tests, a proven winner)
inside the bounds, without a person's approval. false turns it off: every such change comes
back proposed for a person to decide in Approvals. Turning it on records who and when (the
caller's user; no one for an API key with no user); turning it off clears that and the
client's yes.
Turn it on, set an audience or raise weekly_top_up_limit only when a person asks you to. Never
do it so that one of your own create-action calls applies instead of being proposed, and never
in place of agent_team(operation="create-proposal") with kind audience, which a person approves.
client_yes (up to 300 characters): in a client workspace, turning Autopilot on needs the
client's yes, else 400. Say who gave it, where and when ("Dana on the Oct 19 call"). Pass it
only when a person gave you that source, and never invent one.
audience_filters and audience_summary, together: the Kenso Search people filters lead top-ups
come from (at least one filter) and a one-line summary a person reads (up to 300 characters).
An audience set here is approved by the caller. clear_audience true removes the audience
(not together with audience_filters). weekly_top_up_limit 0..20000: the leads the team may add
per rolling 7 days (500 until set).
Fields left out, other than enabled, stay as they are. Changes no campaign field and nothing
that sends. Returns data as agent_team(operation="get-autopilot") does. 400 validation_failed
when a value is out of range, client_yes is missing in a client workspace, or the audience is
incomplete.
undo-action
Write. Early access: needs agent_templates on for the workspace. POST https://api.ken.so/v1/agent-team/actions/{actionId}/undo
Path: actionId
Undo an applied agent action inside its undo window. Puts back what the action changed: the previous cap, the dropped inbox, the default before; a lead top-up removes only the leads that have not started.
POST /api/v1/agent-team/actions/{actionId}/undo. Sends Ken-Version 1.1 and X-Ken-Actor agent.
client_id is sent as X-Ken-Workspace-Id. Needs Campaigns edit. 404 while the agent_templates
flag is off for the workspace, or when the action is not in the workspace. 400 when it is
already undone or failed, its undo window has closed, or the undo would overwrite a newer change
(the action stays in effect with the reason). action_id is the actionId create-action returned.
Returns data {actionId, status, undoneAt}; status is undone.