Verify a quest task

POST /v1/player/quests/verify · for player session

Use it when the player presses the button of a task whose action is verify, as the Verify button does in Discord. The check reads a state: a role the member has, a badge, a balance, a follow on a platform. A quest the player has not started is started first, and the rules of Start a quest apply. The request needs the game loop. For the three conditions (game loop enabled for the game, member consent, server membership) and the error each returns, see What has to be true first.

Body parameters

Returns

When the last task is completed, the quest completes and grants its rewards: questCompleted is true and rewards contains:

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/player/quests/verify \
  -H "Authorization: Bearer $CEEJAY_PLAYER_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "questId": 12,
    "taskId": 45
  }'

The TypeScript example uses connect.hub.verifyQuestTask from the Connect client in the TypeScript SDK. The player must be connected first: the client manages and refreshes the player session. It returns the data of the response below.

{
  "success": true,
  "data": {
    "questId": 12,
    "taskId": 45,
    "verified": true,
    "questCompleted": true,
    "tasksDone": 5,
    "taskCount": 5,
    "rewards": {
      "xp": 100,
      "coins": 50,
      "badge": "Newcomer",
      "roleGranted": false,
      "leveledUp": true,
      "newLevel": 12
    }
  }
}

{
  "success": true,
  "data": {
    "questId": 12,
    "taskId": 44,
    "verified": true,
    "questCompleted": false,
    "tasksDone": 4,
    "taskCount": 5,
    "rewards": null
  }
}

A task that is not done

A task that is not done yet returns 409 with the code quest_task_not_done, and message says why in a sentence the game can show. A task that cannot be verified this way returns 409 with the code quest_task_unavailable and a reason:

The other errors are the quest's rules, as on Start a quest. An error about a quest includes message, a sentence the game can show to the player. CEEJAY does not send the member a direct message.

Limits

20 writes a minute for one player session, shared by Start, Verify and Answer a quest task, Buy a shop item, Claim an item and Check in. The three X-RateLimit headers report that count. Every request made with a player session also counts toward 140 a minute. See Rate limits. Over a limit the response is 429 with the code rate_limited, retryAfter and a Retry-After header.

Errors

Every error body also includes requestId, and a 400 with the code bad_request identifies the invalid field in field. Match on code; message text can change.

The errors every request of a game shares (the key, the state of the game, the origin, 405, 429, 500) are on the Errors page, and the errors specific to the game loop are under Codes of the game loop.