score_remove
WriteTake one score off the game's leaderboard (score_id from leaderboard_read), for example a cheated or test score.
/api/agent/scores/removeBehavior
Take one score off the game's leaderboard (score_id from leaderboard_read), for example a cheated or test score. reason is for the creator and operators, never shown to players. The score stays recorded, so its round cannot be posted again; restore true puts back a score removed this way (one rejected by replay verification stays off). On a game with boards, score_id is an entry's from leaderboard_read, or give board and player (with split and period as leaderboard_read takes them, and preview true for the preview builds' boards) instead; a removed entry stays off until restored or until that player posts to the board again, which starts the entry over.
To stop a player posting at all, use player_ban. Removing someone's score is the creator's decision: confirm it with them first.
Input parameters
score_idOptionalstring- Min. length: 10
- Max. length: 64
reasonRequiredstring- Max. length: 200
restoreOptionalbooleanboardOptionalstring- Pattern: ^[a-z][a-z0-9-]{0,31}$
playerOptionalstring- Min. length: 3
- Max. length: 64
splitOptionalstring- Min. length: 1
- Max. length: 40
periodOptionalstring- Min. length: 3
- Max. length: 10
previewOptionalbooleanThe 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": {
"score_id": {
"type": "string",
"minLength": 10,
"maxLength": 64
},
"reason": {
"type": "string",
"maxLength": 200
},
"restore": {
"type": "boolean"
},
"board": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,31}$"
},
"player": {
"type": "string",
"minLength": 3,
"maxLength": 64
},
"split": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"period": {
"type": "string",
"minLength": 3,
"maxLength": 10
},
"preview": {
"type": "boolean"
}
},
"required": [
"reason"
],
"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.