Skip to main content

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.

​
GET /api/v1/content

List all content items for the tenant. Supports cursor-based pagination and filtering.

​
Query Parameters

ParameterTypeDefaultDescription
limitinteger20Max results per page
cursorstring—Cursor for pagination
statusstring—Filter by status (e.g., "draft", "published")
channelTypestring—Filter by channel type
isTemplatestring—Filter templates ("true" or "false")
sourceTypestring—Filter by source type

​
Response

{
  "data": [
    {
      "id": "content_001",
      "name": "Spring Promotion Email",
      "tenantId": "tenant_001",
      "channelType": "email",
      "status": "published",
      "version": 4,
      "content": { "subject": "Spring deals just for you", "body": "<html>...</html>" },
      "blocks": [],
      "personalization": { "customer_name": "{{customer.name}}" },
      "isTemplate": false,
      "sourceType": "internal",
      "parentTemplate": { "id": "tmpl_001", "name": "Seasonal Template" },
      "source": null,
      "createdAt": "2026-03-01T10:00:00.000Z",
      "updatedAt": "2026-03-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 15,
    "hasMore": false,
    "limit": 20,
    "cursor": null
  }
}

​
POST /api/v1/content

Create a new content item. The item starts in "draft" status at version 1. An initial ContentVersion snapshot is created automatically.

​
Request Body

FieldTypeRequiredDescription
namestringYesContent item name (must be unique per tenant)
channelTypestringYesChannel type (e.g., "email", "sms", "push")
descriptionstringNoDescription
contentobjectNoContent payload (e.g., subject, body, etc.)
blocksarrayNoContent blocks for block-based editing
personalizationobjectNoPersonalization configuration
parentTemplateIdstringNoID of a template to inherit from
isTemplatebooleanNoWhether this item is a reusable template. Default: false

​
Example

curl -X POST https://playground.kaireonai.com/api/v1/content \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "name": "Welcome Email",
    "channelType": "email",
    "content": {
      "subject": "Welcome to Kaireon!",
      "body": "<html>...</html>"
    },
    "personalization": {
      "customer_name": "{{customer.name}}"
    }
  }'

​
Error Codes

CodeReason
201Content item created successfully
409A content item with that name already exists
Response: 201 Created with the content item object.

​
GET /api/v1/content/

Get a content item with its parent template, source, and recent version history (up to 20 versions).

​
Response

{
  "id": "content_001",
  "name": "Spring Promotion Email",
  "status": "published",
  "version": 4,
  "content": { "subject": "Spring deals just for you", "body": "<html>...</html>" },
  "blocks": [],
  "personalization": { "customer_name": "{{customer.name}}" },
  "parentTemplate": { "id": "tmpl_001", "name": "Seasonal Template" },
  "source": null,
  "publishedAt": "2026-03-10T12:00:00.000Z",
  "versions": [
    { "id": "cv_004", "version": 4, "createdAt": "2026-03-10T12:00:00.000Z" }
  ]
}

​
PUT /api/v1/content/

Update a content item. Increments the version number and creates a version snapshot automatically.

​
Request Body

FieldTypeRequiredDescription
namestringNoUpdated name
contentobjectNoUpdated content payload
blocksarrayNoUpdated content blocks
personalizationobjectNoUpdated personalization config
Response: 200 OK

​
DELETE /api/v1/content/

Archive a content item (soft delete — sets status to "archived"). Response: 204 No Content

​
POST /api/v1/content//submit

Submit a draft content item for review. Changes status from "draft" to "in_review". Prerequisite: Content must be in "draft" status. Response: 200 OK

​
POST /api/v1/content//approve

Approve a content item that is in review. Changes status from "in_review" to "approved". Prerequisite: Content must be in "in_review" status. The approver cannot be the same user who submitted the content (self-approval prevention). Response: 200 OK

​
POST /api/v1/content//publish

Publish an approved content item. Sets status to "published" and records publishedAt. Creates a version snapshot. Prerequisite: Content must be in "approved" status. Response: 200 OK

​
POST /api/v1/content//reject

Reject a content item in review. Returns it to "draft" status. Prerequisite: Content must be in "in_review" status.

​
Request Body

FieldTypeRequiredDescription
reasonstringNoRejection reason
Response: 200 OK

​
GET /api/v1/content//versions

List all version snapshots for a content item (up to 100, newest first).

​
Response

[
  {
    "id": "cv_004",
    "contentItemId": "content_001",
    "version": 4,
    "content": { "subject": "Spring deals just for you" },
    "changeNote": "Published",
    "changedBy": "user_001",
    "createdAt": "2026-03-10T12:00:00.000Z"
  }
]

​
POST /api/v1/content//revert/

Revert a content item to a previous version. Creates a new version with the snapshot’s content and resets status to "draft". Prerequisite: Target version must be less than the current version.

​
Example

curl -X POST https://playground.kaireonai.com/api/v1/content/content_001/revert/2 \
  -H "X-Tenant-Id: my-tenant"
Response: 200 OK with the updated content item at the new version number.

​
Content Lifecycle

draft --> in_review --> approved --> published
  ^          |
  |          v
  +------ rejected (returns to draft)
  ^
  |
  +------ reverted (returns to draft)

​
Roles

EndpointAllowed Roles
GET /contentadmin, editor, viewer
POST /contentadmin, editor
GET /content/{id}admin, editor, viewer
PUT /content/{id}admin, editor
DELETE /content/{id}admin, editor
POST /content/{id}/submitadmin, editor
POST /content/{id}/approveadmin, editor
POST /content/{id}/publishadmin, editor
POST /content/{id}/rejectadmin, editor
GET /content/{id}/versionsadmin, editor, viewer
POST /content/{id}/revert/{version}admin, editor
See also: Content Management