Claiming a quest

Overview

The Claim Quest endpoint allows authenticated users to submit their progress or completion for a specific quest deployment. This process may include verifying required accounts, submitting task inputs, and passing a captcha challenge if enabled.

Key benefits:

• Ensures only eligible users can claim quest rewards

• Supports custom task input validation

• Integrates with hCaptcha for anti-bot protection

How It Works

1. The user completes the required quest tasks and (if needed) solves a captcha.

2. The frontend collects all necessary data and sends a POST request to the claim endpoint.

3. The backend verifies authentication, quest existence, required accounts, and (if enabled) captcha validity.

4. If all checks pass, the claim is processed and a validation message is returned.

API Reference

POST https://your-community-slug.domino.page/api/quests/{id}/claim

Replace your-community-slug in the URL with your community slug. You can find your community slug in your community URL - it's the part before .domino.page. For example, if your community URL is my-community.domino.page, your slug is my-community.

Request Parameters

Parameter	Type	Required	Description
questId	String	Yes	The unique identifier of the quest being claimed.
deploymentId	String	Yes	The unique identifier of the quest deployment instance.
taskInputs	Array	Yes	User-provided answers or data for the quest's tasks.
captchaToken	String	Conditionally1	The hCaptcha token, required if the quest has captcha enabled.

You can find both the questId and deploymentId in the sharing panel of the quest editor.

¹ captchaToken is required only if the quest's metadata specifies requireCaptcha: true.

Notes:

• The user must be authenticated.

• The endpoint automatically includes the user's ID and a referral code (if present in cookies).

Response

On success:

{
  "message": "Your claim was successful!" // or a specific validation reason
}

On error (examples):

• 404 Quest not found

• 400 Captcha token is required

• 400 Failed to verify captcha, please try again.

Examples

Remember to replace your-community-slug with your actual community slug in all the examples below.

// Example: Claiming a quest with captcha
const response = await $fetch('https://your-community-slug.domino.page/api/quests/123/claim', {
  method: 'POST',
  body: {
    questId: '123',
    deploymentId: 'abc456',
    taskInputs: [
      { answer: '42' },
      { answer: 'Domino' }
    ],
    captchaToken: '10000000-xxxx-xxxx-xxxx-000000000001'
  }
});
console.log(response.message);

Real-World Usage

// Used in a Vue component to handle quest claims
async function claimQuest() {
  try {
    const res = await $fetch(`https://your-community-slug.domino.page/api/quests/${deployment.quest.id}/claim`, {
      method: 'POST',
      body: {
        questId: deployment.quest.id,
        deploymentId: deployment.id,
        taskInputs: taskInputs,
        captchaToken: captchaToken // only if required
      }
    });
    // Show success message to user
    emit('success', res.message);
  } catch (error) {
    // Handle error, show message to user
    emit('error', error?.data?.data?.error || 'Claim failed');
  }
}

Related Resources

• hCaptcha Integration Guide

• User Authentication