Skip to Content
Copy and personalization

AI prompts

Prompts for AI columns and personalization: create, edit, delete and test them.

Copy and personalization6 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
promptIdpathinteger (int64)requiredThe prompt's 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.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

List prompts

GET/v1/promptsprompts.list
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns the workspace's prompts in id order. Filter with campaignId, segmentId, flow and q, which matches the name.

Errors:

  • 400 validation_failed: a filter, limit or cursor is not valid.
  • 404 not_found: the campaign or segment is not in this workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
campaignIdqueryinteger (int64)optionalOnly this campaign's prompts.
segmentIdqueryinteger (int64)optionalOnly this segment's prompts. With campaignId, the segment must be in that campaign.
flowquerystringoptionalOnly prompts of this flow: qualification, personalization, rewriting, segmentation, tone_of_voice or scoring.
qquerystringoptionalOnly prompts whose name matches this text, at most 200 characters.
limitqueryinteger (int32)optionalHow many prompts to return, from 1 to 200. Defaults to 50.
cursorquerystringoptionalThe nextCursor of the previous page. Omit it for the first page.
Request
curl -X GET "https://api.ken.so/v1/prompts?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a list of Prompt. Each item has these fields. The response also carries pagination.

Show the 20 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Create a prompt

POST/v1/promptsprompts.create
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Adds a prompt to a campaign or segment. Send prompt, flow, type, and campaignId or segmentId. Returns 201 with a Location header.

Errors:

  • 400 validation_failed: a required field is missing or a value is not accepted.
  • 404 not_found: the campaign, segment or prompt template is not in this workspace.
  • 409 conflict: the write would clear AI results (see error.impact). Set the confirm query parameter to true.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
confirmquerybooleanoptionalSet to true to go ahead when the change would clear AI results Kenso already made. Default false.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringoptionalThe prompt's name. On a personalization prompt with toOutput true, it is also the AI variable's name.
promptstringrequiredThe instructions the AI follows. Required.
audienceDescriptionstringoptionalWho the campaign targets. Kenso adds it to the qualification, scoring and personalization prompts.
qualificationCriteriastringoptionalWhat makes a contact a fit. Qualification and scoring read it.
disqualificationCriteriastringoptionalWhat rules a contact out. Qualification and scoring read it.
scoringCriteriastringoptionalWhat makes a contact a good or a poor fit. A scoring prompt needs it to run.
typestringrequiredThe message role the prompt is sent as: system, user or assistant. Required.
flowstringrequiredThe step the prompt belongs to: qualification, personalization, rewriting, segmentation or scoring. Required.
campaignIdinteger (int64)optionalThe campaign the prompt belongs to. Send it, segmentId, or both.
segmentIdinteger (int64)optionalThe segment the prompt belongs to. With campaignId, the segment must be in that campaign.
promptTemplateIdinteger (int64)optionalA prompt template of this workspace to add the prompt to. Optional.
toOutputbooleanoptionalOn a personalization prompt, true to have the AI write the result as an AI variable for the emails. Defaults to false.
toRewriteinteger (int32)optionalAbove 0 to have the rewriting step rewrite this AI variable. Optional.
orderinteger (int32)optionalWhere the prompt sits among its campaign's prompts. Lower numbers come first. Defaults to 0.
fallbackIfEmptystringoptionalThe text to use when the AI variable comes out empty. Optional.
isRequiredForSendingbooleanoptionalTrue to hold a contact from sending while this AI variable is empty and there is no fallback. Defaults to false.
Request
curl -X POST "https://api.ken.so/v1/prompts" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "prompt": "string",
  "audienceDescription": "string",
  "qualificationCriteria": "string",
  "disqualificationCriteria": "string",
  "scoringCriteria": "string",
  "type": "system",
  "flow": "qualification",
  "campaignId": 812,
  "segmentId": 812,
  "promptTemplateId": 812,
  "toOutput": true,
  "toRewrite": 1,
  "order": 1,
  "fallbackIfEmpty": "string",
  "isRequiredForSending": true
}'

Response 201

data is a Prompt.

Show the 20 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get a prompt

GET/v1/prompts/{promptId}prompts.get
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns one prompt.

Errors:

  • 404 not_found: the prompt is not in this workspace.

Requires Campaigns view.

Request
curl -X GET "https://api.ken.so/v1/prompts/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a Prompt.

Show the 20 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Update a prompt

PATCH/v1/prompts/{promptId}prompts.update
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Changes the fields you send, the same fields as a new prompt, and keeps the rest. null clears a text field or promptTemplateId. segmentId cannot change, and a prompt without a segment keeps its campaignId.

Errors:

  • 400 validation_failed: the body is empty, names an unknown field, or breaks a rule above.
  • 404 not_found: the prompt, campaign, segment or prompt template is not in this workspace.
  • 409 conflict: the write would clear AI results (see error.impact). Set the confirm query parameter to true.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
confirmquerybooleanoptionalSet to true to go ahead when the change would clear AI results Kenso already made. Default false.

Request body

application/json, optional: object.

Request
curl -X PATCH "https://api.ken.so/v1/prompts/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

data is a Prompt.

Show the 20 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Delete a prompt

DELETE/v1/prompts/{promptId}prompts.delete
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Deletes a prompt. Returns 204.

Errors:

  • 404 not_found: the prompt is not in this workspace.
  • 409 conflict: the delete would clear AI results (see error.impact). Set the confirm query parameter to true.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
confirmquerybooleanoptionalSet to true to go ahead when the change would clear AI results Kenso already made. Default false.
Request
curl -X DELETE "https://api.ken.so/v1/prompts/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 204

Response 204
HTTP/1.1 204 No Content

Test prompts on sample contacts

POST/v1/prompts/testprompts.test
Permission
Campaigns edit and the ask permission
Rate limit
30 requests a minute and 200 a day per workspace (Free plan: 3 a minute and 20 a day)

Try it on developer.ken.so

Runs the campaign's qualification, segmentation or personalization prompts on a random sample of its contacts and returns each result without saving it. Each sample calls the AI model and spends model usage, shown in estimatedCostUsd.

Errors:

  • 400 validation_failed: a field is not valid, or the campaign has fewer eligible contacts than sampleSize.
  • 404 not_found: the campaign or segment is not in this workspace.
  • 429 rate_limited: the workspace reached its AI limit. Try again later.

Requires Campaigns edit and the ask permission.

Request body

application/json, optional.

FieldTypeRequiredDescription
campaignIdinteger (int64)requiredThe campaign whose prompts run. Required.
flowstringrequiredThe flow to test: qualification, segmentation or personalization. Required.
sampleSizeinteger (int32)optionalHow many contacts to sample, from 1 to 100. Defaults to 10.
segmentIdinteger (int64)optionalOn a personalization test, the segment whose prompts run. Omit it to run the campaign's default segment. Not accepted on other flows.
modelOverridesmap of PromptTestOverrideRequestoptionalModels to use for this run only, keyed by flow. Set only the tested flow, plus rewriting on a personalization test.
excludeContactIdsarray of integer (int64)optionalContact ids to leave out of the sample. Each id must be above 0.
Request
curl -X POST "https://api.ken.so/v1/prompts/test" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignId": 812,
  "flow": "qualification",
  "sampleSize": 1,
  "segmentId": 812,
  "modelOverrides": {
    "key": {
      "model": "string",
      "maxTokens": 1,
      "temperature": 0.5,
      "reasoningLevel": "none"
    }
  },
  "excludeContactIds": [
    812
  ]
}'

Response 200

data is a PromptTestResult.

Show the 12 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page