Skip to content

Kaltura API Guides — Project Standards

This project produces Kaltura API documentation for AI agents building applications on Kaltura. Every guide must be accurate, tested against the live API, and written so an agent can follow it to build integrations safely, securely, and efficiently.

Repository Structure

Kaltura API Guides/
├── AGENTS.md                              # This file
├── PLAN.md                                # Master roadmap and API landscape
├── GUIDE_MAP.md                           # Dependency graph, reading order, decision tree
├── KALTURA_API_GETTING_STARTED.md         # API structure, first call, multirequest, errors
├── KALTURA_SESSION_GUIDE.md               # KS generation and management
├── KALTURA_APPTOKENS_API.md               # Secure auth with AppTokens
├── KALTURA_ESEARCH_API.md                 # Unified search
├── KALTURA_UPLOAD_AND_DELIVERY_API.md     # Upload, ingest, playback URLs
├── KALTURA_PLAYER_EMBED_GUIDE.md          # Player v7 embed (iframe + JS)
├── KALTURA_REACH_API.md                   # Enrichment services marketplace: 22+ services, machine + human, 80+ languages
├── KALTURA_AGENTS_MANAGER_API.md          # Automated content processing
├── KALTURA_AI_GENIE_API.md                # Conversational AI search
├── KALTURA_EVENTS_PLATFORM_API.md         # Virtual events
├── KALTURA_MULTI_STREAM_API.md            # Dual/multi-screen entries
├── KALTURA_APP_REGISTRY_API.md            # Application instance registry
├── KALTURA_USER_PROFILE_API.md            # Per-app user profiles & attendance
├── KALTURA_MESSAGING_API.md               # Template-based email messaging
├── KALTURA_WEBHOOKS_API.md                # HTTP webhooks & email via Messaging Service
├── KALTURA_USER_MANAGEMENT_API.md         # User CRUD, roles (RBAC), groups
├── KALTURA_AUTH_BROKER_API.md             # SSO/SAML auth profiles, app subscriptions
├── KALTURA_CATEGORIES_AND_ACCESS_CONTROL_API.md  # Categories, membership, access control
├── KALTURA_CUSTOM_METADATA_API.md         # XSD schemas, metadata profiles, XSLT transforms
├── KALTURA_CAPTIONS_AND_TRANSCRIPTS_API.md # Caption assets, transcripts, multi-language, REACH
├── KALTURA_ANALYTICS_REPORTS_API.md       # Reports, CSV exports, live analytics, stream health
├── KALTURA_ANALYTICS_EVENTS_COLLECTION_API.md  # Playback & engagement event collection
├── KALTURA_GAMIFICATION_API.md            # Leaderboards, badges, certificates, lead scoring
├── KALTURA_DISTRIBUTION_API.md            # Content distribution connectors (push to YouTube/FB/FTP)
├── KALTURA_SYNDICATION_API.md             # Syndication feeds (RSS/MRSS/iTunes/Roku pull)
├── KALTURA_EXPERIENCE_COMPONENTS_API.md   # Experience components index (links to standalone guides)
├── KALTURA_EXPRESS_RECORDER_API.md        # Browser-based WebRTC recording
├── KALTURA_CAPTIONS_EDITOR_API.md         # Interactive caption editing with video/waveform sync
├── KALTURA_CONVERSATIONAL_AVATAR_API.md   # AI-powered conversational video avatar embed
├── KALTURA_CNC_API.md                     # Chat & Collaborate (real-time chat, Q&A, polls)
├── KALTURA_GENIE_WIDGET_API.md            # Conversational AI search widget
├── KALTURA_MEDIA_MANAGER_API.md           # Browsable media library (select, upload, manage entries)
├── KALTURA_CONTENT_LAB_API.md             # AI content repurposing (summaries, chapters, clips, quizzes)
├── KALTURA_AGENTS_WIDGET_API.md           # Automated content-processing agent management UI
├── KALTURA_VOD_AVATAR_API.md              # Pre-recorded avatar video generation from scripts
├── KALTURA_ANALYTICS_EMBED_API.md         # Embeddable analytics dashboards via iframe
├── KALTURA_UNISPHERE_FRAMEWORK_API.md     # Unisphere micro-frontend framework (loader, workspace, services)
├── KALTURA_MULTI_ACCOUNT_MANAGEMENT_API.md # Multi-account management, cross-account analytics
├── KALTURA_MODERATION_API.md              # Content moderation: flagging, approve/reject, AI moderation via REACH
├── KALTURA_CUE_POINTS_API.md             # Cue points hub: temporal metadata concepts, base service, eSearch, protocols
├── KALTURA_QUIZ_API.md                   # Interactive video quizzes: questions, scoring, reports, IVQ plugin
├── KALTURA_CHAPTERS_AND_SLIDES_API.md    # Chapters, slides, timedThumbAsset workflow, navigation plugin
├── KALTURA_ANNOTATIONS_API.md            # Annotations, threaded replies, hotspots, searchableOnEntry
├── KALTURA_AD_CUE_POINTS_API.md          # VAST/VPAID ad insertion: pre-roll, mid-roll, overlay
├── KALTURA_CODE_CUE_POINTS_API.md        # Code markers, view-change, forceStop, event/session cue points
├── version.txt                            # Current version (managed by release-please)
├── release-please-config.json             # Release automation config
├── .release-please-manifest.json          # Version tracking for release-please
└── tests/                                 # Companion test scripts

Verification Commands

cd "Kaltura API Guides/tests"
python3 test_multi_stream_api.py           # Run a specific test
python3 test_multi_stream_api.py --keep    # Preserve entries for browser testing
for f in test_*.py; do echo "=== $f ===" && python3 "$f" && echo "PASS" || echo "FAIL"; done

All tests must pass against the live Kaltura API before a guide is considered done. If a test fails, the guide is wrong — fix the guide, not the test.

Philosophy

  1. Positive framing only. Document what works and how to use it. State the correct approach directly — agents follow positive instructions more reliably than prohibitions.
  2. Language-agnostic. All API examples use curl with shell variables. Agents choose their own language.
  3. Live-tested. Every guide has a companion test script that validates documented behavior against the real API.
  4. Agent-first. Write for an AI agent that reads top-to-bottom and executes. Clear structure, explicit parameters, no ambiguity.
  5. Customer-accessible only. Document only API actions accessible to customer accounts. Verify every action against the live API with a standard customer KS. Exclude actions that return SERVICE_FORBIDDEN — these are internal/system actions. The disableentitlement KS privilege bypasses content entitlement checks; partner-level service restrictions remain in force regardless.
  6. One guide per service boundary. Each guide covers one cohesive API service or tightly-coupled service cluster. Two services belong in the same guide only if they share API actions, one depends on the other at the API level, or a developer using one always needs the other. Services that merely "relate to entries" (e.g., metadata and captions) are separate guides. When in doubt, split — standalone guides can cross-reference each other, but a bundled guide cannot be unbundled without losing coverage depth.
  7. Self-contained. Every guide must contain all the information an agent needs to build integrations. Inline all relevant external information directly in the guide. External links used during research are references for the guide author — keep them out of published guides.

Guide File Structure

Header Block (Lines 1-7)

# Kaltura [Service Name] [API/Guide]

[1-2 sentence description.]

**Base URL:** `https://...` (may differ by region/deployment)
**Auth:** [How to authenticate — KS param, Bearer header, etc.]
**Format:** [Request encoding and response format]

Required Sections

  • Prerequisites / Authentication — Kaltura account, KS requirements, auth method, required privileges
  • Numbered sections — # 1. Section Title (H1 with number), ## 1.1 Subsection for nesting
  • Error Handling — Common error codes and responses for that API. Agents must know what errors to expect and how to handle them.
  • Best Practices — Security, performance, and integration patterns specific to that API. Guide agents toward production-quality code.
  • Related Guides (final section) — Format: - **[Display Name](FILENAME.md)** — One-line description

curl Example Standards

Kaltura API v3 (form-encoded)

curl -X POST "$KALTURA_SERVICE_URL/service/{service}/action/{action}" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "param[key]=value"
  • Shell variables: $KALTURA_SERVICE_URL, $KALTURA_KS, $KALTURA_PARTNER_ID, $KALTURA_ENTRY_ID
  • Always include format=1 for JSON responses
  • One -d parameter per line with backslash continuation
  • The API v3 backend accepts both application/x-www-form-urlencoded and application/json bodies. Guides use form-encoded as the default (easier for agents to adapt), but JSON is equally supported.

Modern JSON APIs (Events Platform, Agents Manager, AI Genie)

curl -X POST "$KALTURA_BASE_URL/endpoint" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Auth header formats differ by API: - Events Platform & Agents Manager: Authorization: Bearer $KALTURA_KS - AI Genie: Authorization: KS $KALTURA_KS - API v3: KS as form parameter (-d "ks=$KALTURA_KS")

Writing Style

  • Positive framing. Write "Use UTC format for dates" instead of describing what fails. State what to do, then optionally state why.
  • Language-agnostic examples. Use curl for all server-side API calls. Exception: Guides for front-end components (Player embed, editor, Unisphere widgets) include JavaScript/HTML where the component's API is inherently browser-based.
  • Minimal commentary. Let API parameters and examples speak. Prose only when behavior is non-obvious.
  • Tables for structured data. Parameter lists, status codes, enum values.
  • Inline code for identifiers. Backticks for parameter names, values, IDs, env vars.
  • Emojis: Only when explicitly requested.
  • Acceptable URLs in guides: (a) Kaltura API/CDN endpoint URLs in curl examples and configuration, (b) example.com placeholder URLs in code samples, (c) cross-references to other guides using [Name](FILENAME.md) format. Inline all other external information directly. Source code repositories, reference implementations, and "learn more" links are research aids for the author — keep them out of published guides.
  • Trailing double spaces for line breaks. Lines within a paragraph that should render as separate visual lines must end with (two trailing spaces). Especially important in header blocks (Base URL / Auth / Format) and multi-line list items. Without them, GitHub and other renderers join lines into one paragraph.
  • Use "multi-account" terminology. Write "multi-account" or "parent-child account" when describing Kaltura's multi-account model. Explain concepts directly rather than using internal product names like "VPaaS."
  • Platform scale. Refer to the platform as having "100+ API services" and "a dozen client libraries" — not "80+" or other approximations.

Auth Patterns

API Auth Method KS Notes
API v3 (media, baseEntry, etc.) -d "ks=$KALTURA_KS" form param Admin KS with disableentitlement for full access
Events Platform Bearer $KALTURA_KS header KS must have userId set
Agents Manager Bearer $KALTURA_KS header Standard admin KS
AI Genie KS $KALTURA_KS header Standard admin KS
App Registry Bearer $KALTURA_KS header Admin KS with ADMIN_BASE permission
User Profile Bearer $KALTURA_KS header Admin KS with ADMIN_BASE permission
Messaging Bearer $KALTURA_KS header Admin KS (type=2)
Webhooks (Event Notifications) -d "ks=$KALTURA_KS" form param Admin KS with disableentitlement
Distribution & Syndication -d "ks=$KALTURA_KS" form param Admin KS with disableentitlement
Auth Broker KS $KALTURA_KS header Admin KS
Player embed KS in URL or JS config USER KS (type=0) for playback

Common Kaltura API Patterns

  • Entry statuses: -2 (ERROR_IMPORTING), -1 (ERROR_CONVERTING), 0 (IMPORT), 1 (PRECONVERT), 2 (READY), 3 (DELETED), 4 (PENDING), 5 (MODERATE), 6 (BLOCKED), 7 (NO_CONTENT)
  • Upload lifecycle: uploadToken.add → uploadToken.upload → media.add → media.addContent
  • Polling pattern: Check baseEntry.get for status=2 with interval/timeout
  • Cascade behavior: Deleting a parent entry cascades to children — use baseEntry.list with parentEntryIdEqual to discover children first
  • Search for child entries: Use parentEntryIdEqual filter to retrieve child entries (multi-stream, clip children). Default search returns root entries only.
  • Event IDs are integers (Events Platform) — pass as 12345, not "evt_abc123"
  • Cue point filter constraint: Every cuePoint.list / cuePoint.count call must include entryIdEqual, entryIdIn, idEqual, or idIn — calls without these return an error

Security & Compliance Guidance

Every guide must steer agents toward production-quality, secure integrations:

  1. Use AppTokens in production. Generate KS server-side via AppTokens with minimal privileges; rotate periodically. API secrets are permanent and cannot be regenerated or revoked — keep adminSecret on the server only. See KALTURA_APPTOKENS_API.md.
  2. Scope KS privileges. Use edit:entryId, sview:*, setrole:ROLE, iprestrict, urirestrict to limit what a session can access. Prefer USER KS (type=0) over ADMIN KS (type=2) whenever possible.
  3. Set KS expiry. Default to short-lived sessions (1-4 hours). Use AppToken session start for renewal rather than long-lived admin sessions.
  4. Generate KS server-side for mobile/client apps. Pass tokens to clients per-session at runtime. API secrets are permanent and unrevocable; KS tokens expire, breaking hardcoded binaries; and users can extract embedded credentials.
  5. Verify webhook signatures. Always validate HMAC signatures on incoming webhooks using SHA256(signing_secret + body). See KALTURA_WEBHOOKS_API.md section 5.
  6. Validate inputs at boundaries. Sanitize user-provided entry IDs, search terms, and metadata before passing to API calls.
  7. Use Kaltura's built-in capabilities. Prefer Kaltura REACH for enrichment services (captions, translation, moderation, and more), Agents Manager for automation, Messaging for emails, eSearch for content discovery, and Access Control for content protection — rather than building custom implementations.
  8. Handle errors gracefully. Every API call can fail — check for error responses, implement retries with backoff for transient failures, and log error codes for debugging.
  9. Protect content with Access Control. Use accessControlProfile to restrict content by IP, domain, geo, or scheduling rules rather than implementing custom access logic.
  10. Use CAN-SPAM compliant email. When sending emails via the Messaging API, always include unsubscribe links and respect opt-out preferences. See KALTURA_MESSAGING_API.md.

Leveraging Kaltura Capabilities

Agents building on Kaltura should use platform services rather than reimplementing:

Need Use Kaltura Service Guide
Content enrichment (any type) REACH API (22+ services, machine + human, 80+ languages) KALTURA_REACH_API.md
Captions, translation, dubbing REACH API (specific enrichment services) KALTURA_REACH_API.md
Content moderation (AI) REACH API (serviceFeature=15) + Moderation API KALTURA_MODERATION_API.md
Auto-process new uploads Agents Manager (trigger + action rules) KALTURA_AGENTS_MANAGER_API.md
Auto-process matching entries REACH Automation Rules (Boolean/category conditions) KALTURA_REACH_API.md
Content search eSearch API (full-text, facets, operators) KALTURA_ESEARCH_API.md
Conversational AI / Q&A AI Genie (RAG over video library) KALTURA_AI_GENIE_API.md
Video player embed Player v7 (iframe or JS SDK) KALTURA_PLAYER_EMBED_GUIDE.md
Email notifications Messaging API (templates, tracking, unsubscribe) KALTURA_MESSAGING_API.md
Event-driven webhooks Webhooks API (HTTP callbacks with HMAC signing) KALTURA_WEBHOOKS_API.md
Virtual events Events Platform API (sessions, speakers, templates) KALTURA_EVENTS_PLATFORM_API.md
Secure auth without secrets AppTokens (HMAC-based session start) KALTURA_APPTOKENS_API.md
Multi-camera / dual-screen Multi-Stream API (parent-child entries) KALTURA_MULTI_STREAM_API.md
User registration & attendance User Profile API (per-app profiles) KALTURA_USER_PROFILE_API.md
User provisioning & RBAC User Management API (users, roles, groups) KALTURA_USER_MANAGEMENT_API.md
SSO/SAML authentication Auth Broker API (IdP config, app subscriptions) KALTURA_AUTH_BROKER_API.md
Content organization Categories & Access Control (hierarchy, entitlement) KALTURA_CATEGORIES_AND_ACCESS_CONTROL_API.md
Custom metadata schemas Custom Metadata API (XSD schemas, appinfo, XSLT) KALTURA_CUSTOM_METADATA_API.md
Captions & transcripts Captions & Transcripts API (SRT/VTT/DFXP, REACH) KALTURA_CAPTIONS_AND_TRANSCRIPTS_API.md
Content distribution Distribution connectors (YouTube, Facebook, FTP, cross-Kaltura) KALTURA_DISTRIBUTION_API.md
Syndication feeds RSS/MRSS/iTunes/Roku feeds for external platforms KALTURA_SYNDICATION_API.md
Analytics reports Reports API (VOD/Live/Webcast metrics, CSV exports) KALTURA_ANALYTICS_REPORTS_API.md
Playback event tracking Stats collection (quartiles, seeks, buffer events) KALTURA_ANALYTICS_EVENTS_COLLECTION_API.md
Gamification & leaderboards Game Services (badges, certificates, rules engine) KALTURA_GAMIFICATION_API.md
Browser recording Express Recorder (WebRTC recording widget) KALTURA_EXPRESS_RECORDER_API.md
Caption editing Captions Editor (interactive editing with waveform) KALTURA_CAPTIONS_EDITOR_API.md
AI avatar conversations Conversational Avatar (iframe embed) KALTURA_CONVERSATIONAL_AVATAR_API.md
Real-time chat & Q&A Chat & Collaborate (event chat panels) KALTURA_CNC_API.md
AI search widget Genie Widget (conversational search) KALTURA_GENIE_WIDGET_API.md
Embedded analytics Embeddable Analytics (iframe dashboards) KALTURA_ANALYTICS_EMBED_API.md
Unisphere experiences Micro-frontend framework: loader, workspace, services, Media Manager KALTURA_UNISPHERE_FRAMEWORK_API.md
Multi-account management Parent-child accounts, cross-account analytics KALTURA_MULTI_ACCOUNT_MANAGEMENT_API.md
Cue points (overview & base service) Temporal metadata concepts, base CRUD, eSearch, protocols, bulk ops KALTURA_CUE_POINTS_API.md
Interactive video quizzes Quiz lifecycle, 8 question types, scoring, reports, IVQ plugin KALTURA_QUIZ_API.md
Chapters & slides Thumb cue points, timedThumbAsset workflow, navigation plugin KALTURA_CHAPTERS_AND_SLIDES_API.md
Annotations & hotspots Threaded annotations, hotspot pattern, searchableOnEntry KALTURA_ANNOTATIONS_API.md
Ad cue points VAST/VPAID ad insertion, pre-roll/mid-roll/overlay KALTURA_AD_CUE_POINTS_API.md
Code, event & session markers View-change commands, forceStop, broadcast events, sessions KALTURA_CODE_CUE_POINTS_API.md

Commit Messages & Versioning

This repository uses Conventional Commits. Every commit must follow this format:

<type>(<scope>): <description>
Type When Version bump
feat New guide, new major section Minor (6.2 → 6.3)
fix Correct wrong docs, fix tests Patch (6.2.0 → 6.2.1)
test Test-only changes None
docs Non-guide prose (README, CONTRIBUTING) None
chore Meta files, formatting None
ci Workflows, CI config None
refactor Restructure without content change None

Scope is optional — use the guide name or area: feat(moderation), fix(reach), test(esearch).

Breaking changes use !: feat!: restructure guide format → major bump.

Examples: 

feat(distribution): add Distribution API guide with 18 E2E tests
fix(reach): correct serviceFeature enum values for Immersive Agent
test(moderation): add reject side-effects verification
chore: update GUIDE_MAP.md and README test counts
ci: add commitlint and release-please workflows

Releases are automated via release-please. Push conventional commits → release-please opens a release PR → merge it to cut a release with auto-generated notes.

Adding a New Guide

  1. Research. Explore the API surface — endpoints, params, response schemas, auth. Test calls live.
  2. Verify accessibility. Test every action you plan to document with a customer account KS. Exclude actions that return SERVICE_FORBIDDEN or require partner-level permissions beyond standard KS privileges. disableentitlement bypasses content entitlement checks; partner-level service restrictions remain in force regardless.
  3. Write the guide. Follow the header block, numbered sections, curl examples, Related Guides structure.
  4. Create the test file. tests/test_{name}.py — cover every documented endpoint with real API calls.
  5. Run tests. All tests must pass against the live API. Tests must succeed with actual successful API responses — not by catching expected errors.
  6. Cross-reference. Add to Related Guides sections of existing guides where relevant. Link only to published guides in this repository.
  7. Update GUIDE_MAP.md. Add the new guide to the reading order tiers, dependency graph, and decision tree. Run python3 scripts/validate_guide_map.py to verify all cross-references are valid.
  8. Update PLAN.md. Add a row to the Completed Guides table.
  9. Commit with conventional format. Use feat(service-name): add Service Name API guide with N E2E tests. See Commit Messages & Versioning above.
  10. Iterate. If tests reveal undocumented behavior, update the guide to match reality.

Naming Convention

  • Guide: KALTURA_{SERVICE_NAME}_API.md (or _GUIDE.md for non-API docs)
  • Test: tests/test_{service_name}_api.py

Detailed Reference

See .claude/rules/ for detailed standards on specific topics:

  • test-standards.md — Test file structure, conventions, environment config, test helpers
  • player-testing.md — Browser-based player testing, Player v7 runtime API
  • common-pitfalls.md — Known issues and fixes encountered during guide development