Kenso
Get early access

Prompt versions

The saved prompt versions of a segment, and restoring one.

AI3 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors

List prompt versions for a segment in the current workspace

GET/v1/segments/{segmentId}/prompt-versionsprompt-versions.list

Try it on developer.ken.so

A segment outside X-Ken-Workspace-Id is not_found before versions are read. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
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 PromptVersionModel. Each item has these fields. The response also carries pagination.

Field
Type
Description
id
integer (int64)
segmentId
integer (int64)
versionNumber
integer (int32)
createdAt
string (date-time)
createdByUserId
integer (int64)
createdByEmail
string
isRevert
boolean
restoredFromVersionId
integer (int64)
restoredFromVersionNumber
integer (int32)
restoredFromCreatedAt
string (date-time)
prompts
array of PromptVersionPromptModel
Request
curl -X GET "https://api.ken.so/v1/segments/812/prompt-versions" \
  -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,
      "segmentId": 812,
      "versionNumber": 1,
      "createdAt": "2026-09-23T15:02:11Z",
      "createdByUserId": 812,
      "createdByEmail": "[email protected]",
      "isRevert": true,
      "restoredFromVersionId": 812,
      "restoredFromVersionNumber": 1,
      "restoredFromCreatedAt": "2026-09-23T15:02:11Z",
      "prompts": [
        {
          "name": "string",
          "prompt": "string",
          "type": "string",
          "flow": "string",
          "order": 1,
          "toOutput": true,
          "toRewrite": 1
        }
      ]
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}

Return one prompt version for a segment in the current workspace

GET/v1/segments/{segmentId}/prompt-versions/{versionId}prompt-versions.get

Try it on developer.ken.so

A missing segment or version is not_found. Requires ReadAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
versionId
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 PromptVersionModel.

Field
Type
Description
id
integer (int64)
segmentId
integer (int64)
versionNumber
integer (int32)
createdAt
string (date-time)
createdByUserId
integer (int64)
createdByEmail
string
isRevert
boolean
restoredFromVersionId
integer (int64)
restoredFromVersionNumber
integer (int32)
restoredFromCreatedAt
string (date-time)
prompts
array of PromptVersionPromptModel
Request
curl -X GET "https://api.ken.so/v1/segments/812/prompt-versions/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,
    "segmentId": 812,
    "versionNumber": 1,
    "createdAt": "2026-09-23T15:02:11Z",
    "createdByUserId": 812,
    "createdByEmail": "[email protected]",
    "isRevert": true,
    "restoredFromVersionId": 812,
    "restoredFromVersionNumber": 1,
    "restoredFromCreatedAt": "2026-09-23T15:02:11Z",
    "prompts": [
      {
        "name": "string",
        "prompt": "string",
        "type": "string",
        "flow": "string",
        "order": 1,
        "toOutput": true,
        "toRewrite": 1
      }
    ]
  }
}

Restore a prompt version for a segment in the current workspace

POST/v1/segments/{segmentId}/prompt-versions/{versionId}/restoreprompt-versions.restore

Try it on developer.ken.so

Qualification and scoring workflow sync stay inside the existing revert command. A segment outside the workspace is not_found before the write. dryRun returns what the restore would clear and does not write. A restore that would clear campaign AI output returns 409 conflict with error.impact until confirm is true. The body is optional. Requires WriteAccess.

Parameters

Name
In
Type
Required
Description
segmentId
In: path
integer (int64)
required
versionId
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).

Request body

application/json, optional.

Field
Type
Required
Description
confirm
boolean
optional
dryRun
boolean
optional

Response 200

data is a PromptVersionRestoreModel.

Field
Type
Description
dryRun
boolean
True when the request was a dry run: nothing was restored and Ken.Scraper.API.Canonical.PromptVersionRestoreModel.Impact is the preview.
versionNumber
integer (int32)
versionWarning
string
Set when the restore applied but version history or the model configuration was not fully captured.
hasImpact
boolean
Dry run only: whether the restore would clear campaign AI output.
impact
CanonicalInvalidationImpact
Wire counts for an AI-flow wipe. Matches AiFlowInvalidationImpactDto without its enums.
message
string
Request
curl -X POST "https://api.ken.so/v1/segments/812/prompt-versions/812/restore" \
  -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 '{
  "confirm": true,
  "dryRun": true
}'
Response 200
{
  "success": true,
  "data": {
    "dryRun": true,
    "versionNumber": 1,
    "versionWarning": "string",
    "hasImpact": true,
    "impact": {
      "qualificationResponses": 1,
      "qualifiedFlags": 1,
      "segmentationReasoning": 1,
      "segmentationAssignmentsKept": 1,
      "segmentationAssignmentsReset": 1,
      "personalizationLines": 1,
      "personalizationLeads": 1,
      "rewritingLines": 1,
      "rewritingLeads": 1
    },
    "message": "string"
  }
}
More in AI:AI runsAgent teamPromptsEmail copy gradesEmail copy lintsAI linesAI line holdsTranslationsAll resources