---
title: API Request Structure
url: https://docs.kaltura.com/docs/getting-started/general/api-request-structure
---

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

```bash
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:

```bash
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:

```bash
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.