Kenso MCP tools

Workflows workflows

Not on this tool: a workflow's audit log (edits, publishes, restores, runs) is workflow_runs(operation="activity", workflow_id=...); call only that, no get or versions-list before or beside it. Workflows: one trigger plus steps (find, enrich, qualify with AI, tag, notify) saved as a kenWorkflow definition with versions. Create a draft, validate it until valid is true (to check a saved workflow for problems, call validate with its workflow_id directly), then publish; update with draftVersion as base_version. unpublish turns a live workflow off. To build one from a plain-words request, call workflow_builder build with the request as the goal, ids included, before anything else. Compiling a condition and test runs are on workflow_builder; runs, their recovery and run-on-records are on workflow_runs.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through workflows_read and changes through workflows_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: brief, estimate-create, create, delete, versions-diff, workflow-slack-connection-get, step-types-get, templates-get, versions-get, get, workflow-secrets-list, step-types-list, templates-list, versions-list, list, publish, versions-restore, unpublish, update, validate

brief

Read. Early access: needs workflows, workflows_plain on for the workspace. GET https://api.ken.so/v1/workflows/brief

Query: campaignId integer, include string, kind string, types string, workflowId integer

Everything your own model needs to write a workflow in plain steps; no Kenso AI cost. Start here, write the definition yourself, then create or update, validate, test and publish.

GET /api/v1/workflows/brief. Sends Ken-Version 1.1. Requires workflows
view, and the workspace's workflows and workflows_plain features (404
otherwise). Reads only: no model call, nothing charged, nothing saved.
The caller's own model (Claude Code, Claude Desktop, Codex, Cursor) does
the writing; Kenso runs the workflow.

kind: general or campaign, the workflow you will write (campaign when
you send campaign_id, else general). campaign_id: the campaign a campaign
workflow is for, listed first under workspace; a campaign brief needs it
(400), and 404 when it is not a campaign of the workspace. workflow_id: an existing
workflow to change; current is then its draft definition (else its
published version) and currentDraftVersion the base_version for
workflows update (0 when it has no draft). With workflow_id, kind and
campaign_id come from the workflow (400 when you send different ones).

include: the sections to return. Default: every section but format,
which is the skill reference
load_skill(name="workflows", reference="references/definition-format.md");
add "format" to get it here (about 12k tokens). types: up to 20 step or
trigger types (key@version, or a bare key for the latest) to return in
full under stepTypeDetails, with inputSchema, outputSchema, example,
exampleOutput and cost: ask for the types you will use. 400 when one is
not available to this workspace.

Returns {data: {kind, campaignId?, workflowId?, format?, authoring?,
stepTypes?, triggers?, stepTypeDetails?, plainSchema?, examples?,
workspace?, current?, currentDraftVersion?}}:
- authoring: markdown, how to turn plain steps into engine steps, the
  canonical rule shapes (fit filter, segment branch, adding a person to
  a campaign), when to pin a step, when to run one with judgment, and
  the secrets rule. Follow it.
- stepTypes and triggers: what this workspace can use (its features
  decide), one compact item each: {type, kind, title, summary, example,
  cost, requires, test, sideEffects, recordType?, workflowType?}.
  example is a working "with". requires lists app:slack, app:crm and
  flag:x needs.
- plainSchema: JSON Schema of the definition's plain block.
- examples: worked pairs {key, title, kind, plain, definition}: plain is
  what a person wrote, definition the workflow it became, plain block
  included. Each validates.
- workspace: {slackConnected, campaigns: [{id, name, sendingStatus,
  segments: [{id, name, isDefault}]}] (the newest 50 not archived, the
  asked campaign first), hasMoreCampaigns, secrets: [names only],
  recordTypes}.

Next: write {..., "plain": {"when": ..., "steps": [...]}} into a
definition, then workflows create (or update with base_version),
workflows validate, workflow_builder test on one record, workflows
publish. Secrets: reference {{secrets.NAME}}; the user sets the value in
the app (Settings > Integrations > Secrets), never in this chat.

estimate-create

Read. Early access: needs workflows on for the workspace. POST https://api.ken.so/v1/workflow-estimates

Body (json): definition object, records integer, workflowId integer

Estimate the credits for running records through a workflow. Charges and saves nothing.

POST /api/v1/workflow-estimates. Staff. Sends Ken-Version 1.1. Requires
workflows view. Send exactly one of workflow_id (its draft, else its
published version) and definition. records: 1 to 100000.

Returns {data: {records, expectedCredits, maxCredits,
expectedMillicredits, maxMillicredits, workflowType?, bulkExpectedCredits?,
bulkMaxCredits?, bulkExpectedMillicredits?, bulkMaxMillicredits?,
bulkPriceApplies?, steps: [{nodeId, stepType, action, maxMillicreditsPerRecord, hitRate,
reachRate, expectedMillicreditsPerRecord, chargedBy, variable, bulkAction?,
bulkMaxMillicreditsPerRecord?, bulkExpectedMillicreditsPerRecord?, estimated}]}}.
maxCredits assumes every record reaches and pays at every step. hitRate is
the share of calls that charge (paid lookups charge only on a result) and
reachRate the share of records that get to the step. 1 credit = 1000
millicredits.

Bulk import price (DEV-5814): workflowType is "signal" or "bulk_import"
(the definition's type, else its trigger's), absent when the trigger has
neither. The plain totals and step prices are always the real-time price.
On a bulk_import workflow the bulk* fields are the same totals and step
prices at the Bulk import price: a balanced or smart ai.prompt@1 costs half
(WorkflowAiPromptBalancedBulk 0.25 credits instead of 0.5,
WorkflowAiPromptSmartBulk 1 instead of 2); the cheap tier and every other
step cost the same. A live run pays the bulk price only while the workspace
has workflow_sources on; test runs pay real time. bulkPriceApplies says
whether this workspace's runs pay the bulk totals now. When it is true,
show the bulk total with the real-time total next to it, for example
"about 300 credits for 1,000 leads, 550 in real time". When it is false,
quote only the real-time total: that is what a run costs today. Signals
and untyped workflows have no bulk fields.

chargedBy is "workflow" (charged on the run's credits) or "campaign": a
campaign.sequence@1 step's copy is charged by the campaign as AI
personalization per lead written, at the campaign's price, so it is in the
totals but shows in the campaign's usage, not the run's credits. variable
is true when that price depends on a campaign the estimate does not know:
estimating a bare definition has no campaign, so the line keeps its per-lead
price and stays out of the totals. Estimate a campaign workflow by
workflow_id to count it. A "studio" line is a studio.page@1 step: Studio
charges the page fill and its first link (1 credit) itself, priced from the
template's latest published version; variable when the template cannot be
priced.

estimated is true on a step metered on its own path (account.research@1,
account.map_committee@1, person.research@1, account.plan@1,
data.find_phone@1): its expected figure is a typical charge and its max a
ceiling, not a rate card price, so call those figures estimates. A server
that predates the field leaves it out.

create

Write. Early access: needs workflows on for the workspace. POST https://api.ken.so/v1/workflows

Body (json): campaignId integer, definition object, kind string, note string, templateKey string

Create a workflow as a draft, from a kenWorkflow definition or a template. Nothing runs until a version is published. Validate before publishing.

POST /api/v1/workflows. Staff. Sends Ken-Version 1.1. Requires workflows
edit. Returns 201 with the workflow (as workflows get) and its draftVersion.

Send exactly one of definition (a kenWorkflow "1" object: name, trigger,
steps) and template_key (from workflow templates list), else 400 on
definition. kind: general (default, or the template's kind) or campaign.
system is Kenso's own (one per Knowledge skill) and is refused. A campaign
workflow needs campaign_id (a campaign in the workspace, else 404); any
other kind refuses campaign_id. A campaign workflow whose definition has a
campaign.enroll@1 step with no targetCampaignId sends the campaign's own
sequence. On a campaign with no such workflow yet it becomes the
campaign's own workflow (isCampaignOwn true). When the campaign's own
workflow is still the draft Kenso wrote and nobody changed, the create
replaces that draft's definition and returns that workflow's id instead
of adding a second one. When the campaign already has a workflow that
sends its sequence, or a person changed or published the own workflow, a
second workflow is created beside it with isCampaignOwn false. Read
isCampaignOwn on the response. note (500 characters) is shown in the
version history. A definition is at most 256 KB, 200 steps, 1,000 next
links and 50 branch arms (400 too_large); the request body at most 512 KB.

A definition that does not parse (bad JSON shape, unknown step type, missing
id) answers 400 invalid_definition with error.details [{field: <JSON path>,
code, message}]. The draft may still have warnings and graph problems:
run workflows validate to see them.

Data sources (DEV-4693, dark behind the workspace's workflow_sources flag):
trigger is the first source, and optional additionalTriggers lists more,
each {id, type, with, schedule} like trigger plus an id (step id rules,
unique among sources and steps; the first source's id is "trigger" unless
it names one). Optional root type is signal (always on, each record as it
arrives) or bulk_import (once or on a schedule); left out, it is the first
trigger's workflowType (workflow step-types list). Every source must be of
that one type, or validate reports workflow_type_mismatch. A Bulk import
source that reads on a schedule (trigger.saved_list@1, a saved company
list read as accounts; trigger.ken_search@1, a Kenso Search people search
by filters or savedSearchId, up to limit people a read, skipKnown true by
default so a repeating read runs new people only; trigger.campaign_leads@1,
the leads added to a campaign since its last read; trigger.csv@1, the
people list a CSV was uploaded into, by savedListId;
trigger.event_attendees@1, an outbound event's attendee list by eventId
and optional roles, each person listed run once (one waiting for their
company's account runs once it exists); trigger.apollo@1, an
Apollo contacts list by listId, on the workspace's own Apollo key;
trigger.job_posts@1, the companies with open job posts that match
filters (the jobFilters of POST /v1/job-post-searches/companies), each
an account run with its posts in {{trigger.posts}};
trigger.linkedin_connections@1, a LinkedIn seat's imported connections
by linkedInAccountId, each a person run with level and stage on it)
needs a schedule
{every: once, hour, day or week, at "HH:mm", weekday, timezone}, as
trigger.schedule@1 reads them: it reads when published, then on its
cadence, one run per record. trigger.campaign_leads@1 only repeats
(hour, day or week): its read at publish only marks where to start.
trigger.csv@1 only reads once, after the upload is processed, and runs
each person once per workflow, a republish included.
trigger.event_attendees@1 reads once, day or week, never hour.
trigger.apollo@1 reads once, daily or weekly (not hourly) and runs each
person once per workflow, so a repeating read runs the list's new
contacts; workflow_builder(operation="apollo-lists-list") lists its
lists.
trigger.job_posts@1 reads once, daily or weekly (not hourly) and runs
each company (by its Kenso Search company id) once per workflow, unless
rerunAfterDays is set; backfillDays (0 to 30, 0 by default) is how far
back its first read goes (a once schedule needs 1 to 30, or its one
read finds nothing), and limit (100 by default) caps the companies
a check starts. POST /v1/job-post-searches/companies with the same
filters counts the companies they match (hiringSet.total) before
publish. includeUnmatched (false by default) also runs the hiring
companies Kenso Search has no company for yet: each becomes an account
named after the company on its best-known domain (one with no known
domain is skipped, since an account needs a domain), its run keyed by
the jobs index company id ({{trigger.jobsCompanyId}},
{{trigger.matchStatus}} "unmatched") and run once per workflow, never
again once Kenso Search matches it. The companies call with
includeUnmatched true counts them (hiringSet.unmatched).
A schedule on any other source is
invalid_schedule (it keeps its own cadence). A
Bulk import campaign workflow always holds trigger.campaign_leads@1 for its
own campaign (Kenso adds it, hourly, when it builds one). Publish registers
each source, and every run says which source started it (sourceId on
workflow_runs).
With the flag off, type, additionalTriggers and a trigger id or schedule
are feature_disabled.

Plain steps (DEV-7291): optional root plain {when?, steps[]} is the
workflow in words, each item {id, text, compiledTo?, summary?, pinned?,
mode?}. compiledTo lists the engine ids the step became ("trigger" or an
additionalTriggers id, else step ids); pinned true marks config written by
hand; mode is compiled (default) or judgment. Words only: the engine never
runs them and the definition hash leaves them out. Validate reports
plain_duplicate_id, plain_empty_text, plain_unknown_ref,
plain_duplicate_owner and plain_invalid_mode, and warns plain_uncovered_step
for an engine step no plain step owns. The workflows skill's
definition-format reference has the rules.

Example: definition={"kenWorkflow": "1", "name": "Qualify new signups",
"trigger": {"type": "trigger.manual@1"}, "steps": [{"id": "qualify",
"type": "ai.qualify@1", "with": {"criteria": "B2B SaaS, 50+ people"}}]}

delete

Write. Early access: needs workflows on for the workspace. DELETE https://api.ken.so/v1/workflows/{workflowId}

Path: workflowId

Delete a workflow. Its triggers stop at once; past runs stay readable. Empty success means it was deleted.

DELETE /api/v1/workflows/{workflowId}. Staff. Sends Ken-Version 1.1.
Requires workflows edit. The backend returns 204, or 404 not_found for a
workflow outside the workspace or already deleted. Webhook, schedule and
event registrations are retired with it. There is no undelete.

versions-diff

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflows/{workflowId}/versions/{number}/diff

Path: workflowId, number

Query: against integer

Compare a workflow version with another (default the one before it). Lists steps added, removed and changed by id.

GET /api/v1/workflows/{workflowId}/versions/{number}/diff. Staff. Sends
Ken-Version 1.1. Requires workflows view. against: the version to compare
with, default number - 1. 404 not_found when either version does not exist
(version 1 has nothing before it).

Returns {data: {from, to, nameChanged, triggerChanged, limitsChanged,
stepsAdded, stepsRemoved, stepsChanged}}. The step lists hold step ids.
triggerChanged covers every data source and the workflow type.

workflow-slack-connection-get

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflow-slack-connection

Read whether the workspace's Slack is connected for workflow slack.message steps. Never returns the bot token.

GET /api/v1/workflow-slack-connection. Staff. Sends Ken-Version 1.1.
Requires workflows view. Returns 404 not_found unless the workspace has the
workflows feature on.

Returns {data: {available, connected, teamName, botUserId, scopes, installedAt}}.
available is false until Kenso's Slack app is set up; then nobody can
connect yet. connected means the workspace has one install of the Kenso Slack
app with a bot token, so slack.message steps can post. teamName, botUserId,
scopes (comma-separated bot scopes) and installedAt describe that install
and are null when there is none. Connecting and disconnecting happen in the
Kenso app's Slack integration (a browser flow).

step-types-get

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflow-step-types/{type}

Path: type

Read one step or trigger type: what it takes, returns and costs.

GET /api/v1/workflow-step-types/{type}. Staff. Sends Ken-Version 1.1.
Requires workflows view. type: key@version (ai.qualify@1), or a bare key
for its latest version. 404 not_found for an unregistered type. Returns
{data: <one item of workflow step types list>}.

templates-get

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflow-templates/{templateKey}

Path: templateKey

Read one workflow template with its kenWorkflow definition.

GET /api/v1/workflow-templates/{templateKey}. Staff. Sends Ken-Version 1.1.
Requires workflows view. 404 not_found for an unknown key. Returns {data:
{key, name, description, kind, stepTypes, requires, defaultWorkflowKey,
preview, definition}}.

versions-get

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflows/{workflowId}/versions/{number}

Path: workflowId, number

Read one version of a workflow with its definition and layout.

GET /api/v1/workflows/{workflowId}/versions/{number}. Staff. Sends
Ken-Version 1.1. Requires workflows view. 404 not_found for an unknown
number or a workflow outside the workspace.

Returns {data: {number, status, revision, definitionHash, note, definition,
layout, author, createdAt, publishedAt}}. author is {kind, userId,
clientName}.

get

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflows/{workflowId}

Path: workflowId

Read one workflow with its current definition, draftVersion and node layout. Send draftVersion back as base_version on the next update.

GET /api/v1/workflows/{workflowId}. Staff. Sends Ken-Version 1.1. Requires
workflows view. 404 not_found for a workflow outside the workspace, a
deleted one, or when the workflows feature is off.

Returns {data: {id, kind, campaignId, isCampaignOwn, name, description,
defaultKey, status, draft, published, ..., triggerType, workflowType, definition, draftVersion,
layout, webhook}}: the list item's fields (workflows list), plus these. definition is the
draft's kenWorkflow JSON, else the published one. draftVersion is the
draft's revision, its save counter (null when there is no draft); it is not
the version number that versions-list shows. Send it as base_version. layout is
{positions: {trigger: {x, y}, <stepId>: {x, y}}}. webhook is {url, live} for a
workflow with a trigger.webhook@1 source once a publish created its URL, for a
caller with integrations, else absent (DEV-5232): url is where the sender POSTs JSON (give it to the user to
paste into their form tool; anyone holding it can start runs), live is true
while the published webhook trigger is on, false after unpublish (the same URL
works again after the next publish). There is no signing secret.

workflow-secrets-list

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflow-secrets

List the workspace's workflow secrets (names and last 4 characters, never values). Workflow connector steps reference them as {{secrets.NAME}}.

GET /api/v1/workflow-secrets. Staff. Sends Ken-Version 1.1. Requires
workflows view. Returns 404 not_found unless the workspace has the
workflows feature on.

Returns {data: [{id, name, preview, createdAt, rotatedAt, lastUsedAt,
header}], pagination: {hasMore: false}}, ordered by name. preview is the
last 4 characters of a value of 8 or more characters, else null. lastUsedAt
is when a workflow step last resolved the secret. header is {host, name}
for a header-only secret (DEV-4018), absent for a plain one: only a Run code step uses
it, and the sandbox firewall adds it as that request header for that one
host, so the code never sees the value.

Values are write-only: no route returns one, and this tool drops any field
outside that list. Create a secret with
workflow_builder(operation="workflow-secrets-create") and replace its value
with workflow_builder(operation="workflow-secrets-rotate").

step-types-list

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflow-step-types

Query: kind string, workflowType string

List the step and trigger types a workflow can use, with input schemas and costs.

GET /api/v1/workflow-step-types. Staff. Sends Ken-Version 1.1. Requires
workflows view. kind: trigger, source, data, ai, action, logic, human or
code. workflow_type: signal (always on, one record at a time) or
bulk_import (once or on a schedule, the batch together) keeps only the
triggers of that workflow type, the sources a workflow of that type can
start from.

Returns {data: [{type, key, version, kind, title, description,
inputSchema, outputSchema, example, exampleOutput, cost, retry,
rateLimits, batch, fusionGroup, lane, pool, requires, test, sideEffects,
supportsApproval, engineNative, literalFields, secretListField,
systemOnly, agentTeamOnly, workflowType, sourceGroup, recordType}],
pagination: {hasMore: false}}. type is key@version, the value a step's
"type" takes. cost.action is the credit action it charges, cost.free true
when it charges nothing. literalFields lists the with fields passed as
written, never rendered (code.run@1's code: put references elsewhere).
secretListField names the with field that lists workspace secret names
(code.run@1's secrets), or is null. A trigger's workflowType is signal or
bulk_import, its sourceGroup the Data sources picker section (ken_data,
apps, time, inbound, buying_signals, website, linkedin, pipeline,
system) and its recordType what each run is about; other kinds carry
null in all three.

templates-list

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflow-templates

Query: kind string

List Kenso's built-in workflow templates. Start a workflow from one with workflows create.

GET /api/v1/workflow-templates. Staff. Sends Ken-Version 1.1. Requires
workflows view. kind: general, campaign or system.

Returns {data: [{key, name, description, kind, stepTypes, requires,
defaultWorkflowKey, preview}], pagination: {hasMore: false}}, without
definitions. preview is the template's outline read from its definition:
{trigger: {type, with}, steps: [{id, type, title, next, branches: [{label,
next}]}]}, the top-level steps in order (a for-each body left out), with
branches filled only on a logic.branch@1 step. requires lists what the workspace needs before publishing: app:slack,
secret:NAME, flag:x. app:apify means the workspace's own Apify API token,
saved under Settings > Integrations > Apify: the Apify event templates run
actors on it and bill that account, never Kenso's. defaultWorkflowKey is the
defaultKey of the default workflow Kenso installs with this template's
trigger and steps (null when none): a workspace with a workflow of that
defaultKey already runs it.

versions-list

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflows/{workflowId}/versions

Path: workflowId

Query: cursor string, limit integer

List a workflow's versions, oldest first, without definitions.

GET /api/v1/workflows/{workflowId}/versions. Staff. Sends Ken-Version 1.1.
Requires workflows view. limit 1 to 200 (default 50); pass
pagination.nextCursor back as cursor.

Returns {data: [{id, number, status, revision, definitionHash,
publishedAt, createdAt, author, note}], pagination}. status is draft,
published or archived. At most one version is the draft and one is
published. author is {kind, userId, clientName}, who saved the version
last, and note the note on that save.

list

Read. Early access: needs workflows on for the workspace. GET https://api.ken.so/v1/workflows

Query: campaignId integer, cursor string, defaultKey string, kind string, limit integer, q string, status string

List the workspace's workflows, newest first, without their definitions. Filter by kind, status, campaign, a name search or the default workflow key.

GET /api/v1/workflows. Staff. Sends Ken-Version 1.1. Requires workflows
view. Returns 404 not_found unless the workspace has the workflows feature on.

kind: general, campaign or system. status: draft (never published), live
or off. campaign_id: only that campaign's workflows. q: case-insensitive
name match. default_key (sent as defaultKey): only the workflow Kenso
installed as that default workflow, such as champion_moved or
find_relevant_events; at most one, whatever its status, and none when the
workspace never had it or deleted it. limit 1 to 200 (default 50); pass
pagination.nextCursor back as cursor.

Returns {data: [{id, kind, campaignId, isCampaignOwn, name, description,
defaultKey, status, keepSuccessDetails, autoPausedAt, pausedReason, createdBy, createdAt,
modifiedAt, runs7d, lastRunAt, needsAttention,
creditsThisMonthMillicredits, triggerType, workflowType, stepTypes}], pagination:
{nextCursor, hasMore}}. List items carry no draft or published version:
workflows get and versions-list return those summaries, with author and
note. runs7d counts runs created in the last 7 days, lastRunAt is the
newest run's createdAt in the last 90 days (null without one) and
needsAttention the runs in needs_attention created in the last 90 days,
all without test runs. creditsThisMonthMillicredits is what runs created
since the first of this UTC month charged, test runs included.
triggerType is the current version's trigger type and stepTypes its
distinct top-level step types in definition order (key@version).
workflowType is signal (always on, one record at a time) or bulk_import
(once or on a schedule), read from its trigger; null without one. defaultKey
names the default workflow Kenso installed it as (such as find_relevant_events),
null for every other workflow. isCampaignOwn is true on the one workflow
that is its campaign's own: what the campaign does with each new lead,
sequence and send included. A campaign has at most one, and may have none
(Kenso can write it as a draft from the campaign's settings); its other
workflows, such as Keep this campaign full, are false. Use workflows get
for the definition.

publish

Write. Early access: needs workflows on for the workspace. POST https://api.ken.so/v1/workflows/{workflowId}/publish

Path: workflowId

Body (json): note string

Publish the workflow's tested draft: it goes live and its trigger starts. Needs a passing test run on this exact draft first. On an off workflow with no draft it turns the published version back on, with no new test.

POST /api/v1/workflows/{workflowId}/publish. Staff. Sends Ken-Version 1.1.
Requires workflows edit. note (500 characters) is shown in the version
history.

The gate, in order:
1. The draft passes validation in publish mode: limits set
   (creditsPerMonth, creditsPerRun, runsPerDay), secrets exist, apps
   connected. Failures are 400 invalid_definition with one error.details
   entry per issue ({field: <JSON path>, code, message}).
2. Every send step keeps approval "required". approval "auto" passes only
   for a workspace with the workflows_auto_send flag, and even then every
   send still waits for approval in Today. Otherwise 400
   invalid_definition with code approval_required on that step.
3. A test run passed on this exact draft. Otherwise 409 invalid_state:
   "A test run must pass on this draft before publishing. Call
   POST /v1/workflows/{workflowId}/test, then publish again."
A draft saved while publishing is 409 version_conflict:
"The draft changed while it was being published. Read the workflow
again, test the new draft, then publish."

An off workflow with no draft (turned off, or a default workflow Kenso set
up off) is turned on instead: its published version goes live through
gates 1 and 2, without a test (that version passed one when it was
published), and no new version is made. If that version cannot go live
(its trigger no longer binds) it is 409 invalid_state: "The workflow
could not be turned on with its published version. Open it, test it and
publish it again." A live workflow with no draft is 409 invalid_state:
"Workflow has no draft to publish."

Returns the workflow as workflows get, with status live and published set.
A workflow with a webhook trigger also carries webhook {url, live}, for a
caller with integrations: the URL the user pastes into their form tool (DEV-5232).
warnings (DEV-9626) lists what did not stop the publish, omitted when there is
none: code from_inbox_cannot_send for each send.email@1 step whose literal
fromInbox names an inbox that cannot send a 1:1 email now, with field (JSON
path), stepId, inboxId, reason (the reason of inboxes operation
get-one-to-one-readiness) and message. The workflow is live; that step's
emails wait until the inbox can send, so tell the user and fix the inbox or
the step. Tolerate codes not listed here.
The previous live version stops taking new runs; runs already started
finish on it. A live run that reaches send.email@1, send.linkedin@1 or
send.whatsapp@1 waits until a person approves the touch (Ken approves a
LinkedIn or WhatsApp send on auto) and the Accounts send pass (DEV-1618)
sends it, where sending is on for the workspace, for up to the 14-day
wait timeout.
send.facebook@1 and send.instagram@1 wait the same way.

versions-restore

Write. Early access: needs workflows on for the workspace. POST https://api.ken.so/v1/workflows/{workflowId}/versions/{number}/restore

Path: workflowId, number

Copy an old version's definition into the draft. The published version is unchanged.

POST /api/v1/workflows/{workflowId}/versions/{number}/restore. Staff. Sends
Ken-Version 1.1. Requires workflows edit. Replaces the current draft (or
creates one) with that version's definition. 404 not_found for an unknown
number. Returns the workflow (as workflows get) with its new draftVersion.

unpublish

Write. Early access: needs workflows on for the workspace. POST https://api.ken.so/v1/workflows/{workflowId}/unpublish

Path: workflowId

Turn a live workflow off. Its trigger stops; runs already started finish. The draft and the version history stay; publish again to turn it back on.

POST /api/v1/workflows/{workflowId}/unpublish. Staff. Sends Ken-Version
1.1. Requires workflows edit. A workflow that is not live answers 409
invalid_state "Workflow is not live.". Returns the workflow as workflows
get, with status off.

update

Write. Early access: needs workflows on for the workspace. PATCH https://api.ken.so/v1/workflows/{workflowId}

Path: workflowId

Body (json): baseVersion integer, definition object, note string, patch object

Save the workflow's draft: a whole new definition, or an RFC 6902 patch. base_version is the draftVersion you last read; a stale one answers 409.

PATCH /api/v1/workflows/{workflowId}. Staff. Sends Ken-Version 1.1.
Requires workflows edit. Never changes what the published version runs.
One exception for words (DEV-7291): a save whose definition differs from
the published one only in its plain block (same definitionHash) also
writes that plain block onto the published version, so a live workflow
shows its new words with no unpublished change and no new test. Patch
plain text with paths such as /plain/steps/0/text.

base_version: the draftVersion from your last read (0 when the workflow
had no draft; the first save then copies the published version). Send
exactly one of definition (the whole kenWorkflow object) and patch (a list
of {op, path, value} with op add, replace or remove and path an RFC 6901
pointer such as /steps/2/with/prompt or /steps/- to append).

When someone else saved since your read, the backend answers 409
version_conflict with currentVersion at the top level of the error body:
read the workflow again, reapply your change, and send currentVersion as
base_version. A patch path that does not exist answers 400 with
error.details[0].code path_not_found (unsupported_op and invalid_patch are
the other codes). A result that does not parse answers 400
invalid_definition. Returns the workflow with its new draftVersion.

Knowledge prompt links (DEV-3163): an ai.agent or ai.qualify step's
instructions, an ai.prompt step's prompt and an ai.research step's focus
can come from a Knowledge prompt. To link (or revert to the prompt), set
with.knowledgePromptId to the prompt's id and copy its body into that text
in one save; to unlink, remove with.knowledgePromptId and keep the text.
The step always runs its own text. A body change in Knowledge rewrites the
text of linked steps still equal to the old body in the draft (the draft's
version goes up). An id that is not a Knowledge prompt of this workspace
answers 400 invalid_definition with error.details[0].code
knowledge_prompt_not_found on that step; a deleted prompt keeps its link.
Write the id as 12 or "12" (a whole number above 0): any other form, such
as "012" or "+12", is invalid_knowledge_prompt_id.

Example: workflow_id=12, base_version=3, patch=[{"op": "replace", "path":
"/steps/0/with/criteria", "value": "Agencies with 10+ people"}]

validate

Read. Early access: needs workflows on for the workspace. POST https://api.ken.so/v1/workflows/{workflowId}/validate

Path: workflowId

Body (json): definition object, mode string

Check a workflow definition and list every problem with its JSON path and a fix. Saves nothing. Run it before publishing.

POST /api/v1/workflows/{workflowId}/validate. Staff. Sends Ken-Version 1.1.
Requires workflows view. 404 not_found for a workflow outside the workspace.

definition: a kenWorkflow object to check; omit it to check the saved draft
(else the published version). mode: draft (default: shape, step types,
inputs, graph, formulas) or publish (also limits, secrets, the Slack
connection and other requirements).

Returns {data: {valid, mode, issues: [{severity, path, code, message,
fix}]}}. valid is true when no issue has severity error; warnings do not
block. path is a JSON path into the definition such as
$.steps[2].with.prompt. A formula issue's message starts with "<code>: "
(the formula error code). Every string or list a formula builds is capped
at 64 KB; going over is formula_too_large. Data sources (workflows create
has the shape) add feature_disabled (workflow_sources is off),
invalid_workflow_type, workflow_type_mismatch (a source of the other
type), duplicate_source (a source repeats another, or a second webhook),
invalid_schedule (a source that reads on a schedule without one, a
schedule on a source that keeps its own cadence, or once on
trigger.campaign_leads@1), invalid_source_campaign
(a trigger.campaign_leads@1 campaignId that is not the campaign workflow's
own campaign, or not a campaign of the workspace), campaign_leads_required
(a Bulk import campaign workflow without trigger.campaign_leads@1 for its
campaign), and too_large past 10 sources.