Feed

The Feed API delivers ranked, personalized video content to your users. It combines content filtering, ranking algorithms, and user preferences to serve optimal feeds.

Endpoints

Method	Endpoint	Description
`GET`	`/v1/feed`	Get personalized feed
`GET`	`/v1/feed/trending`	Get trending content
`GET`	`/v1/feed/topic/{topic}`	Get topic-specific feed
`POST`	`/v1/feed/refresh`	Force feed refresh

Get feed

Retrieves a personalized feed for the requesting user/device.

GET /v1/feed

Query parameters

limit

integer

default:20

Number of items to return (1-50).

cursor

string

Pagination cursor from previous response.

userId

string

User ID for personalization (optional with SDK).

deviceId

string

Device ID for anonymous users.

topics

string

Comma-separated topic filters.

excludeIds

string

Comma-separated content IDs to exclude.

geo

string

ISO country code for geo-relevance.

Example request

curl "https://api.shortkit.dev/v1/feed?limit=20&userId=user_123" \
  -H "Authorization: Bearer pk_live_your_publishable_key"

Response

{
  "data": [
    {
      "id": "cnt_abc123",
      "title": "Amazing Product Demo",
      "duration": 45.2,
      "aspectRatio": "9:16",
      "thumbnails": {
        "default": "https://cdn.shortkit.dev/thumbnails/cnt_abc123/default.jpg",
        "animated": "https://cdn.shortkit.dev/thumbnails/cnt_abc123/preview.webp"
      },
      "streamingUrl": "https://video.shortkit.dev/v1/streams/cnt_abc123/manifest.m3u8?token=...",
      "creator": {
        "id": "creator_xyz",
        "name": "Product Team",
        "avatar": "https://cdn.shortkit.dev/avatars/creator_xyz.jpg"
      },
      "engagement": {
        "views": 12500,
        "likes": 850,
        "shares": 120
      },
      "ranking": {
        "score": 0.85,
        "reasons": ["trending", "topic_match"]
      }
    }
  ],
  "meta": {
    "cursor": "eyJvZmZzZXQiOjIwfQ==",
    "hasMore": true,
    "feedId": "feed_abc123",
    "experimentId": "exp_xyz789"
  }
}

Feed item object

string

Content ID.

title

string

Content title.

duration

number

Duration in seconds.

aspectRatio

string

Aspect ratio (e.g., 9:16).

thumbnails

object

Thumbnail URLs by type.

streamingUrl

string

Signed HLS streaming URL.

creator

object

Creator information (if available).

engagement

object

Engagement metrics.

ranking

object

Ranking score and contributing factors.

Retrieves globally trending content.

GET /v1/feed/trending

Query parameters

limit

integer

default:20

Number of items (1-50).

period

string

default:"day"

Time period: hour, day, week.

geo

string

ISO country code for regional trending.

Example request

curl "https://api.shortkit.dev/v1/feed/trending?period=day&geo=US&limit=10" \
  -H "Authorization: Bearer pk_live_your_publishable_key"

Response

{
  "data": [
    {
      "id": "cnt_trend1",
      "title": "Viral Video",
      "duration": 30.0,
      "trending": {
        "rank": 1,
        "velocity": 2.5,
        "peakViews": 50000
      }
    }
  ],
  "meta": {
    "period": "day",
    "geo": "US",
    "updatedAt": "2024-02-04T12:00:00Z"
  }
}

Topic feed

Retrieves content for a specific topic.

GET /v1/feed/topic/{topic}

Path parameters

topic

string

required

Topic slug (e.g., technology, sports, music).

Query parameters

limit

integer

default:20

Number of items (1-50).

cursor

string

Pagination cursor.

sort

string

default:"ranked"

Sort order: ranked, recent, popular.

Example request

curl "https://api.shortkit.dev/v1/feed/topic/technology?limit=20&sort=ranked" \
  -H "Authorization: Bearer pk_live_your_publishable_key"

Refresh feed

Force a feed refresh, bypassing cache.

POST /v1/feed/refresh

Request body

userId

string

User ID to refresh feed for.

deviceId

string

Device ID to refresh feed for.

reason

string

Reason for refresh (for analytics).

Example request

curl -X POST https://api.shortkit.dev/v1/feed/refresh \
  -H "Authorization: Bearer pk_live_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "reason": "pull_to_refresh"
  }'

Response

{
  "data": {
    "refreshed": true,
    "feedId": "feed_new123"
  }
}

Ranking signals

The feed ranking algorithm considers these signals:

Signal	Weight	Description
Recency	0.25	Newer content scores higher
Engagement	0.20	Completion rate, likes, shares
Topic affinity	0.20	Match with user interests
Geo-relevance	0.15	Location-based scoring
Completion rate	0.10	Historical completion data
Creator affinity	0.10	Previous engagement with creator

Weights are configurable via the Ranking API.

Personalization

Anonymous users

For users without accounts, personalization uses:

Device ID for session continuity
Viewing history (last 7 days)
Implicit topic preferences
Geographic location

Identified users

For logged-in users, additional signals:

Explicit topic preferences
Cross-device history
Account-level engagement
Social graph (if available)

User identification

Link anonymous history to user accounts:

curl -X POST https://api.shortkit.dev/v1/users/identify \
  -H "Authorization: Bearer pk_live_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "device_abc123",
    "userId": "user_123"
  }'

SDK integration

SDKs handle feed fetching and pagination automatically:

iOS
Android
React Native

// Fetch feed
let feed = try await shortKit.fetchFeed(limit: 20)

// Paginate
if feed.hasMore {
    let nextPage = try await shortKit.fetchFeed(
        limit: 20,
        cursor: feed.cursor
    )
}

// Topic feed
let techFeed = try await shortKit.fetchFeed(
    topic: "technology",
    limit: 20
)

// Fetch feed
val feed = shortKit.fetchFeed(limit = 20)

// Paginate
if (feed.hasMore) {
    val nextPage = shortKit.fetchFeed(
        limit = 20,
        cursor = feed.cursor
    )
}

// Topic feed
val techFeed = shortKit.fetchFeed(
    topic = "technology",
    limit = 20
)

// Fetch feed
const { items, cursor, hasMore } = await shortkit.fetchFeed({ limit: 20 });

// Paginate
if (hasMore) {
  const nextPage = await shortkit.fetchFeed({ limit: 20, cursor });
}

// Topic feed
const techFeed = await shortkit.fetchFeed({
  topic: 'technology',
  limit: 20
});

Caching

Feed responses are cached for performance:

Feed Type	Cache Duration
Personalized	5 minutes
Trending	15 minutes
Topic	10 minutes

Use POST /v1/feed/refresh to bypass cache when needed.

A/B testing

Feed requests may be assigned to experiments:

{
  "meta": {
    "experimentId": "exp_xyz789",
    "variant": "treatment_a"
  }
}

Track experiment exposure when displaying feed items to ensure accurate analytics.

Overview

Content

Analytics

Configuration

Feed

Endpoints

Get feed

Query parameters

Example request

Response

Feed item object

Query parameters

Example request

Response

Topic feed

Path parameters

Query parameters

Example request

Refresh feed

Request body

Example request

Response

Ranking signals

Personalization

Anonymous users

Identified users

User identification

SDK integration

Caching

A/B testing

Next steps

Feed ranking

Events API

Overview

Content

Feed

Analytics

Configuration

​Endpoints

​Get feed

​Query parameters

​Example request

​Response

​Feed item object

​Trending feed

​Query parameters

​Example request

​Response

​Topic feed

​Path parameters

​Query parameters

​Example request

​Refresh feed

​Request body

​Example request

​Response

​Ranking signals

​Personalization

​Anonymous users

​Identified users

​User identification

​SDK integration

​Caching

​A/B testing

​Next steps

Feed ranking

Events API

Endpoints

Get feed

Query parameters

Example request

Response

Feed item object

Trending feed

Query parameters

Example request

Response

Topic feed

Path parameters

Query parameters

Example request

Refresh feed

Request body

Example request

Response

Ranking signals

Personalization

Anonymous users

Identified users

User identification

SDK integration

Caching

A/B testing

Next steps