Skip to main content
View as Markdown

API Request Structure - Getting Started

API Request Structure​

Every Kaltura API v3 call follows this pattern:

POST \{BASE_URL\}/service/\{SERVICE_NAME\}/action/\{ACTION_NAME\}

For example, listing media entries:

curl -X POST "$KALTURA_SERVICE_URL/service/media/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1"

Key conventions:

  • HTTP method: Always POST (even for read operations)
  • Content-Type: application/x-www-form-urlencoded (default) or application/json — the API v3 backend accepts both formats
  • Response format: Add format=1 to get JSON (format values: 1=JSON, 2=XML, 3=PHP, 9=JSONP).
  • Authentication: Pass ks= as a form parameter or JSON field in every request
  • Boolean parameters: Many filter fields use KalturaNullableBoolean: -1=null/ignore, 0=false, 1=true. Pass integers, not string "true"/"false".

Form-encoded parameters use bracket notation for nested fields:

curl -X POST "$KALTURA_SERVICE_URL/service/media/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "filter[objectType]=KalturaMediaEntryFilter" \
  -d "filter[nameLike]=demo" \
  -d "filter[mediaTypeEqual]=1" \
  -d "pager[pageSize]=10" \
  -d "pager[pageIndex]=1"

JSON bodies use nested objects directly:

curl -X POST "$KALTURA_SERVICE_URL/service/media/action/list" \
  -H "Content-Type: application/json" \
  -d '{
    "ks": "'$KALTURA_KS'",
    "format": 1,
    "filter": {
      "objectType": "KalturaMediaEntryFilter",
      "nameLike": "demo",
      "mediaTypeEqual": 1
    },
    "pager": { "pageSize": 10, "pageIndex": 1 }
  }'

Both formats produce identical results. These guides use form-encoded curl examples since they are easier for agents to adapt to any language, but JSON is equally supported.

The objectType field tells the server which object class to instantiate. Include it when the API accepts multiple object types for a parameter.

Newer platform services (Events Platform, Agents Manager, Conversational AI) have their own dedicated REST endpoints with Bearer or KS auth headers. Each guide specifies its endpoint and auth method.