Complete a quest task

POST /v1/quests/tasks/complete · requires quests:complete

Use this when the thing a member has to do happens on your own platform: finishing a tutorial, reaching a rank, signing up. You add a task of the type Completed by your API to a quest. When a member has done it, your server calls this request and CEEJAY completes the task. When it was the quest's last task, CEEJAY completes the quest and grants its rewards.

To complete a whole quest for a member without matching a task, use Complete a quest. That page compares the two requests.

This request is also available at a legacy endpoint, /api/quests/external/complete, which keeps working: see Complete a quest task (legacy endpoint).

Set up the task

Give each task its own key, and use only letters, digits, _ and -, from 4 to 64 characters. The builder asks for one key per task but does not check it, and it accepts keys this request rejects.

Body parameters

Deprecated names that still work

Send one of the two. If both are sent, the deprecated one is used. Deprecated names remain supported for as long as version 1 exists, and an error message names the one you sent.

Who did it

Send one of discordId, playerId with platform, xHandle, wallet, github and twitch. If you send more than one, CEEJAY uses the first in that order and ignores the rest. A discordId that is null or an empty string is skipped, and the next one in that order is used.

platform is read only when playerId is the identifier in use. With a discordId, or with no playerId, whatever the body contains under that name is ignored. With playerId, a missing platform returns 400, and a platform your community does not know returns 400 with the code unknown_platform.

When platform is a game set up for Connect and the key is limited to other games of your community, the task returns 403 with the code game_not_allowed. Otherwise, a member who connected the player themselves at the basic level is not found by playerId: nothing confirmed that the player is theirs, so the task returns 202 as it does for a player nobody is linked to. A player connected at the verified level is found, and so is one your own server linked with Link an account. A game can be set up so that basic connections earn too, and then they are found.

Send xHandle, wallet, github and twitch as strings. A whole number is read as well, as its digits, so a GitHub or Twitch ID sent as a JSON number finds the same account as that ID in quotes. That applies up to 9,007,199,254,740,991, the largest whole number a JSON number can hold with every digit intact. An X user ID is larger, so send it in quotes. A larger number, a number with a fraction, a list, an object and true or false do not match a member and return 202. They are never converted to text.

An account counts when the member connected it in your community and has not disconnected it. Members connect accounts themselves, for example through the Connect X, Connect Web3 Wallet, Connect GitHub and Connect Twitch quest tasks, or you link them with Link an account under the platform twitter, metamask, github or twitch. When two members connected the same account, the one who connected it last is used.

A discordId CEEJAY already has a member profile for is used as it is. One it has no profile for is looked up in Discord first:

• A member of your server passes, and that result is cached for five minutes.
• An ID that is not in your server does not match a member. The call returns 202 with matched: 0, like any identifier CEEJAY cannot match.
• When the Discord API is unavailable, or its response does not say whether the ID is a member, the call returns 503 with the code discord_unavailable. No changes were made: retry shortly.

Returns

Each entry of completed and sentForReview contains questId and questTitle. These fields are inside data. Alongside success, the response also includes the two original fields, which remain for as long as version 1 exists: matched, and completed with each quest's title under title.

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/quests/tasks/complete \
  -H "Authorization: Bearer $CEEJAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskKey": "tk_4k2m9x7qzb",
    "discordId": "409876543210987654",
    "evidence": "https://acme.example/players/nova/tutorial",
    "idempotencyKey": "tutorial-88213004"
  }'

The TypeScript example uses ceejay.quests.reportTask from the TypeScript SDK. It returns the full response below.

{
  "success": true,
  "matched": 1,
  "completed": [
    {
      "questId": 42,
      "title": "Finish the Acme tutorial"
    }
  ],
  "data": {
    "matched": 1,
    "completed": [
      {
        "questId": 42,
        "questTitle": "Finish the Acme tutorial"
      }
    ],
    "sentForReview": [],
    "duplicate": false
  }
}

When CEEJAY does not match a member, the response is 202:

{
  "success": true,
  "matched": 0,
  "data": {
    "matched": 0,
    "completed": [],
    "sentForReview": []
  }
}

What a call does

1. CEEJAY checks the key, then finds the member.
2. It looks at the quests in your community that are active and inside their start and end dates, and at their Completed by your API tasks whose key is the one you sent. Any number of tasks can match, in any quest. A quest whose task key does not match is never started.
3. For each match it applies the quest's own rules, listed below. A quest the member cannot take part in is skipped without an error.
4. It completes the task. With review on, it files the report in the Review Queue instead, and data.sentForReview lists the quest.
5. When every task of a quest is done, the quest completes, and data.completed lists it.

What CEEJAY checks, and what it does not

The quest's own rules apply. If one of them blocks a quest, the call still returns 200 with that quest omitted, and it does not say which rule applied:

• The quest is not active, or today is outside its dates.
• The quest requires a role the member does not have. A member who already has a run of that quest open is not checked again.
• The member is below the level, or short of the season XP, that the quest asks for.
• The quest belongs to a program the member has not joined.
• The quest's prerequisite quest is not done.
• The wait between runs of a repeatable quest has not passed.
• The member has reached the quest's limit per member, or the quest has reached its overall limit.
• The member has reached your community's Daily Quest Limit Per User, in your Quest settings.

When a matching quest requires a role and CEEJAY's bot cannot read the member's roles from Discord, the call returns 503 with the code discord_unavailable. Nothing was started or completed: retry shortly.

CEEJAY does not check:

• That a member it already knows is still in your server. Only a discordId it has no member profile for is looked up in Discord.
• That what you report is true. Unless review is on, you are confirming that the member did it.
• That a key belongs to one task. Every live task that has the key is completed, in every quest.
• Which API key made the call. Any key with the scope can report any task key in your community.

Review

With review on, nothing completes yet. CEEJAY files the report in the Review Queue, under Gamification → Quests, and your team gets a Quest submission needs review notification. The moderator sees evidence as the proof, or Reported done by your platform when you sent none. Approving completes the task, and the quest when it was the last task. Rejecting does not, and the next call from your platform files it again.

Review is on when the task's switch is on or the call sends review: true. A call can ask for review, but it cannot take it away. While a report is awaiting review, the quest's other automatic tasks do not advance for that member.

Without review, evidence is stored with the member's progress on the task.

Retrying safely

Send an idempotencyKey with every call you might need to retry. It is a string of 1 to 128 characters that you choose, sent in the JSON body.

• A key is stored only when the call changed something: a 200 in which at least one quest was completed or sent for review. A retry then returns the original response, with data.duplicate: true and the header Idempotent-Replayed: true, and CEEJAY's bot is not called again.
• No key is stored for a call that made no changes. A 202, and a 200 with both lists empty, do not use up the key. A retry with the same key is processed as a new request, for example after the player has linked the account.
• Each key is tied to one request payload. The same request means the same task key, member, evidence and review. A key that was used for a different request returns 409 with the code idempotency_key_reused.
• After a lost response, the key prevents a second attempt. When CEEJAY's bot does not respond in time, or its response is lost because it failed part way or the connection dropped, the call returns 502 with the code bot_timeout, and the task may or may not have been completed. With a key, the same request returns 409 with the code idempotency_in_progress for a minute, and idempotency_outcome_unknown after that: it is never sent to the bot a second time. Check the member's quests in the dashboard, then use a new key if the task has to be sent again.
• bot_unavailable is the response that is safe to retry. It means the bot never received the task or rejected it: no changes were made, and the key is released, so a retry with the same key is processed as a new request.
• On an instance that does not support idempotency keys yet, a call that sends one returns 503 with the code idempotency_unavailable. idempotency_key is not accepted on this endpoint; use idempotencyKey.

Without a key, what a retry does depends on the quest:

• A quest a member can complete once: after the first completion a retry does nothing and returns 200 with empty lists. It is safe to retry.
• A report awaiting review: a retry does nothing until a moderator decides.
• A task already done in a quest with other tasks still open: a retry does nothing.
• A quest members can repeat: once the wait between runs is over, a retry starts a new run and completes the task in it, and the quest grants its rewards again when that was its last task. With no wait set, every call starts a new run. So after a bot_timeout, sending the task again without a key can complete a repeatable quest a second time. Send one call for each thing the member did, with a key.

Side effects

• When a quest completes, CEEJAY grants everything configured on it: XP, coins while your community's economy is enabled, the badge, the role and any extra rewards set on the quest in the Rewards Engine. A quest in a program also adds its XP to the member's program XP.
• Subscribers to the quest.completed webhook get an event when the quest completes.
• The completion is added to the member's activity history. A badge the member did not have yet can send badge.earned, and XP that levels the member up grants that level's rewards and roles and can send member.level_up.
• A call starts the quest for the member, if they have not started it, for every live quest that has a Completed by your API task with your key. A quest that one of the rules above blocks is not started.
• CEEJAY posts no completion message and no achievement card in Discord for this request. The member sees the task's status when they press Check status.

Errors

A body that is not valid JSON, or is over 1 MB, is rejected before the key is checked.

CEEJAY returns 202, not an error, when it does not match a member, and the response says nothing else about the member. This is deliberate, so that nobody can work out who is in your community by trying names. It is not a full guarantee: 0 against 1 still shows whether an X handle, wallet or login is connected, and whether a Discord ID is one CEEJAY knows or a member of your server.

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 shares (401, 403, 405, 429, 500) are on the Errors page.

Related

• Complete a quest completes a whole quest for a member, with no task.