Short Links - Integration

Kaltura Short Link API

Create, manage, and resolve shortened URLs for sharing Kaltura content — player embeds, preview pages, download links, or any URL. Short links provide clean, shareable URLs with built-in expiration and status control.

Base URL: $KALTURA_SERVICE_URL (e.g., https://www.kaltura.com/api_v3)
Auth: KS as form parameter (-d "ks=$KALTURA_KS")
Format: Form-encoded POST, format=1 for JSON responses

1. When to Use

Shareable preview URLs — Generate clean links for player preview pages, embed configurators, or content portals
Time-limited access — Create expiring links for temporary content access (e.g., review links, campaign URLs)
URL management — Track and manage all shortened URLs across your account with filtering by user, status, or date
Deep link shortening — Shorten complex Kaltura URLs (playManifest, embed codes, portal pages) into compact IDs

2. Prerequisites

A Kaltura account with Partner ID and Admin Secret
An admin KS (type=2) with disableentitlement privilege for full access
User KS (type=0) can create/list short links scoped to that user only

export KALTURA_SERVICE_URL="https://www.kaltura.com/api_v3"
export KALTURA_PARTNER_ID="your_partner_id"

KALTURA_KS=$(curl -s -X POST "$KALTURA_SERVICE_URL/service/session/action/start" \
  -d "secret=$KALTURA_ADMIN_SECRET" \
  -d "partnerId=$KALTURA_PARTNER_ID" \
  -d "type=2" \
  -d "userId=$KALTURA_USER_ID" \
  -d "privileges=disableentitlement" \
  -d "format=1" | tr -d '"')

3. Create a Short Link

POST /service/shortlink_shortlink/action/add

Parameter	Type	Required	Description
`shortLink[systemName]`	string	Yes	Identifier (min 3 chars) — use a descriptive name for programmatic lookups
`shortLink[fullUrl]`	string	Yes	Destination URL (min 10 chars) — the URL the short link redirects to
`shortLink[status]`	int	No	1=DISABLED, 2=ENABLED (default), 3=DELETED
`shortLink[expiresAt]`	int	No	Unix timestamp for expiration (0 or omit = never expires)
`shortLink[userId]`	string	No	Owner user ID (defaults to KS user)
`shortLink[name]`	string	No	Display name for the short link

curl -X POST "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "shortLink[objectType]=KalturaShortLink" \
  -d "shortLink[systemName]=PREVIEW-ENTRY-$KALTURA_ENTRY_ID" \
  -d "shortLink[fullUrl]=https://www.kaltura.com/index.php/extwidget/preview/partner_id/$KALTURA_PARTNER_ID/uiconf_id/$KALTURA_PLAYER_ID/entry_id/$KALTURA_ENTRY_ID/embed/dynamic" \
  -d "shortLink[status]=2"

Response:

{
  "id": "67mk41xj",
  "createdAt": 1778429631,
  "updatedAt": 1778429631,
  "partnerId": 1234567,
  "userId": "user@example.com",
  "systemName": "PREVIEW-ENTRY-1_abc123",
  "fullUrl": "https://www.kaltura.com/index.php/extwidget/preview/partner_id/1234567/uiconf_id/56732362/entry_id/1_abc123/embed/dynamic",
  "status": 2,
  "objectType": "KalturaShortLink"
}

The returned id is the short link identifier. The shareable URL is:

https://\{SERVICE_URL_HOST\}/tiny/{id}

For example: https://www.kaltura.com/tiny/67mk41xj

3.1 Create an Expiring Short Link

Set expiresAt to a Unix timestamp. The goto action will reject expired links with EXPIRED_SHORT_LINK.

EXPIRES_AT=$(date -d "+7 days" +%s 2>/dev/null || date -v+7d +%s)

curl -X POST "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "shortLink[objectType]=KalturaShortLink" \
  -d "shortLink[systemName]=TEMP-REVIEW-LINK" \
  -d "shortLink[fullUrl]=https://www.kaltura.com/index.php/extwidget/preview/partner_id/$KALTURA_PARTNER_ID/uiconf_id/$KALTURA_PLAYER_ID/entry_id/$KALTURA_ENTRY_ID/embed/dynamic" \
  -d "shortLink[status]=2" \
  -d "shortLink[expiresAt]=$EXPIRES_AT"

4. Resolve a Short Link

4.1 Browser Redirect (Primary Use)

Users access short links directly in the browser. The URL format is:

https://\{SERVICE_URL_HOST\}/tiny/\{SHORT_LINK_ID\}

This returns a 301 redirect to the API goto action, which then issues a 302 redirect to the fullUrl.

4.2 API `goto` Action

GET /service/shortlink_shortlink/action/goto/id/\{SHORT_LINK_ID\}

Parameter	Type	Required	Default	Description
`id`	string	Yes	—	Short link ID
`proxy`	boolean	No	false	Proxy the response content instead of redirecting

The goto action requires no KS — it is publicly accessible. It validates the link status and expiration before redirecting.

curl -s -o /dev/null -w "%{http_code} %{redirect_url}" \
  "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/goto/id/$SHORT_LINK_ID"

With proxy=true, the server fetches the destination URL and returns its content directly:

curl -s "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/goto/id/$SHORT_LINK_ID/proxy/true"

5. List Short Links

POST /service/shortlink_shortlink/action/list

Parameter	Type	Required	Description
`filter[statusEqual]`	int	No	Filter by status (1=DISABLED, 2=ENABLED, 3=DELETED)
`filter[statusIn]`	string	No	Comma-separated status values
`filter[userIdEqual]`	string	No	Filter by owner user ID
`filter[systemNameEqual]`	string	No	Filter by exact systemName
`filter[systemNameIn]`	string	No	Comma-separated systemName values
`filter[idEqual]`	string	No	Filter by exact ID
`filter[idIn]`	string	No	Comma-separated IDs
`filter[createdAtGreaterThanOrEqual]`	int	No	Created on or after (Unix timestamp)
`filter[createdAtLessThanOrEqual]`	int	No	Created on or before (Unix timestamp)
`filter[updatedAtGreaterThanOrEqual]`	int	No	Updated on or after (Unix timestamp)
`filter[updatedAtLessThanOrEqual]`	int	No	Updated on or before (Unix timestamp)
`filter[expiresAtGreaterThanOrEqual]`	int	No	Expires on or after (Unix timestamp)
`filter[expiresAtLessThanOrEqual]`	int	No	Expires on or before (Unix timestamp)
`filter[orderBy]`	string	No	Sort: `+createdAt`, `-createdAt`, `+updatedAt`, `-updatedAt`, `+expiresAt`, `-expiresAt`
`pager[pageSize]`	int	No	Results per page (default 30, max 500)
`pager[pageIndex]`	int	No	Page number (default 1)

curl -X POST "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "filter[statusEqual]=2" \
  -d "filter[orderBy]=-createdAt" \
  -d "pager[pageSize]=10" \
  -d "pager[pageIndex]=1"

Response:

{
  "objects": [
    {
      "id": "67mk41xj",
      "createdAt": 1778429631,
      "updatedAt": 1778429631,
      "partnerId": 1234567,
      "userId": "user@example.com",
      "systemName": "KMC-PREVIEW",
      "fullUrl": "https://www.kaltura.com/index.php/extwidget/preview/...",
      "status": 2,
      "objectType": "KalturaShortLink"
    }
  ],
  "totalCount": 70,
  "objectType": "KalturaShortLinkListResponse"
}

User KS restriction: With a user KS (type=0), the list is automatically scoped to that user's short links. An admin KS can list all short links or filter by any userIdEqual.

6. Update a Short Link

POST /service/shortlink_shortlink/action/update

Parameter	Type	Required	Description
`id`	string	Yes	Short link ID to update
`shortLink[fullUrl]`	string	No	New destination URL
`shortLink[status]`	int	No	New status (1=DISABLED, 2=ENABLED)
`shortLink[expiresAt]`	int	No	New expiration timestamp
`shortLink[name]`	string	No	New display name
`shortLink[systemName]`	string	No	New system name

curl -X POST "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/update" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$SHORT_LINK_ID" \
  -d "shortLink[objectType]=KalturaShortLink" \
  -d "shortLink[status]=1"

Setting status=1 (DISABLED) prevents the link from resolving without deleting it.

7. Delete a Short Link

POST /service/shortlink_shortlink/action/delete

Parameter	Type	Required	Description
`id`	string	Yes	Short link ID to delete

curl -X POST "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/delete" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$SHORT_LINK_ID"

This is a soft delete — sets status=3 (DELETED). The link stops resolving immediately.

Short links are also automatically deleted when their owner user is deleted from the system (cascade behavior).

8. Common Integration Patterns

The KMC (Rich Media CMS) creates short links for the embed preview page. The pattern:

Construct the full preview URL with partner ID, player uiconf, and entry ID
Create a short link with systemName=KMC-PREVIEW
Present the short URL (/tiny/{id}) to the user for sharing

FULL_URL="https://www.kaltura.com/index.php/extwidget/preview/partner_id/$KALTURA_PARTNER_ID/uiconf_id/$KALTURA_PLAYER_ID/entry_id/$KALTURA_ENTRY_ID/embed/dynamic"

curl -X POST "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "shortLink[objectType]=KalturaShortLink" \
  -d "shortLink[systemName]=KMC-PREVIEW" \
  -d "shortLink[fullUrl]=$FULL_URL" \
  -d "shortLink[status]=2"

Campaign Links with Expiration

Create time-limited links for marketing campaigns or review workflows:

EXPIRES_AT=$(date -d "+30 days" +%s 2>/dev/null || date -v+30d +%s)

curl -X POST "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "shortLink[objectType]=KalturaShortLink" \
  -d "shortLink[systemName]=CAMPAIGN-Q4-2025" \
  -d "shortLink[fullUrl]=https://your-portal.kaltura.com/media/entry_id/$KALTURA_ENTRY_ID" \
  -d "shortLink[name]=Q4 Campaign Video" \
  -d "shortLink[status]=2" \
  -d "shortLink[expiresAt]=$EXPIRES_AT"

Lookup by System Name

Use systemNameEqual filter to find short links by their programmatic identifier:

curl -X POST "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "filter[systemNameEqual]=CAMPAIGN-Q4-2025" \
  -d "filter[statusEqual]=2"

Bulk Cleanup of Expired Links

List and delete short links that have passed their expiration:

NOW=$(date +%s)

curl -X POST "$KALTURA_SERVICE_URL/service/shortlink_shortlink/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "filter[statusEqual]=2" \
  -d "filter[expiresAtLessThanOrEqual]=$NOW" \
  -d "filter[expiresAtGreaterThanOrEqual]=1" \
  -d "pager[pageSize]=500"

9. Error Handling

Error Code	Action	Description
`INVALID_OBJECT_ID`	get, update, delete, goto	Short link ID does not exist
`INVALID_SHORT_LINK`	goto	Link is DISABLED or DELETED
`EXPIRED_SHORT_LINK`	goto	Link has passed its `expiresAt` timestamp
`CANNOT_RETRIEVE_ANOTHER_USERS_SHORT_LINK`	list	User KS attempted to filter by a different user's links
`INVALID_USER_ID`	list	User KS with no `userId` set attempted to list
`PROPERTY_VALIDATION_MIN_LENGTH`	add	`systemName` < 3 chars or `fullUrl` < 10 chars
`MISSING_MANDATORY_PARAMETER`	add	`systemName` or `fullUrl` not provided

10. Best Practices

Use descriptive systemName values. Prefix with the context: KMC-PREVIEW, CAMPAIGN-{name}, SHARE-{entryId}. This enables filtering and bulk management.
Set expiresAt for temporary links. Review links, campaign URLs, and time-sensitive access should always have an expiration. Use 0 (or omit) only for permanent links.
Disable rather than delete. Set status=1 (DISABLED) to temporarily revoke access while preserving the link for potential reactivation.
Use admin KS for cross-user management. User KS can only see that user's short links. Use admin KS with disableentitlement for full account visibility.
The goto action is public. It requires no authentication — treat short link IDs as semi-public identifiers. For sensitive content, rely on the destination URL's own access control (KS in player embed, access control profiles).
Store the id for programmatic access. The short URL format is https://{host}/tiny/{id}. Construct it client-side after creating the link.

Player Embed Guide — Generate embed/preview URLs to shorten
Session (KS) Guide — KS generation for short link API access
AppTokens API — Secure server-side auth for production short link services

Kaltura Short Link API​

1. When to Use​

2. Prerequisites​

3. Create a Short Link​

3.1 Create an Expiring Short Link​

4. Resolve a Short Link​

4.1 Browser Redirect (Primary Use)​

4.2 API goto Action​

5. List Short Links​

6. Update a Short Link​

7. Delete a Short Link​

8. Common Integration Patterns​

Preview and Share Links​

Campaign Links with Expiration​

Lookup by System Name​

Bulk Cleanup of Expired Links​

9. Error Handling​

10. Best Practices​

11. Related Guides​