Start a quest

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

Use it when the player presses Start on a quest from List the quests. Starting a quest the player already has open returns alreadyStarted: true and changes nothing, which is also what a retry after a lost response returns, so the request is safe to repeat and takes no key. 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

Example

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

The TypeScript example uses connect.hub.startQuest 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,
    "status": "in_progress",
    "alreadyStarted": false
  }
}

{
  "success": true,
  "data": {
    "questId": 12,
    "status": "in_progress",
    "alreadyStarted": true
  }
}

What stops a player

A quest the player cannot start is rejected with the code of the rule that applies, all of them 409 apart from quest_not_found. For a quest that requires a role, CEEJAY looks up the member in Discord once. CEEJAY does not send the member a direct message. A rejection about a quest includes message, a sentence the game can show to the player.

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.