AI prompts
Prompts for AI columns and personalization: create, edit, delete and test them.
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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
promptId | path | integer (int64) | required | The prompt's id. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The 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-Id | header | integer (int64) | optional | The 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
/v1/promptsprompts.list- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
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,limitorcursoris not valid.404 not_found: the campaign or segment is not in this workspace.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | query | integer (int64) | optional | Only this campaign's prompts. |
segmentId | query | integer (int64) | optional | Only this segment's prompts. With campaignId, the segment must be in that campaign. |
flow | query | string | optional | Only prompts of this flow: qualification, personalization, rewriting, segmentation, tone_of_voice or scoring. |
q | query | string | optional | Only prompts whose name matches this text, at most 200 characters. |
limit | query | integer (int32) | optional | How many prompts to return, from 1 to 200. Defaults to 50. |
cursor | query | string | optional | The nextCursor of the previous page. Omit it for the first page. |
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
/v1/promptsprompts.create- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
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 (seeerror.impact). Set theconfirmquery parameter to true.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
confirm | query | boolean | optional | Set to true to go ahead when the change would clear AI results Kenso already made. Default false. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | The prompt's name. On a personalization prompt with toOutput true, it is also the AI variable's name. |
prompt | string | required | The instructions the AI follows. Required. |
audienceDescription | string | optional | Who the campaign targets. Kenso adds it to the qualification, scoring and personalization prompts. |
qualificationCriteria | string | optional | What makes a contact a fit. Qualification and scoring read it. |
disqualificationCriteria | string | optional | What rules a contact out. Qualification and scoring read it. |
scoringCriteria | string | optional | What makes a contact a good or a poor fit. A scoring prompt needs it to run. |
type | string | required | The message role the prompt is sent as: system, user or assistant. Required. |
flow | string | required | The step the prompt belongs to: qualification, personalization, rewriting, segmentation or scoring. Required. |
campaignId | integer (int64) | optional | The campaign the prompt belongs to. Send it, segmentId, or both. |
segmentId | integer (int64) | optional | The segment the prompt belongs to. With campaignId, the segment must be in that campaign. |
promptTemplateId | integer (int64) | optional | A prompt template of this workspace to add the prompt to. Optional. |
toOutput | boolean | optional | On a personalization prompt, true to have the AI write the result as an AI variable for the emails. Defaults to false. |
toRewrite | integer (int32) | optional | Above 0 to have the rewriting step rewrite this AI variable. Optional. |
order | integer (int32) | optional | Where the prompt sits among its campaign's prompts. Lower numbers come first. Defaults to 0. |
fallbackIfEmpty | string | optional | The text to use when the AI variable comes out empty. Optional. |
isRequiredForSending | boolean | optional | True to hold a contact from sending while this AI variable is empty and there is no fallback. Defaults to false. |
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
/v1/prompts/{promptId}prompts.get- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns one prompt.
Errors:
404 not_found: the prompt is not in this workspace.
Requires Campaigns view.
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
/v1/prompts/{promptId}prompts.update- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
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 (seeerror.impact). Set theconfirmquery parameter to true.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
confirm | query | boolean | optional | Set to true to go ahead when the change would clear AI results Kenso already made. Default false. |
Request body
application/json, optional: object.
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
/v1/prompts/{promptId}prompts.delete- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Deletes a prompt. Returns 204.
Errors:
404 not_found: the prompt is not in this workspace.409 conflict: the delete would clear AI results (seeerror.impact). Set theconfirmquery parameter to true.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
confirm | query | boolean | optional | Set to true to go ahead when the change would clear AI results Kenso already made. Default false. |
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
HTTP/1.1 204 No ContentTest prompts on sample contacts
/v1/prompts/testprompts.test- Permission
- Campaigns edit and the
askpermission - Rate limit
- 30 requests a minute and 200 a day per workspace (Free plan: 3 a minute and 20 a day)
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 thansampleSize.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.
| Field | Type | Required | Description |
|---|---|---|---|
campaignId | integer (int64) | required | The campaign whose prompts run. Required. |
flow | string | required | The flow to test: qualification, segmentation or personalization. Required. |
sampleSize | integer (int32) | optional | How many contacts to sample, from 1 to 100. Defaults to 10. |
segmentId | integer (int64) | optional | On a personalization test, the segment whose prompts run. Omit it to run the campaign's default segment. Not accepted on other flows. |
modelOverrides | map of PromptTestOverrideRequest | optional | Models to use for this run only, keyed by flow. Set only the tested flow, plus rewriting on a personalization test. |
excludeContactIds | array of integer (int64) | optional | Contact ids to leave out of the sample. Each id must be above 0. |
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.
More in Copy and personalization:Custom variablesPrompt versionsImage variablesCopy gradesCopy checksVoicesVoice notesVoice note previewsMessage templatesAll resources