---
title: Events API
url: https://docs.kaltura.com/docs/events-collaboration/events-platform-api/events-platform-events-api
---

## Events API

### 5.1 Create an Event

```
POST /api/v1/events/create
Content-Type: application/json
Authorization: Bearer <KS>
```

```json
{
  "name": "Q4 All-Hands Town Hall",
  "templateId": "tm2000",
  "startDate": "2024-12-15T14:00:00.000Z",
  "endDate": "2024-12-15T16:00:00.000Z",
  "timezone": "America/New_York",
  "description": "Quarterly company update and Q&A"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Event display name |
| `templateId` | string | Yes | Template to use (see section 8) |
| `startDate` | string | Yes | ISO 8601 start date |
| `endDate` | string | Yes | ISO 8601 end date |
| `timezone` | string | Yes | IANA timezone (e.g., `America/New_York`, `Europe/London`) |
| `description` | string | No | Event description |

Set `doorsOpenDate` via `events/update` after the event is created.

**Resilience:** If `events/create` returns HTTP 500, the event may still have been created server-side. Verify by calling `events/list` with a `searchTerm` matching your event name.

**Response example:**

```json
{
  "id": 56789,
  "name": "API Demo Webinar",
  "status": "draft",
  "templateId": "tm2000",
  "startDate": "2024-12-20T15:00:00.000Z",
  "endDate": "2024-12-20T16:00:00.000Z",
  "timezone": "America/New_York",
  "description": "Created via Events Platform API",
  "labels": [],
  "createdAt": "2024-11-01T10:00:00.000Z",
  "updatedAt": "2024-11-01T10:00:00.000Z"
}
```

The response contains the full event object. Save the `id` field (integer) for subsequent API calls.

```bash
curl -X POST "$KALTURA_EVENTS_API_URL/events/create" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Demo Webinar",
    "templateId": "tm2000",
    "startDate": "2024-12-20T15:00:00.000Z",
    "endDate": "2024-12-20T16:00:00.000Z",
    "timezone": "America/New_York",
    "description": "Created via Events Platform API"
  }'
```

Save the `id` from the response as `EVENT_ID`.

### 5.2 List Events

```
POST /api/v1/events/list
```

All parameters are optional per the API specification. To reliably retrieve all events, include a single-space `searchTerm` filter which matches all event names.

```json
{
  "filter": {
    "searchTerm": "town hall",
    "labels": ["quarterly"],
    "idIn": [12345, 67890]
  },
  "pager": {
    "offset": 0,
    "limit": 15
  },
  "orderBy": "-startDate"
}
```

| Filter Field | Type | Description |
|-------------|------|-------------|
| `searchTerm` | string | Free-text search by event name |
| `labels` | array | Filter by label tags (matches events containing any listed label) |
| `idIn` | array | Filter by specific event IDs (integers) |
| `templateIdIn` | array | Filter by template IDs (e.g., `["tm0000", "tm2000"]`) |
| `startDateGreaterThanOrEqual` | string | ISO 8601 — events starting on or after this date |
| `startDateLessOrEqualThan` | string | ISO 8601 — events starting on or before this date |
| `endDateGreaterThanOrEqual` | string | ISO 8601 — events ending on or after this date |
| `endDateLessOrEqualThan` | string | ISO 8601 — events ending on or before this date |

| Pager Field | Type | Default | Description |
|-------------|------|---------|-------------|
| `offset` | int | 0 | Number of results to skip |
| `limit` | int | 5 | Max results to return (max 15) |

| orderBy | Description |
|---------|-------------|
| `+name` / `-name` | Alphabetical by event name |
| `+createdAt` / `-createdAt` | By creation date |
| `+startDate` / `-startDate` | By event start date |

**Response:**

```json
{
  "events": [
    {
      "id": 56789,
      "name": "Q4 All-Hands Town Hall",
      "startDate": "2024-12-15T14:00:00.000Z",
      "endDate": "2024-12-15T16:00:00.000Z",
      "timezone": "America/New_York",
      "labels": ["quarterly"],
      "publicDomain": "https://1234567-5.events.kaltura.com",
      "templateId": "tm2000",
      "createdAt": "2024-11-01T10:00:00.000Z"
    }
  ],
  "totalCount": 1,
  "status": "ok"
}
```

List all events sorted by start date (descending):

```bash
curl -X POST "$KALTURA_EVENTS_API_URL/events/list" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"searchTerm": " "},
    "orderBy": "-startDate",
    "pager": {"offset": 0, "limit": 15}
  }'
```

Filter by search term:

```bash
curl -X POST "$KALTURA_EVENTS_API_URL/events/list" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"searchTerm": "town hall"},
    "pager": {"offset": 0, "limit": 10}
  }'
```

### 5.3 Update an Event

```
POST /api/v1/events/update
```

```json
{
  "id": 12345,
  "name": "Updated Event Name",
  "description": "Updated description",
  "startDate": "2024-12-15T15:00:00.000Z",
  "endDate": "2024-12-15T17:00:00.000Z",
  "doorsOpenDate": "2024-12-15T14:45:00.000Z",
  "timezone": "America/New_York",
  "labels": ["updated", "quarterly"],
  "logoEntryId": "0_abc123",
  "bannerEntryId": "0_def456"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | **Required.** Event ID to update |
| `name` | string | Updated name |
| `description` | string | Updated description |
| `startDate` | string | Updated start date |
| `endDate` | string | Updated end date |
| `doorsOpenDate` | string | Updated doors-open time |
| `timezone` | string | Updated timezone |
| `labels` | array | Updated labels/tags |
| `logoEntryId` | string | Kaltura entry ID for event logo image |
| `bannerEntryId` | string | Kaltura entry ID for event banner image |

Only include the fields you want to change. Fields not included remain unchanged.

**Response:** The updated event object.

```bash
curl -X POST "$KALTURA_EVENTS_API_URL/events/update" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": $EVENT_ID,
    \"name\": \"Updated Event Name\",
    \"labels\": [\"updated\", \"quarterly\"]
  }"
```

### 5.4 Delete an Event

```
POST /api/v1/events/delete
```

```json
{
  "id": 12345
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | integer | Yes | Event ID to delete |

Permanently deletes the event and all its sessions. Returns an empty response on success (HTTP 200).

**Category cleanup:** The Events Platform auto-creates root categories for each event (e.g., `{eventId}EP{hex}`, `ep_agenda_{eventId}`, `ep_private_{eventId}`). Deleting an event removes the event record and its sessions, but does **not** cascade-delete these categories. Clean them up separately via `category.delete` using the category IDs, or list root categories filtered by the event ID pattern.

```bash
curl -X POST "$KALTURA_EVENTS_API_URL/events/delete" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{\"id\": $EVENT_ID}"
```

### 5.5 Duplicate an Event

```
POST /api/v1/events/duplicate
```

```json
{
  "sourceEventId": 12345
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sourceEventId` | integer | Yes | The numeric ID of the event to duplicate |

Creates a copy of the event with all its configuration. Returns a job object with a `jobId`.

**Response:**
```json
{
  "jobId": "job_xyz789"
}
```

### 5.6 Check Duplication Status

```
POST /api/v1/events/duplicateStatus
```

```json
{
  "jobId": "job_xyz789"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `jobId` | string | Yes | Job ID returned by `events/duplicate` |

**Response:** Contains `status` (see table below) and, on completion, `eventId` with the new event's integer ID.

| Status | Description |
|--------|-------------|
| `completed` | Duplication finished successfully |
| `failed` | Duplication failed |
| `paused` | Job paused |
| `repeat` | Job being retried |
| `wait` | Job queued, waiting to start |
| `unknown` | Status cannot be determined |

```bash
# Start duplication
curl -X POST "$KALTURA_EVENTS_API_URL/events/duplicate" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"sourceEventId": 12345}'
# Save the "jobId" from the response as JOB_ID

# Poll for completion
curl -X POST "$KALTURA_EVENTS_API_URL/events/duplicateStatus" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d "{\"jobId\": \"$JOB_ID\"}"
# Repeat until "status" is "completed" or "failed"
```