> ## 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.

# Content Sources

> Manage external CMS integrations for syncing content into KaireonAI.

Content sources connect external CMS platforms (Contentful, Strapi, Sanity, etc.) to KaireonAI. Content is synced via webhooks or manual sync triggers and imported as content items.

## GET /api/v1/content-sources

List all content sources for the tenant.

### Response

```json theme={null}
[
  {
    "id": "clx...",
    "name": "Marketing Contentful",
    "provider": "contentful",
    "config": { "spaceId": "abc123", "environment": "master" },
    "syncMode": "webhook",
    "syncIntervalMinutes": null,
    "autoPublish": true,
    "mappings": { "title": "fields.title", "body": "fields.body" },
    "status": "active",
    "lastSyncAt": "2026-03-18T10:00:00.000Z",
    "createdAt": "2026-03-01T00:00:00.000Z"
  }
]
```

***

## POST /api/v1/content-sources

Create a new content source. **Admin only.**

### Request Body

| Field                 | Type    | Required | Description                                                        |
| --------------------- | ------- | -------- | ------------------------------------------------------------------ |
| `name`                | string  | Yes      | Source name                                                        |
| `provider`            | string  | Yes      | CMS provider (e.g., `contentful`, `strapi`, `sanity`, `wordpress`) |
| `config`              | object  | No       | Provider-specific configuration                                    |
| `syncMode`            | string  | No       | Sync mode: `webhook` or `poll` (default: `webhook`)                |
| `syncIntervalMinutes` | number  | No       | Poll interval in minutes (for poll mode)                           |
| `autoPublish`         | boolean | No       | Auto-publish synced content (default: false)                       |
| `mappings`            | object  | No       | Field mappings from CMS schema to content item fields              |

### Example

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/content-sources \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "name": "Blog CMS",
    "provider": "contentful",
    "config": { "spaceId": "abc123", "accessToken": "..." },
    "syncMode": "webhook",
    "autoPublish": false,
    "mappings": { "title": "fields.title", "body": "fields.body" }
  }'
```

### Response (201)

Returns the created content source object.

***

## GET /api/v1/content-sources/{id}

Get a single content source by ID.

***

## PUT /api/v1/content-sources/{id}

Update a content source. **Admin only.**

### Request Body

Same fields as POST, all optional.

### Error Responses

| Status | Cause                                                                                   |
| ------ | --------------------------------------------------------------------------------------- |
| `404`  | Content source not found for the caller's tenant (includes ids owned by another tenant) |
| `409`  | A content source with that name already exists                                          |

The lookup is scoped by the `(tenantId, id)` compound key, so a `PUT` against an id owned by another tenant returns `404` — never `500`.

***

## DELETE /api/v1/content-sources/{id}

Delete a content source. **Admin only.**

### Response

`204 No Content` on success.

### Error Responses

| Status | Cause                                                                                   |
| ------ | --------------------------------------------------------------------------------------- |
| `404`  | Content source not found for the caller's tenant (includes ids owned by another tenant) |

***

## POST /api/v1/content-sources/{id}/sync

Trigger a manual sync from the content source. Fetches all content items from the CMS and upserts them as content items. **Editor or Admin.**

Sync operations have a 120-second timeout and are capped at 5,000 items per sync.

### Response

```json theme={null}
{
  "synced": 47,
  "source": "clx..."
}
```

If the sync exceeds the timeout:

```json theme={null}
{
  "error": {
    "code": "TIMEOUT",
    "message": "Content source sync timed out",
    "status": 504
  }
}
```