Documentation Index
Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
Use this file to discover all available pages before exploring further.
Outcome types define the vocabulary of customer responses in the platform. Each outcome type has a classification (positive, negative, or neutral) and a category (impression or response). System-default outcome types are auto-seeded on first access.
All outcome types support soft-delete (a deletedAt timestamp is set instead of permanent removal), version tracking (the version field auto-increments on every update), and audit logging (before/after snapshots are recorded for every CRUD operation).
Base path
List outcome types
GET /api/v1/outcome-types
Query parameters
| Parameter | Required | Type | Description |
|---|
includeDeleted | No | string | Set to "true" to include soft-deleted outcome types in the results. |
System defaults
| Key | Name | Classification | Category |
|---|
impression | Impression | neutral | impression |
click | Click | positive | response |
dismiss | Dismiss | negative | response |
accept | Accept | positive | response |
convert | Convert | positive | response |
not_presented | Not Presented | neutral | impression |
requested_info | Requested More Info | positive | response |
not_interested | Not Interested | negative | response |
expired | Expired | neutral | impression |
deferred | Deferred | neutral | response |
Response 200
Returns a flat array (not paginated) of all outcome types.
[
{
"id": "ot_001",
"tenantId": "t_001",
"key": "click",
"name": "Click",
"description": "",
"classification": "positive",
"category": "response",
"isSystem": true,
"ordinal": 1,
"status": "active",
"version": 1,
"deletedAt": null,
"createdAt": "2026-03-10T12:00:00.000Z",
"updatedAt": "2026-03-10T12:00:00.000Z"
}
]
Error codes
| Code | Reason |
|---|
401 | Missing or invalid API key / session. |
403 | Insufficient role. |
Create an outcome type
POST /api/v1/outcome-types
isSystem: false and can be fully edited or deleted.
Request body
| Field | Required | Type | Description |
|---|
key | Yes | string (1-255) | Unique key identifier (e.g., "purchased", "bounced"). |
name | Yes | string (1-255) | Display name. |
description | No | string | Description. Default "". |
classification | No | enum | positive, negative, neutral. Default "neutral". |
category | No | enum | impression, response. Default "response". |
ordinal | No | integer (>= 0) | Sort order. Default 99. |
status | No | enum | draft, active (default), paused, archived. |
Example request
{
"key": "purchased",
"name": "Purchased",
"classification": "positive",
"category": "response",
"ordinal": 10
}
Response 201
Returns the created outcome type object with version: 1 and deletedAt: null. An audit log entry is created with a create action.
Error codes
| Code | Reason |
|---|
400 | Validation error (missing key or name). |
401 | Missing or invalid API key / session. |
403 | Insufficient role (requires editor or admin). |
415 | Content-Type is not application/json. |
Update an outcome type
PUT /api/v1/outcome-types
version field is auto-incremented and a before/after audit snapshot is recorded.
System outcome types (isSystem: true) only allow editing name, description, and ordinal. The key, classification, category, and status fields are locked for system types.
Request body
| Field | Required | Type | Description |
|---|
id | Yes | string | The outcome type ID to update. |
key | No | string | Updated key (custom types only). |
name | No | string | Updated display name. |
description | No | string | Updated description. |
classification | No | enum | Updated classification (custom types only). |
category | No | enum | Updated category (custom types only). |
ordinal | No | integer | Updated sort order. |
status | No | enum | Updated status (custom types only). |
Response 200
Returns the updated outcome type object with the incremented version.
Error codes
| Code | Reason |
|---|
400 | Validation error. |
401 | Missing or invalid API key / session. |
403 | Insufficient role. |
404 | Outcome type not found. |
Delete an outcome type (soft-delete)
DELETE /api/v1/outcome-types?id={outcomeTypeId}
deletedAt timestamp. System outcome types cannot be deleted.
Query parameters
| Parameter | Required | Type | Description |
|---|
id | Yes | string | Outcome type ID to delete. |
Response 200
Error codes
| Code | Reason |
|---|
400 | Missing id query parameter, entity not found, or entity already deleted. |
401 | Missing or invalid API key / session. |
403 | Cannot delete system outcome types. |
404 | Outcome type not found. |
To restore a soft-deleted outcome type, use POST /api/v1/restore?entityType=outcomeType&id={outcomeTypeId} (admin only).
Role requirements
| Method | Minimum role |
|---|
| GET | viewer |
| POST | editor |
| PUT | editor |
| DELETE | editor |
