Ranking

The Ranking API allows you to configure the feed ranking algorithm, including signal weights, boost rules, and content filters.

Endpoints

Method	Endpoint	Description
`GET`	`/v1/ranking/config`	Get ranking configuration
`PUT`	`/v1/ranking/config`	Update ranking configuration
`GET`	`/v1/ranking/rules`	List ranking rules
`POST`	`/v1/ranking/rules`	Create ranking rule
`PATCH`	`/v1/ranking/rules/{id}`	Update ranking rule
`DELETE`	`/v1/ranking/rules/{id}`	Delete ranking rule
`POST`	`/v1/ranking/preview`	Preview ranking changes

Get ranking configuration

Retrieve current ranking algorithm settings.

GET /v1/ranking/config

Example request

curl https://api.shortkit.dev/v1/ranking/config \
  -H "Authorization: Bearer sk_live_your_secret_key"

Response

{
  "data": {
    "weights": {
      "recency": 0.25,
      "engagement": 0.20,
      "topicAffinity": 0.20,
      "geoRelevance": 0.15,
      "completionRate": 0.10,
      "creatorAffinity": 0.10
    },
    "decayFunction": {
      "type": "exponential",
      "halfLife": 24
    },
    "diversitySettings": {
      "creatorDiversity": 0.3,
      "topicDiversity": 0.2
    },
    "coldStart": {
      "strategy": "popularity",
      "minDataPoints": 100
    }
  },
  "meta": {
    "version": 3,
    "updatedAt": "2024-02-01T12:00:00Z"
  }
}

Update ranking configuration

Modify ranking algorithm weights and settings.

PUT /v1/ranking/config

Request body

weights

object

Signal weights (must sum to 1.0).

Show properties

recency

number

Weight for content age (0-1).

engagement

number

Weight for engagement signals (0-1).

topicAffinity

number

Weight for topic match (0-1).

geoRelevance

number

Weight for geographic relevance (0-1).

completionRate

number

Weight for historical completion rate (0-1).

creatorAffinity

number

Weight for creator preference (0-1).

decayFunction

object

Time decay settings.

Show properties

type

string

Decay type: exponential, linear, step.

halfLife

number

Hours until content score is halved (exponential).

diversitySettings

object

Feed diversity controls.

Show properties

creatorDiversity

number

Penalty for consecutive same-creator content (0-1).

topicDiversity

number

Penalty for consecutive same-topic content (0-1).

Example request

curl -X PUT https://api.shortkit.dev/v1/ranking/config \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "weights": {
      "recency": 0.30,
      "engagement": 0.25,
      "topicAffinity": 0.15,
      "geoRelevance": 0.15,
      "completionRate": 0.10,
      "creatorAffinity": 0.05
    },
    "decayFunction": {
      "type": "exponential",
      "halfLife": 12
    }
  }'

Response

{
  "data": {
    "weights": {
      "recency": 0.30,
      "engagement": 0.25,
      "topicAffinity": 0.15,
      "geoRelevance": 0.15,
      "completionRate": 0.10,
      "creatorAffinity": 0.05
    },
    "decayFunction": {
      "type": "exponential",
      "halfLife": 12
    },
    "diversitySettings": {
      "creatorDiversity": 0.3,
      "topicDiversity": 0.2
    }
  },
  "meta": {
    "version": 4,
    "updatedAt": "2024-02-04T12:00:00Z"
  }
}

Ranking rules

Rules apply conditional modifications to content scores.

List rules

GET /v1/ranking/rules

Response

{
  "data": [
    {
      "id": "rule_abc123",
      "name": "Boost new creators",
      "condition": {
        "field": "creator.contentCount",
        "operator": "lt",
        "value": 10
      },
      "action": {
        "type": "boost",
        "value": 1.2
      },
      "priority": 10,
      "enabled": true
    },
    {
      "id": "rule_def456",
      "name": "Pin featured content",
      "condition": {
        "field": "tags",
        "operator": "contains",
        "value": "featured"
      },
      "action": {
        "type": "pin",
        "positions": [0, 5, 10]
      },
      "priority": 100,
      "enabled": true
    }
  ]
}

Create rule

POST /v1/ranking/rules

name

string

required

Rule name for identification.

condition

object

required

When to apply the rule.

Show properties

field

string

required

Field to evaluate.

operator

string

required

Comparison: eq, ne, gt, lt, gte, lte, contains, in.

value

any

required

Value to compare against.

action

object

required

What to do when condition matches.

Show properties

type

string

required

Action type: boost, suppress, pin, exclude.

value

number

Multiplier for boost/suppress (e.g., 1.5 = 50% boost).

positions

number[]

Positions for pin action.

priority

integer

default:0

Rule priority (higher = evaluated first).

enabled

boolean

default:true

Whether rule is active.

Example: Create boost rule

curl -X POST https://api.shortkit.dev/v1/ranking/rules \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Boost high-engagement content",
    "condition": {
      "field": "completionRate",
      "operator": "gte",
      "value": 0.7
    },
    "action": {
      "type": "boost",
      "value": 1.3
    },
    "priority": 50
  }'

Example: Create pin rule

curl -X POST https://api.shortkit.dev/v1/ranking/rules \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pin promotional content",
    "condition": {
      "field": "tags",
      "operator": "contains",
      "value": "promo"
    },
    "action": {
      "type": "pin",
      "positions": [0, 4]
    },
    "priority": 100,
    "enabled": true
  }'

Example: Create exclusion rule

curl -X POST https://api.shortkit.dev/v1/ranking/rules \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Exclude flagged content",
    "condition": {
      "field": "metadata.flagged",
      "operator": "eq",
      "value": true
    },
    "action": {
      "type": "exclude"
    },
    "priority": 1000
  }'

Update rule

PATCH /v1/ranking/rules/{id}

curl -X PATCH https://api.shortkit.dev/v1/ranking/rules/rule_abc123 \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Delete rule

DELETE /v1/ranking/rules/{id}

curl -X DELETE https://api.shortkit.dev/v1/ranking/rules/rule_abc123 \
  -H "Authorization: Bearer sk_live_your_secret_key"

Preview ranking changes

Test ranking configuration without applying it.

POST /v1/ranking/preview

Request body

config

object

Proposed ranking configuration.

rules

array

Proposed ranking rules.

userId

string

User to simulate feed for.

limit

integer

default:20

Number of items to return.

Example request

curl -X POST https://api.shortkit.dev/v1/ranking/preview \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "weights": {
        "recency": 0.40,
        "engagement": 0.30,
        "topicAffinity": 0.10,
        "geoRelevance": 0.10,
        "completionRate": 0.05,
        "creatorAffinity": 0.05
      }
    },
    "userId": "user_123",
    "limit": 10
  }'

Response

{
  "data": {
    "preview": [
      {
        "contentId": "cnt_abc123",
        "title": "Latest Tech Update",
        "currentPosition": 5,
        "previewPosition": 1,
        "scores": {
          "current": 0.72,
          "preview": 0.89
        },
        "signalBreakdown": {
          "recency": 0.38,
          "engagement": 0.28,
          "topicAffinity": 0.09
        }
      }
    ],
    "comparison": {
      "positionChanges": 8,
      "newInTop10": 3,
      "removedFromTop10": 2
    }
  }
}

Available condition fields

Field	Type	Description
`tags`	array	Content tags
`metadata.*`	any	Custom metadata fields
`creator.id`	string	Creator identifier
`creator.contentCount`	number	Creator’s total content
`duration`	number	Video duration in seconds
`completionRate`	number	Historical completion rate
`createdAt`	datetime	Creation timestamp
`publishedAt`	datetime	Publication timestamp

Action types

Type	Description	Parameters
`boost`	Multiply score	`value`: multiplier (e.g., 1.5)
`suppress`	Reduce score	`value`: multiplier (e.g., 0.5)
`pin`	Force to positions	`positions`: array of indices
`exclude`	Remove from feed	None

Overview

Content

Feed

Analytics

Configuration

Endpoints

Get ranking configuration

Example request

Response

Update ranking configuration

Request body

Example request

Response

Ranking rules

List rules

Response

Create rule

Example: Create boost rule

Example: Create pin rule

Example: Create exclusion rule

Update rule

Delete rule

Preview ranking changes

Request body

Example request

Response

Available condition fields

Action types

Next steps

Feed configuration

A/B testing

Overview

Content

Feed

Analytics

Configuration

​Endpoints

​Get ranking configuration

​Example request

​Response

​Update ranking configuration

​Request body

​Example request

​Response

​Ranking rules

​List rules

​Response

​Create rule

​Example: Create boost rule

​Example: Create pin rule

​Example: Create exclusion rule

​Update rule

​Delete rule

​Preview ranking changes

​Request body

​Example request

​Response

​Available condition fields

​Action types

​Next steps

Feed configuration

A/B testing

Endpoints

Get ranking configuration

Example request

Response

Update ranking configuration

Request body

Example request

Response

Ranking rules

List rules

Response

Create rule

Example: Create boost rule

Example: Create pin rule

Example: Create exclusion rule

Update rule

Delete rule

Preview ranking changes

Request body

Example request

Response

Available condition fields

Action types

Next steps