Search docs ⌘K
esc
Type to search across all documentation pages
Ranking

Ranking

Narrow ranking primitives for caller-owned collections, item embeddings, signal logs, ranked results, and related-item lookups. The surface stays intentionally focused on ranking and affinity, not campaign orchestration or merchandising rules.

Scope: This is not a full recommender system product. You still own experiments, promotions, checkout rules, and application-specific ranking policy.

Create Ranking Collection

POST
/infra/decisioning/ranking/collections
ranking:write

Create a caller-owned collection for ranking and recommendation primitives.

curl
curl -X POST https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"example"}'
json — 200 OK
{ "status": "ok" }
typescript
const collection = await ss.infra.decisioning.ranking.createCollection({ name: 'products', strategy_default: 'hybrid', embedding_model: 'workers-ai:bge-m3' })
  1. Open Dashboard → Decisioning and select your project
  2. Go to the Ranking workspace
  3. Create the collection from the workspace rail, pick the default ranking strategy, and immediately pin it as the active collection.
Body field
Type
Description
name required
string
1–120 chars
description
mixed
strategy_default
string
values: behavioral, semantic, hybrid
embedding_model
mixed
metadata_schema
mixed
Error responses
400 Bad request
401 Unauthorized
402 Insufficient tokens
403 Forbidden
409 Conflict
429 Rate limited

List Ranking Collections

GET
/infra/decisioning/ranking/collections
ranking:read

List ranking collections for the active project.

curl
curl https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const { collections } = await ss.infra.decisioning.ranking.listCollections()
  1. Open Dashboard → Decisioning and select your project
  2. Go to the Ranking workspace
  3. Use the workspace rail to browse saved collections for the active project and switch the selected collection before running any operators.
Error responses
401 Unauthorized
403 Forbidden
429 Rate limited

Get Ranking Collection

GET
/infra/decisioning/ranking/collections/{collection_id}
ranking:read

Get one ranking collection definition.

curl
curl https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections/{collection_id} \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const collection = await ss.infra.decisioning.ranking.getCollection('rcol_123')
  1. Open Dashboard → API Console and select your project
  2. Choose GET /infra/decisioning/ranking/collections/{collection_id} from the route list
  3. Fill in the JSON body or Storage references, then send the request and inspect the response directly in the console
Path param
Type
Description
collection_id required
string
Error responses
401 Unauthorized
403 Forbidden
404 Not found
429 Rate limited

Update Ranking Collection

PATCH
/infra/decisioning/ranking/collections/{collection_id}
ranking:write

Update mutable ranking collection fields.

curl
curl -X PATCH https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections/{collection_id} \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'
json — 200 OK
{ "status": "ok" }
typescript
const collection = await ss.infra.decisioning.ranking.updateCollection('rcol_123', { description: 'Product affinity workspace' })
  1. Open Dashboard → API Console and select your project
  2. Choose PATCH /infra/decisioning/ranking/collections/{collection_id} from the route list
  3. Fill in the JSON body or Storage references, then send the request and inspect the response directly in the console
Path param
Type
Description
collection_id required
string
Body field
Type
Description
name
string
1–120 chars
description
mixed
strategy_default
string
values: behavioral, semantic, hybrid
embedding_model
mixed
metadata_schema
mixed
Error responses
400 Bad request
401 Unauthorized
402 Insufficient tokens
403 Forbidden
404 Not found
429 Rate limited

Delete Ranking Collection

DELETE
/infra/decisioning/ranking/collections/{collection_id}
ranking:write

Delete a ranking collection and its stored items and signals.

curl
curl -X DELETE https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections/{collection_id} \
  -H "Authorization: Bearer sk_live_..."
typescript
await ss.infra.decisioning.ranking.deleteCollection('rcol_123')
  1. Open Dashboard → API Console and select your project
  2. Choose DELETE /infra/decisioning/ranking/collections/{collection_id} from the route list
  3. Fill in the JSON body or Storage references, then send the request and inspect the response directly in the console
Path param
Type
Description
collection_id required
string
Error responses
401 Unauthorized
402 Insufficient tokens
403 Forbidden
404 Not found
429 Rate limited

Upsert Ranking Items

POST
/infra/decisioning/ranking/collections/{collection_id}/items/upsert
ranking:write

Upsert caller-owned items into a ranking collection, with optional auto-embedding from item text.

curl
curl -X POST https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections/{collection_id}/items/upsert \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"items":[]}'
json — 200 OK
{ "status": "ok" }
typescript
await ss.infra.decisioning.ranking.upsertItems('rcol_123', { auto_embed: true, items: [{ id: 'sku_123', title: 'Trail Jacket', text: 'Waterproof shell with breathable lining', metadata: { brand: 'Northline' } }] })
  1. Open Dashboard → Decisioning and select your project
  2. Go to the Ranking workspace
  3. Select the collection, paste the item-upsert JSON into the seed card, and run it to create or refresh item vectors and metadata.
Path param
Type
Description
collection_id required
string
Body field
Type
Description
auto_embed
boolean
default true
items required
array
1–100 items
Error responses
400 Bad request
401 Unauthorized
402 Insufficient tokens
403 Forbidden
404 Not found
429 Rate limited

List Ranking Items

GET
/infra/decisioning/ranking/collections/{collection_id}/items
ranking:read

List caller-owned items stored in a ranking collection.

curl
curl https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections/{collection_id}/items \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const { items } = await ss.infra.decisioning.ranking.listItems('rcol_123')
  1. Open Dashboard → API Console and select your project
  2. Choose GET /infra/decisioning/ranking/collections/{collection_id}/items from the route list
  3. Fill in the JSON body or Storage references, then send the request and inspect the response directly in the console
Path param
Type
Description
collection_id required
string
Error responses
401 Unauthorized
403 Forbidden
404 Not found
429 Rate limited

Get Ranking Item

GET
/infra/decisioning/ranking/collections/{collection_id}/items/{item_id}
ranking:read

Get one caller-owned item stored in a ranking collection.

curl
curl https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections/{collection_id}/items/{item_id} \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const item = await ss.infra.decisioning.ranking.getItem('rcol_123', 'sku_123')
  1. Open Dashboard → API Console and select your project
  2. Choose GET /infra/decisioning/ranking/collections/{collection_id}/items/{item_id} from the route list
  3. Fill in the JSON body or Storage references, then send the request and inspect the response directly in the console
Path param
Type
Description
collection_id required
string
item_id required
string
Error responses
401 Unauthorized
403 Forbidden
404 Not found
429 Rate limited

Delete Ranking Item

DELETE
/infra/decisioning/ranking/collections/{collection_id}/items/{item_id}
ranking:write

Delete one item from a ranking collection.

curl
curl -X DELETE https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections/{collection_id}/items/{item_id} \
  -H "Authorization: Bearer sk_live_..."
typescript
await ss.infra.decisioning.ranking.deleteItem('rcol_123', 'sku_123')
  1. Open Dashboard → API Console and select your project
  2. Choose DELETE /infra/decisioning/ranking/collections/{collection_id}/items/{item_id} from the route list
  3. Fill in the JSON body or Storage references, then send the request and inspect the response directly in the console
Path param
Type
Description
collection_id required
string
item_id required
string
Error responses
401 Unauthorized
402 Insufficient tokens
403 Forbidden
404 Not found
429 Rate limited

Ingest Ranking Signals

POST
/infra/decisioning/ranking/collections/{collection_id}/signals/batch
ranking:write

Record caller-owned subject-item signals for ranking and related-item queries.

curl
curl -X POST https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections/{collection_id}/signals/batch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"signals":[]}'
json — 200 OK
{ "status": "ok" }
typescript
await ss.infra.decisioning.ranking.ingestSignals('rcol_123', { signals: [{ subject_id: 'user_123', item_id: 'sku_123', event: 'view', weight: 1 }] })
  1. Open Dashboard → Decisioning and select your project
  2. Go to the Ranking workspace
  3. Use the signal replay card to post a batch of subject-item events into the selected collection and watch the stats row update.
Path param
Type
Description
collection_id required
string
Body field
Type
Description
signals required
array
1–500 items
Error responses
400 Bad request
401 Unauthorized
402 Insufficient tokens
403 Forbidden
404 Not found
429 Rate limited

Rank Items

POST
/infra/decisioning/ranking/collections/{collection_id}/rank
ranking:read

Rank caller-owned candidate items for one subject using behavioral, semantic, or hybrid strategy.

curl
curl -X POST https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections/{collection_id}/rank \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"subject_id":"..."}'
json — 200 OK
{ "status": "ok" }
typescript
const result = await ss.infra.decisioning.ranking.rank('rcol_123', { subject_id: 'user_123', strategy: 'hybrid', limit: 8 })
  1. Open Dashboard → Decisioning and select your project
  2. Go to the Ranking workspace
  3. Paste the rank request JSON into the rank card to debug strategy choice, candidate filtering, and ranked output.
Path param
Type
Description
collection_id required
string
Body field
Type
Description
subject_id required
string
1–255 chars
strategy
string
values: behavioral, semantic, hybrid
limit
integer
range ≥1 .. ≤100default 10
candidate_ids
array
max 500 items
exclude_item_ids
array
max 500 items
Error responses
400 Bad request
401 Unauthorized
402 Insufficient tokens
403 Forbidden
404 Not found
429 Rate limited

Get Ranking Stats

GET
/infra/decisioning/ranking/collections/{collection_id}/stats
ranking:read

Get counts for items, signals, and unique subjects in a ranking collection.

curl
curl https://api.saasignal.saastemly.com/infra/decisioning/ranking/collections/{collection_id}/stats \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const stats = await ss.infra.decisioning.ranking.stats('rcol_123')
  1. Open Dashboard → Decisioning and select your project
  2. Go to the Ranking workspace
  3. Select a collection and read the stats strip to verify item, signal, and subject counts without leaving the workspace.
Path param
Type
Description
collection_id required
string
Error responses
401 Unauthorized
403 Forbidden
404 Not found
429 Rate limited