Kenso
Get early access

Prompts

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

AI6 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors

List prompts in the current workspace

GET/v1/promptsprompts.list

Try it on developer.ken.so

Ordered by id. Optional campaignId, segmentId, and flow narrow the page. q matches the name. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
CampaignId
In: query
integer (int64)
optional
SegmentId
In: query
integer (int64)
optional
Flow
In: query
string
optional
Q
In: query
string
optional
Limit
In: query
integer (int32)
optional
Cursor
In: query
string
optional
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

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

Field
Type
Description
id
integer (int64)
name
string
prompt
string
audienceDescription
string
qualificationCriteria
string
disqualificationCriteria
string
scoringCriteria
string
type
string
flow
string
campaignId
integer (int64)
segmentId
integer (int64)
segmentName
string
promptTemplateId
integer (int64)
toOutput
boolean
toRewrite
integer (int32)
order
integer (int32)
fallbackIfEmpty
string
isRequiredForSending
boolean
createdAt
string (date-time)
updatedAt
string (date-time)
Request
curl -X GET "https://api.ken.so/v1/prompts" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": [
    {
      "id": 812,
      "name": "string",
      "prompt": "string",
      "audienceDescription": "string",
      "qualificationCriteria": "string",
      "disqualificationCriteria": "string",
      "scoringCriteria": "string",
      "type": "string",
      "flow": "string",
      "campaignId": 812,
      "segmentId": 812,
      "segmentName": "string",
      "promptTemplateId": 812,
      "toOutput": true,
      "toRewrite": 1,
      "order": 1,
      "fallbackIfEmpty": "string",
      "isRequiredForSending": true,
      "createdAt": "2026-09-23T15:02:11Z",
      "updatedAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}

Create a prompt in the current workspace

POST/v1/promptsprompts.create

Try it on developer.ken.so

Returns 201 and Location. campaignId or segmentId is required so the prompt stays in the workspace. confirm=true is required when the write would refresh cached AI results. Requires WriteAccess.

Parameters

Name
In
Type
Required
Description
confirm
In: query
boolean
optional
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
name
string
optional
prompt
string
optional
audienceDescription
string
optional
qualificationCriteria
string
optional
disqualificationCriteria
string
optional
scoringCriteria
string
optional
type
string
optional
flow
string
optional
campaignId
integer (int64)
optional
segmentId
integer (int64)
optional
promptTemplateId
integer (int64)
optional
toOutput
boolean
optional
toRewrite
integer (int32)
optional
order
integer (int32)
optional
fallbackIfEmpty
string
optional
isRequiredForSending
boolean
optional

Response 201

data is a PromptModel.

Field
Type
Description
id
integer (int64)
name
string
prompt
string
audienceDescription
string
qualificationCriteria
string
disqualificationCriteria
string
scoringCriteria
string
type
string
flow
string
campaignId
integer (int64)
segmentId
integer (int64)
segmentName
string
promptTemplateId
integer (int64)
toOutput
boolean
toRewrite
integer (int32)
order
integer (int32)
fallbackIfEmpty
string
isRequiredForSending
boolean
createdAt
string (date-time)
updatedAt
string (date-time)
Request
curl -X POST "https://api.ken.so/v1/prompts" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "prompt": "string",
  "audienceDescription": "string",
  "qualificationCriteria": "string",
  "disqualificationCriteria": "string",
  "scoringCriteria": "string",
  "type": "string",
  "flow": "string",
  "campaignId": 812,
  "segmentId": 812,
  "promptTemplateId": 812,
  "toOutput": true,
  "toRewrite": 1,
  "order": 1,
  "fallbackIfEmpty": "string",
  "isRequiredForSending": true
}'
Response 201
{
  "success": true,
  "data": {
    "id": 812,
    "name": "string",
    "prompt": "string",
    "audienceDescription": "string",
    "qualificationCriteria": "string",
    "disqualificationCriteria": "string",
    "scoringCriteria": "string",
    "type": "string",
    "flow": "string",
    "campaignId": 812,
    "segmentId": 812,
    "segmentName": "string",
    "promptTemplateId": 812,
    "toOutput": true,
    "toRewrite": 1,
    "order": 1,
    "fallbackIfEmpty": "string",
    "isRequiredForSending": true,
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Return one prompt in the current workspace

GET/v1/prompts/{promptId}prompts.get

Try it on developer.ken.so

A missing or cross-workspace id is not_found. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
promptId
In: path
integer (int64)
required
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a PromptModel.

Field
Type
Description
id
integer (int64)
name
string
prompt
string
audienceDescription
string
qualificationCriteria
string
disqualificationCriteria
string
scoringCriteria
string
type
string
flow
string
campaignId
integer (int64)
segmentId
integer (int64)
segmentName
string
promptTemplateId
integer (int64)
toOutput
boolean
toRewrite
integer (int32)
order
integer (int32)
fallbackIfEmpty
string
isRequiredForSending
boolean
createdAt
string (date-time)
updatedAt
string (date-time)
Request
curl -X GET "https://api.ken.so/v1/prompts/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": {
    "id": 812,
    "name": "string",
    "prompt": "string",
    "audienceDescription": "string",
    "qualificationCriteria": "string",
    "disqualificationCriteria": "string",
    "scoringCriteria": "string",
    "type": "string",
    "flow": "string",
    "campaignId": 812,
    "segmentId": 812,
    "segmentName": "string",
    "promptTemplateId": 812,
    "toOutput": true,
    "toRewrite": 1,
    "order": 1,
    "fallbackIfEmpty": "string",
    "isRequiredForSending": true,
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Update a prompt

PATCH/v1/prompts/{promptId}prompts.update

Try it on developer.ken.so

Absent fields stay unchanged. JSON null clears a text field or promptTemplateId. segmentId cannot change on this route, and campaignId cannot be cleared on a prompt without a segment (400: it would belong to no workspace). confirm=true is required when the write would refresh cached AI results. Requires WriteAccess.

Parameters

Name
In
Type
Required
Description
promptId
In: path
integer (int64)
required
confirm
In: query
boolean
optional
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional: object.

Response 200

data is a PromptModel.

Field
Type
Description
id
integer (int64)
name
string
prompt
string
audienceDescription
string
qualificationCriteria
string
disqualificationCriteria
string
scoringCriteria
string
type
string
flow
string
campaignId
integer (int64)
segmentId
integer (int64)
segmentName
string
promptTemplateId
integer (int64)
toOutput
boolean
toRewrite
integer (int32)
order
integer (int32)
fallbackIfEmpty
string
isRequiredForSending
boolean
createdAt
string (date-time)
updatedAt
string (date-time)
Request
curl -X PATCH "https://api.ken.so/v1/prompts/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'
Response 200
{
  "success": true,
  "data": {
    "id": 812,
    "name": "string",
    "prompt": "string",
    "audienceDescription": "string",
    "qualificationCriteria": "string",
    "disqualificationCriteria": "string",
    "scoringCriteria": "string",
    "type": "string",
    "flow": "string",
    "campaignId": 812,
    "segmentId": 812,
    "segmentName": "string",
    "promptTemplateId": 812,
    "toOutput": true,
    "toRewrite": 1,
    "order": 1,
    "fallbackIfEmpty": "string",
    "isRequiredForSending": true,
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Delete a prompt

DELETE/v1/prompts/{promptId}prompts.delete

Try it on developer.ken.so

Returns 204. confirm=true is required when deletion would refresh cached AI results. Requires WriteAccess.

Parameters

Name
In
Type
Required
Description
promptId
In: path
integer (int64)
required
confirm
In: query
boolean
optional
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 204

Request
curl -X DELETE "https://api.ken.so/v1/prompts/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 204
HTTP/1.1 204 No Content

Run a prompt test against live model calls

POST/v1/prompts/testprompts.test

Try it on developer.ken.so

Samples contacts in the campaign and runs the requested flow. This spends model usage. A missing campaign is not_found. Requires PromptTestAccess.

Parameters

Name
In
Type
Required
Description
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
required
The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field
Type
Required
Description
campaignId
integer (int64)
optional
flow
string
optional
sampleSize
integer (int32)
optional
segmentId
integer (int64)
optional
modelOverrides
map of PromptTestOverrideRequest
optional
excludeContactIds
array of integer (int64)
optional

Response 200

data is a PromptTestResultModel.

Field
Type
Description
campaignId
integer (int64)
flow
string
requestedSampleSize
integer (int32)
returnedSampleSize
integer (int32)
segmentId
integer (int64)
provider
string
model
string
cacheStrategy
string
successCount
integer (int32)
failureCount
integer (int32)
usageSummary
PromptTestUsageModel
samples
array of PromptTestSampleModel
Request
curl -X POST "https://api.ken.so/v1/prompts/test" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignId": 812,
  "flow": "string",
  "sampleSize": 1,
  "segmentId": 812,
  "modelOverrides": {
    "key": {
      "model": "string",
      "maxTokens": 1,
      "temperature": 0.5,
      "reasoningLevel": "string"
    }
  },
  "excludeContactIds": [
    812
  ]
}'
Response 200
{
  "success": true,
  "data": {
    "campaignId": 812,
    "flow": "string",
    "requestedSampleSize": 1,
    "returnedSampleSize": 1,
    "segmentId": 812,
    "provider": "string",
    "model": "string",
    "cacheStrategy": "string",
    "successCount": 1,
    "failureCount": 1,
    "usageSummary": {
      "averageInputTokens": 1,
      "averageCacheReadTokens": 1,
      "averageOutputTokens": 1,
      "totalEstimatedCostUsd": 0.5,
      "averageEstimatedCostUsd": 0.5
    },
    "samples": [
      {
        "contactId": 812,
        "fullName": "string",
        "linkedInUrl": "https://example.com",
        "title": "string",
        "companyName": "string",
        "segmentId": 812,
        "segmentName": "string",
        "success": true,
        "provider": "string",
        "model": "string",
        "cacheStrategy": "string",
        "rewritingProvider": "string",
        "rewritingModel": "string",
        "rewritingCacheStrategy": "string",
        "usage": {
          "inputTokens": 1,
          "outputTokens": 1,
          "totalTokens": 1,
          "cacheCreationTokens": 1,
          "cacheReadTokens": 1,
          "reasoningTokens": 1
        },
        "estimatedCostUsd": 0.5,
        "errorMessage": "string",
        "isQualified": true,
        "qualificationResponse": "string",
        "matchedSegmentName": "string",
        "segmentationReasoning": "string",
        "personalizationOutputs": [
          {
            "name": "string",
            "value": "string"
          }
        ],
        "rewritingOutputs": [
          {
            "name": "string",
            "value": "string"
          }
        ],
        "finalOutputs": [
          {
            "name": "string",
            "value": "string"
          }
        ]
      }
    ]
  }
}
More in AI:AI runsAgent teamPrompt versionsEmail copy gradesEmail copy lintsAI linesAI line holdsTranslationsAll resources