# 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
```

{% hint style="info" %}
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`.
{% endhint %}

#### 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 | Conditionally<sup>1</sup> | The hCaptcha token, required if the quest has captcha enabled. |

{% hint style="info" %}
You can find both the `questId` and `deploymentId` in the sharing panel of the quest editor.
{% endhint %}

<sup>1</sup> `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:

```json
{
  "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

{% hint style="info" %}
Remember to replace `your-community-slug` with your actual community slug in all the examples below.
{% endhint %}

```javascript
// 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

```javascript
// 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](https://docs.hcaptcha.com/)
* [User Authentication](https://github.com/GetDomino/matiz/blob/main/docs/broken-reference/README.md)