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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.domino.run/docs/claiming-a-quest.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.