Sorted Sets API
Scored members for leaderboards, ranking, priorities, and time-based indexes
Sorted sets combine unique members with numeric scores, making them a good fit for leaderboards, ranking, priorities, and time-based indexes.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /[id]/zsets/add | Add scored members |
| POST | /[id]/zsets/remove | Remove members |
| GET | /[id]/zsets/score/{key}/{member} | Get a score |
| GET | /[id]/zsets/rank/{key}/{member} | Get a rank |
| GET | /[id]/zsets/range/{key} | Read a range |
| GET | /[id]/zsets/count/{key} | Count members |
| GET | /[id]/zsets/count-by-score/{key} | Count by score window |
| GET | /[id]/zsets/count-by-lex/{key} | Count by lex window |
| POST | /[id]/zsets/increment | Increment a score |
| POST | /[id]/zsets/pop-min | Pop lowest member(s) |
| POST | /[id]/zsets/pop-max | Pop highest member(s) |
| GET | /[id]/zsets/random/{key} | Read random member(s) |
| POST | /[id]/zsets/scores | Get multiple scores |
| POST | /[id]/zsets/union | Union-store |
| POST | /[id]/zsets/intersect | Intersect-store |
| POST | /[id]/zsets/diff | Diff-store |
| POST | /[id]/zsets/range/store | ZRANGESTORE |
| POST | /[id]/zsets/command | Execute allowed zset commands |
| POST | /[id]/zsets/{key}/command | Execute key-specific zset commands |
Examples
Add members
const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";
const response = await fetch(`${baseUrl}/${plateId}/zsets/add`, {
method: "POST",
headers: {
"Authorization": apiKey,
"Content-Type": "application/json"
},
body: JSON.stringify({
key: "leaderboard",
members: [
{ member: "player1", score: 100 },
{ member: "player2", score: 200 }
]
})
});
const data = await response.json();
console.log(data);Read a range with scores
const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";
const response = await fetch(`${baseUrl}/${plateId}/zsets/range/leaderboard?start=0&stop=9&with_scores=true`, {
headers: {
"Authorization": apiKey,
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data);Read reverse rank
const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";
const response = await fetch(`${baseUrl}/${plateId}/zsets/rank/leaderboard/player2?order=desc`, {
headers: {
"Authorization": apiKey,
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data);Increment a score
const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";
const response = await fetch(`${baseUrl}/${plateId}/zsets/increment`, {
method: "POST",
headers: {
"Authorization": apiKey,
"Content-Type": "application/json"
},
body: JSON.stringify({
key: "leaderboard",
member: "player1",
amount: 10
})
});
const data = await response.json();
console.log(data);Store a weighted union
const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";
const response = await fetch(`${baseUrl}/${plateId}/zsets/union`, {
method: "POST",
headers: {
"Authorization": apiKey,
"Content-Type": "application/json"
},
body: JSON.stringify({
destination: "combined",
keys: ["set:a", "set:b"],
weights: [1, 2],
aggregate: "sum"
})
});
const data = await response.json();
console.log(data);Command Compatibility
const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";
const response = await fetch(`${baseUrl}/${plateId}/zsets/command`, {
method: "POST",
headers: {
"Authorization": apiKey,
"Content-Type": "application/json"
},
body: JSON.stringify({
command: "ZADD",
args: ["leaderboard", 100, "player1", 200, "player2"]
})
});
const data = await response.json();
console.log(data);Command Endpoints
POST /[id]/zsets/command
Execute allowed sorted set commands across the plate.
Allowed Commands:
| Command | Description |
|---|---|
| ZADD | Add scored members |
| ZREM | Remove members |
| ZSCORE | Get score |
| ZRANK | Get rank (ascending) |
| ZREVRANK | Get rank (descending) |
| ZRANGE | Get members by rank |
| ZCARD | Get member count |
| ZCOUNT | Count by score |
| ZLEXCOUNT | Count by lex |
| ZINCRBY | Increment score |
| ZPOPMIN | Pop lowest |
| ZPOPMAX | Pop highest |
| ZRANDMEMBER | Random member |
| ZUNIONSTORE | Union and store |
| ZINTERSTORE | Intersection and store |
| ZDIFFSTORE | Difference and store |
| ZRANGESTORE | Range and store |
| ZMSCORE | Get multiple scores |
Query Parameters for ZRANGE:
start(optional): Start index (default: 0)stop(optional): End index (default: -1)order(optional):ascordescwith_scores(optional): Include scores in response
Query Parameters for ZRANDMEMBER:
count(optional): Number of memberswith_scores(optional): Include scores
POST /[id]/zsets/[key]/command
Execute allowed commands on a specific sorted set key.
Allowed Commands: Same as above.
Request:
const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";
const response = await fetch(`${baseUrl}/${plateId}/zsets/leaderboard/command`, {
method: "POST",
headers: {
"Authorization": apiKey,
"Content-Type": "application/json"
},
body: JSON.stringify({
command: "ZCARD"
})
});
const data = await response.json();
console.log(data);