leaderboards_configure
WriteDeclare the game's leaderboards.
/api/agent/leaderboards/configureBehavior
Declare the game's leaderboards. Read the looping-leaderboards skill first: whether the game should have a board at all, and which settings fit it. Give only the boards to change; null removes one and clears its entries. Each board: title; order high (more is better, the default) or low (times, strokes); keep best (each player's best, the default), latest (the player's current value: a level, a rating) or total (the sum of every post: lifetime wins, kills, gold earned); period all (the default), day, week or month (resets at UTC midnight; the previous period stays readable); trust any (the default: player-reported posts, marked as such) or verified (only an authoritative room's rules.js result and replay-verified rounds post to it); split, a key such as "track" or "level" for one board per value (up to 200 values), with splits listing its values ("monaco", "spa"; added to those it has): a post or a round from the game names only a listed value, while an authoritative room's result may open a new one; format number, time_ms or points (how the game page displays values); shown false keeps it off the game page (the game still reads it).
order, keep, period, trust and split are fixed once a board exists. primary names the board an older SDK's finishRound(score) posts to and leaderboard() reads; a lone board is primary by itself, and with several, name one whenever none is. Up to 16 boards; names are 1-32 lowercase letters, digits and dashes starting with a letter. Boards are free. Once a game has any board, only what it posts to a board is stored: a match stores only what its rules.js result() returns in boards, so change rules.js in the same build.
Propose the boards to the creator in one yes-or-no sentence before calling this.
Input parameters
boardsRequiredobjectNested schema
{
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,31}$"
},
"additionalProperties": {
"anyOf": [
{
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"order": {
"type": "string",
"enum": [
"high",
"low"
]
},
"keep": {
"type": "string",
"enum": [
"best",
"latest",
"total"
]
},
"period": {
"type": "string",
"enum": [
"all",
"day",
"week",
"month"
]
},
"trust": {
"type": "string",
"enum": [
"any",
"verified"
]
},
"split": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z][a-z0-9_-]{0,31}$"
},
{
"type": "null"
}
]
},
"splits": {
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$"
}
},
"format": {
"type": "string",
"enum": [
"number",
"time_ms",
"points"
]
},
"shown": {
"type": "boolean"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
}primaryOptionalstring- Pattern: ^[a-z][a-z0-9-]{0,31}$
The descriptions above include conditional requirements. The full schema below shows structural validation; runtime checks also apply.
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"boards": {
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,31}$"
},
"additionalProperties": {
"anyOf": [
{
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"order": {
"type": "string",
"enum": [
"high",
"low"
]
},
"keep": {
"type": "string",
"enum": [
"best",
"latest",
"total"
]
},
"period": {
"type": "string",
"enum": [
"all",
"day",
"week",
"month"
]
},
"trust": {
"type": "string",
"enum": [
"any",
"verified"
]
},
"split": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z][a-z0-9_-]{0,31}$"
},
{
"type": "null"
}
]
},
"splits": {
"maxItems": 200,
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$"
}
},
"format": {
"type": "string",
"enum": [
"number",
"time_ms",
"points"
]
},
"shown": {
"type": "boolean"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"primary": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,31}$"
}
},
"required": [
"boards"
],
"additionalProperties": false
}Use its name in your connected MCP client. For the HTTP API, the route is relative to your Convex site URL and requires your agent key as a bearer token. Keep the key on the agent side, outside a game build.