Habitica API

https://habitica.com/apidoc
Admin
Habitica API provides programmatic access to manage user habits, tasks, challenges, groups, and...
Tokens:90,486
Snippets:404
Trust Score:9.6
Update:10 months ago
Show doc for...
Tokens:
Raw
### Habitica API Get Equipment Items Example Response (JSON)

Source: https://habitica.com/apidoc/index

An example of a successful response when retrieving a list of equipment items available for purchase for the authenticated user. The response includes details such as the item's text, notes, value, type, key, and stats.

```json
{
    "success": true,
    "data": [
        {
            "text": "Training Sword",
            "notes": "Practice weapon. Confers no benefit.",
            "value": 1,
            "type": "weapon",
            "key": "weapon_warrior_0",
            "set": "warrior-0",
            "klass": "warrior",
            "index": "0",
            "str": 0,
            "int": 0,
            "per": 0,
            "con": 0
        }
    ]
}
```

--------------------------------

### Get Challenge API Request Example

Source: https://habitica.com/apidoc/index

An example of how to call the API to retrieve details for a specific challenge. The challengeId is a required path parameter.

```http
GET /challenges/{challengeId} HTTP/1.1
Host: habitica.com
Authorization: Bearer YOUR_API_TOKEN
```

--------------------------------

### Get Challenges (200 OK Response Example)

Source: https://habitica.com/apidoc/index

Example JSON response for a successful request to retrieve challenges. It includes details about the group, challenge name, leader, timestamps, prize, member count, task ordering, and official status. This response structure is consistent across various challenge retrieval operations.

```json
{
  "data": [
    {
      "group": {
        "_id": "group-id-associated-with-challenge",
        "name": "MyGroup",
        "type": "guild",
        "privacy": "public"
      },
      "name": "Long Detailed Name of Challenge",
      "shortName": "my challenge",
      "leader": {
        "_id": "user-id-of-challenge-creator",
        "profile": {
          "name": "MyUserName"
        }
      },
      "updatedAt": "timestamp",
      "createdAt": "timestamp",
      "_id": "challenge-id",
      "prize": 0,
      "memberCount": 1,
      "tasksOrder": {
        "rewards": [
          "uuid-of-challenge-reward"
        ],
        "todos": [
          "uuid-of-challenge-todo"
        ],
        "dailys": [
          "uuid-of-challenge-daily"
        ],
        "habits": [
          "uuid-of-challenge-habit"
        ]
      },
      "official": false,
      "id": "challenge-id"
    }
  ]
}
```

--------------------------------

### Webhook Add Example

Source: https://habitica.com/apidoc/index

This snippet shows an example of data that can be used to add a webhook. It includes optional fields for configuration.

```json
{
    "enabled": false,
    "type": "taskActivity"
}
```

```json
{
    "options": {
        "groupId": "new-uuid-of-group"
    }
}
```

--------------------------------

### Flag Challenge API Request Example

Source: https://habitica.com/apidoc/index

An example of how to call the API to flag a challenge. This requires the challengeId and can optionally include a comment explaining the reason for flagging.

```http
POST /challenges/{challengeId}/flag HTTP/1.1
Host: habitica.com
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "comment": "This challenge violates community guidelines."
}
```

--------------------------------

### Export Challenge to CSV API Request Example

Source: https://habitica.com/apidoc/index

An example of how to call the API to export a challenge's data in CSV format. The challengeId is required in the URL.

```http
GET /challenges/{challengeId}/export/csv HTTP/1.1
Host: habitica.com
Authorization: Bearer YOUR_API_TOKEN
```

--------------------------------

### Habitica API: Leave Group with Options (Example)

Source: https://habitica.com/apidoc/index

Example request body for leaving a group, specifying whether to remain in or leave associated challenges. This demonstrates the use of the `keepChallenges` parameter.

```json
{
  "keepChallenges": "remain-in-challenges"
}
```

--------------------------------

### Get Group Details - Tavern Example

Source: https://habitica.com/apidoc/index

This snippet displays a successful response when retrieving details for a specific group, using the 'Tavern' as an example. The response includes basic group information, conforming to the group object schema. The `groupId` parameter can specify 'party' or 'habitrpg' (for Tavern).

```json
HTTP/1.1 200 OK
{
  "name": "Tavern",
  ...
}
```

--------------------------------

### Delete Challenge API Request Example

Source: https://habitica.com/apidoc/index

An example of how to call the API to delete a challenge. This typically involves specifying the challengeId in the path.

```http
DELETE /challenges/{challengeId} HTTP/1.1
Host: habitica.com
Authorization: Bearer YOUR_API_TOKEN
```

--------------------------------

### User | Get equipment/gear items available for purchase

Source: https://habitica.com/apidoc/index

Fetches a list of equipment and gear items that are available for purchase by the authenticated user.

```APIDOC
## User | Get equipment/gear items available for purchase

### Description
Retrieves a list of equipment and gear items available for the authenticated user to purchase.

### Method
GET

### Endpoint
`/api/v3/user/available-gear`

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (Array) - A list of available gear items. Each item object contains details like `text`, `notes`, `value`, `type`, `key`, `set`, `klass`, `index`, `str`, `int`, `per`, and `con`.

#### Response Example
```json
{
    "success": true,
    "data": [
        {
            "text": "Training Sword",
            "notes": "Practice weapon. Confers no benefit.",
            "value": 1,
            "type": "weapon",
            "key": "weapon_warrior_0",
            "set": "warrior-0",
            "klass": "warrior",
            "index": "0",
            "str": 0,
            "int": 0,
            "per": 0,
            "con": 0
        }
    ]
}
```
```

--------------------------------

### Habitica API - Example Success Response for Scoring Task

Source: https://habitica.com/apidoc/index

This example demonstrates a successful response after scoring a task. It includes the 'success' status, 'data' containing user statistics, and an empty 'notifications' array. The 'data' object provides detailed player stats like HP, MP, EXP, GP, level, class, and buffs.

```json
{
    "success": true,
    "data": {
        "delta": 0.9746999906450404,
        "_tmp": {},
        "hp": 49.06645205596985,
        "mp": 37.2008917491047,
        "exp": 101.93810026267543,
        "gp": 77.09694176716997,
        "lvl": 19,
        "class": "rogue",
        "points": 0,
        "str": 5,
        "con": 3,
        "int": 3,
        "per": 8,
        "buffs": {
            "str": 9,
            "int": 9,
            "per": 9,
            "con": 9,
            "stealth": 0,
            "streaks": false,
            "snowball": false,
            "spookySparkles": false,
            "shinySeed": false,
            "seafoam": false
        },
        "training": {
            "int": 0,
            "per": 0,
            "str": 0,
            "con": 0
        }
    },
    "notifications": []
}
```

--------------------------------

### GET /status

Source: https://habitica.com/apidoc/index

Get Habitica's API status.

```APIDOC
## GET /status

### Description
Checks the current status of the Habitica API.

### Method
GET

### Endpoint
`/api/v4/status`

### Response
#### Success Response (200)
- **status** (String) - 'up' if everything is ok

### Response Example
```json
{
  "status": "up"
}
```
```

--------------------------------

### GET /challenges

Source: https://habitica.com/apidoc/index

Retrieves a list of challenges, sorted with official challenges first, then by newest to oldest. Supports pagination via query parameters.

```APIDOC
## GET /challenges

### Description
Retrieves an array of challenges, with official challenges listed first, followed by others sorted from newest to oldest. Supports pagination.

### Method
GET

### Endpoint
/challenges

#### Query Parameters
- **page** (integer) - Optional - The page number for pagination. Must be a positive integer.

### Response
#### Success Response (200)
- **challenges** (Object[]) - An array of challenge objects.
  - **_id** (UUID) - The group ID associated with the challenge.
  - **type** (String) - Group type (`guild` or `party`).
  - **privacy** (String) - Group privacy (`public` or `private`).
  - **name** (String) - The full name of the challenge.
  - **shortName** (String) - A shortened name for the challenge, used as a tag.
  - **leader** (Object) - Details of the challenge leader.
    - **_id** (UUID) - User ID of the challenge leader.
    - **profile** (Object) - Profile information of the leader.
      - **name** (String) - Display name of the leader.
  - **updatedAt** (String) - Timestamp of the last update.
  - **createdAt** (String) - Timestamp of the challenge creation.
  - **id** (UUID) - The unique ID of the challenge.
  - **prize** (String) - Number of gems offered as a prize (can be 0).
  - **memberCount** (String) - Number of users participating in the challenge.
  - **tasksOrder** (Object) - Object containing IDs of the challenge's tasks and rewards in their preferred sort order.
    - **rewards** (Array) - Array of reward task IDs.
    - **todos** (Array) - Array of todo task IDs.
    - **dailys** (Array) - Array of daily task IDs.
    - **habits** (Array) - Array of habit task IDs.
  - **official** (Boolean) - Boolean indicating if this is an official Habitica challenge.

#### Response Example (200)
```json
{
  "data": [
    {
      "group": {
        "_id": "group-id-associated-with-challenge",
        "name": "MyGroup",
        "type": "guild",
        "privacy": "public"
      },
      "name": "Long Detailed Name of Challenge",
      "shortName": "my challenge",
      "leader": {
        "_id": "user-id-of-challenge-creator",
        "profile": {
          "name": "MyUserName"
        }
      },
      "updatedAt": "timestamp",
      "createdAt": "timestamp",
      "_id": "challenge-id",
      "prize": 0,
      "memberCount": 1,
      "tasksOrder": {
        "rewards": ["uuid-of-challenge-reward"],
        "todos": ["uuid-of-challenge-todo"],
        "dailys": ["uuid-of-challenge-daily"],
        "habits": ["uuid-of-challenge-habit"]
      },
      "official": false,
      "id": "challenge-id"
    }
  ]
}
```

#### Error Response (400)
- **queryPageInteger** (BadRequest) - Page query parameter must be a positive integer.

#### Error Response (404)
- **UserNotFound** (NotFound) - The specified user could not be found.
```

--------------------------------

### Habitica API User Equip Item Example (URL)

Source: https://habitica.com/apidoc/index

Illustrates how to construct a URL to equip or unequip an item for a user in Habitica. The URL includes the base API path and specific parameters for the item type and the item's key.

```http
https://habitica.com/api/v3/user/equip/equipped/weapon_warrior_2
```

--------------------------------

### POST /force-start-quest

Source: https://habitica.com/apidoc/index

Force-start a pending quest.

```APIDOC
## POST /force-start-quest

### Description
Forces the start of a pending quest.

### Method
POST

### Endpoint
`/api/v4/groups/{groupId}/quests/force-start`

### Parameters
#### Path Parameters
- **groupId** (String) - Required - The group _id (or 'party')

### Permissions
- QuestLeader
- GroupLeader

### Response
#### Success Response (200)
- **data** (Object) - Quest Object

#### Error Response (404)
- **GroupNotFound** (NotFound) - The specified group could not be found.
- **QuestNotFound** (NotFound) - The specified quest could not be found.
```

--------------------------------

### Get a Specific Task (API Request)

Source: https://habitica.com/apidoc/index

This snippet shows how to retrieve details for a single task using its ID. It specifies the `taskId` as a path parameter. An example `curl` command is provided for practical usage.

```http
GET /api/v3/tasks/{taskId}
```

```shell
curl -i https://habitica.com/api/v3/tasks/54a81d23-529c-4daa-a6f7-c5c6e7e84936
```

--------------------------------

### Habitica API User Feed Pet Example URLs (HTTP)

Source: https://habitica.com/apidoc/index

Demonstrates the format of URLs used to feed a pet in Habitica. These URLs include path parameters for the pet and food, and an optional query parameter for the amount of food to provide.

```http
https://habitica.com/api/v3/user/feed/Armadillo-Shade/Chocolate
```

```http
https://habitica.com/api/v3/user/feed/Armadillo-Shade/Chocolate?amount=9
```

--------------------------------

### POST /user/buy/gear/{key}

Source: https://habitica.com/apidoc/index

Purchases a piece of gear for the user.

```APIDOC
## POST /user/buy/gear/{key}

### Description
Purchases a piece of gear for the user.

### Method
POST

### Endpoint
/user/buy/gear/{key}

### Parameters
#### Path Parameters
- **key** (String) - Required - The identifier of the item to buy.

### Response
#### Success Response (200)
- **items** (Object) - User's item inventory.
- **flags** (Object) - User's flags.
- **achievements** (Object) - User's achievements.
- **stats** (Object) - User's current stats.
- **message** (String) - Confirmation message of the purchase.

#### Response Example
```json
{
  "success": true,
  "data": {
    // ... truncated user record
  },
  "message": "Bought Wooden Shield"
}
```
```

--------------------------------

### Get Specific Task Example

Source: https://habitica.com/apidoc/index

Returns a specific task object when a successful 200 status code is received. This includes details like task ID, user ID, text, type, and historical values.

```json
{
    "success": true,
    "data": {
        "_id": "2b774d70-ec8b-41c1-8967-eb6b13d962ba",
        "userId": "b0413351-405f-416f-8787-947ec1c85199",
        "text": "API Trial",
        "alias": "apiTrial",
        "type": "habit",
        "notes": "",
        "tags": [],
        "value": 11.996661122825959,
        "priority": 1.5,
        "attribute": "str",
        "challenge": {
            "taskId": "5f12bfba-da30-4733-ad01-9c42f9817975",
            "id": "f23c12f2-5830-4f15-9c36-e17fd729a812"
        },
        "group": {
            "assignedUsers": [],
            "approval": {
                "required": false,
                "approved": false,
                "requested": false
            }
        },
        "reminders": [],
        "createdAt": "2017-01-12T19:03:33.495Z",
        "updatedAt": "2017-01-13T20:52:02.927Z",
        "history": [
            {
                "value": 1,
                "date": 1484248053486
            },
            {
                "value": 1.9747,
                "date": 1484252965224
            },
            {
                "value": 2.9253562257358428,
                "date": 1484252966902
            },
            {
                "value": 6.415599723011605,
                "date": 1484329050485
            },
            {
                "value": 10.482627142836241,
                "date": 1484329089835
            },
            {
                "value": 11.24705848799571,
                "date": 1484329095500
            },
            {
                "value": 11.996661122825959,
                "date": 1484329552423
            }
        ],
        "down": false,
        "up": true,
        "id": "2b774d70-ec8b-41c1-8967-eb6b13d962ba"
    },
    "notifications": []
}
```

--------------------------------

### Moderators | Get user history (API Example)

Source: https://habitica.com/apidoc/index

Demonstrates how to retrieve the history of a user using the Habitica V3 API. Requires admin privileges. Returns user history data on success or an error object on failure.

```json
{
    "success": false,
    "error": "NotAuthorized",
    "message": "Missing authentication headers."
}
```

```json
{
    "success": false,
    "error": "NotAuthorized",
    "message": "There is no account that uses those credentials."
}
```

```json
{
    "success": false,
    "error": "NotFound",
    "message": "User with id \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\" not found."
}
```

```json
{
    "success": false,
    "error": "NotAuthorized",
    "message": "You don't have admin access."
}
```

--------------------------------

### Get Groups for User - Private Guilds and Tavern Example

Source: https://habitica.com/apidoc/index

This code shows a successful response when retrieving groups for a user, specifically requesting 'privateGuilds' and 'tavern'. The API returns an array of group objects that match the specified types. The query parameters allow filtering by type and pagination for public guilds.

```json
HTTP/1.1 200 OK
[
  {guilds}
]
```

--------------------------------

### POST /tags

Source: https://habitica.com/apidoc/index

Create a new tag.

```APIDOC
## POST /tags

### Description
Creates a new tag for the user.

### Method
POST

### Endpoint
`/api/v4/tags`

### Parameters
#### Request Body
- **name** (string) - Required - The name of the tag to be added.

### Request Example
```json
{
    "name": "practicetag"
}
```

### Response
#### Success Response (201)
- **data** (Object) - The newly created tag

### Response Example
```json
{
    "success": true,
    "data": {
        "name": "practicetag",
        "id": "8bc0afbf-ab8e-49a4-982d-67a40557ed1a"
    },
    "notifications": []
}
```
```

--------------------------------

### GET /tags/{tagId}

Source: https://habitica.com/apidoc/index

Get a specific tag.

```APIDOC
## GET /tags/{tagId}

### Description
Retrieves details of a specific tag.

### Method
GET

### Endpoint
`/api/v4/tags/{tagId}`

### Parameters
#### Path Parameters
- **tagId** (UUID) - Required - The tag _id

### Response
#### Success Response (200)
- **data** (Object) - The tag object

### Response Example
```json
{
    "success": true,
    "data": {
        "name": "practicetag",
        "id": "8bc0afbf-ab8e-49a4-982d-67a40557ed1a"
    },
    "notifications": []
}
```

#### Error Response (400)
- **InvalidRequestParameters** (BadRequest) - "tagId" must be a valid UUID corresponding to a tag belonging to the user.

#### Error Response (404)
- **TagNotFound** (NotFound) - The specified tag could not be found.
```

--------------------------------

### User | Set Custom Day Start time for user

Source: https://habitica.com/apidoc/index

Sets a custom start time for the user's day.

```APIDOC
## POST /api/v4/user/customize-day-start

### Description
Sets a custom start time for the user's day.

### Method
POST

### Endpoint
/api/v4/user/customize-day-start

### Parameters
#### Request Body
- **dayStart** (number) - Optional - The hour number 0-23 for day to begin. If not supplied, will default to 0. Default value: `0`

### Request Example
```json
{
    "dayStart": 2
}
```

### Response
#### Success Response (200)
- **data** (Object) - An empty Object
- **message** (String) - Success message

#### Error Response (4xx)
- **Validation** (BadRequest) - Value provided is not a number, or is outside the range of 0-23

### Response Example
```json
{
    "success": true,
    "data": {
        "message": "Your custom day start has changed."
    },
    "notifications": []
}
```

### Error Example
```json
{
    "success": false,
    "error": "BadRequest",
    "message": "User validation failed",
    "errors": [
        {
            "message": "Path `preferences.dayStart` (25) is more than maximum allowed value (23).",
            "path": "preferences.dayStart",
            "value": 25
        }
    ]
}
```
```

--------------------------------

### Example Task Data Retrieval (JSON)

Source: https://habitica.com/apidoc/index

This snippet demonstrates the structure of a successful API response when retrieving an array of tasks. It includes details about task properties, history, and associated challenges or groups. The response is in JSON format.

```json
{
    "success": true,
    "data": [
        {
            "_id": "5f12bfba-da30-4733-ad01-9c42f9817975",
            "text": "API Trial",
            "type": "habit",
            "notes": "",
            "tags": [],
            "value": 27.70767809690112,
            "priority": 1.5,
            "attribute": "str",
            "challenge": {
                "id": "f23c12f2-5830-4f15-9c36-e17fd729a812"
            },
            "group": {
                "assignedUsers": [],
                "approval": {
                    "required": false,
                    "approved": false,
                    "requested": false
                }
            },
            "reminders": [],
            "createdAt": "2017-01-12T19:03:33.485Z",
            "updatedAt": "2017-01-13T17:45:52.442Z",
            "history": [
                {
                    "date": 1484257319183,
                    "value": 18.53316748293123
                },
                {
                    "date": 1484329552441,
                    "value": 27.70767809690112
                }
            ],
            "down": false,
            "up": true,
            "id": "5f12bfba-da30-4733-ad01-9c42f9817975"
        },
        {
            "_id": "54a81d23-529c-4daa-a6f7-c5c6e7e84936",
            "text": "Challenge TODO",
            "type": "todo",
            "notes": "",
            "tags": [],
            "value": 2,
            "priority": 2,
            "attribute": "str",
            "challenge": {
                "id": "f23c12f2-5830-4f15-9c36-e17fd729a812"
            },
            "group": {
                "assignedUsers": [],
                "approval": {
                    "required": false,
                    "approved": false,
                    "requested": false
                }
            },
            "reminders": [],
            "createdAt": "2017-01-12T19:07:10.310Z",
            "updatedAt": "2017-01-13T20:24:51.070Z",
            "checklist": [],
            "collapseChecklist": false,
            "completed": false,
            "id": "54a81d23-529c-4daa-a6f7-c5c6e7e84936"
        }
    ],
    "notifications": []
}
```

--------------------------------

### Unsubscribe from Email Notifications (GET)

Source: https://habitica.com/apidoc/index

Unsubscribes a user from email notifications via a GET request, typically initiated by clicking a link in an email.

```APIDOC
## GET /unsubscribe

### Description
Unsubscribe an email address or user from email notifications.
This is a GET method included in official emails from Habitica that will unsubscribe the user from emails. Does not require authentication.

### Method
GET

### Endpoint
/unsubscribe

### Parameters
#### Query Parameters
- **code** (string) - Required - An unsubscription code that contains an encrypted User ID or email address.

### Response
#### Success Response (200)
- **Webpage** (string) - An html success message.

#### Response Example
```html
<!DOCTYPE html>
<html>
<head>
<title>Unsubscribed</title>
</head>
<body>
<h1>You have been successfully unsubscribed.</h1>
</body>
</html>
```

#### Error Response (400)
- **missingUnsubscriptionCode** (BadRequest) - The unsubscription code is missing.

#### Error Response (404)
- **UserNotFound** (NotFound) - The specified user could not be found.
```

--------------------------------

### Example Success Response for Releasing Mounts (JSON)

Source: https://habitica.com/apidoc/index

This JSON object represents a successful response after releasing user mounts. It indicates the operation's success and may contain an empty or populated 'data' field depending on the specifics of the release.

```json
{
  "success": true,
  "data": {
    },
    "items": {}
  },
  "message": "Mounts released"
}
```

--------------------------------

### POST /api/v3/user/release-mounts

Source: https://habitica.com/apidoc/index

Releases the user's mounts.

```APIDOC
## POST /api/v3/user/release-mounts

### Description
Releases the user's mounts.

### Method
POST

### Endpoint
/api/v3/user/release-mounts

### Response
#### Success Response (200)
- **data** (Object) - user.items.mounts
- **message** (String) - Success message

#### Error Response (4xx)
- **error** (String) - Error type (e.g., NotAuthorized)
- **message** (String) - Error message (e.g., "Not enough gems")

### Response Example
```json
{
  "success": true,
  "data": {
    "items": {}
  },
  "message": "Mounts released"
}
```

### Error Example
```json
{
  "success": false,
  "error": "NotAuthorized",
  "message": "Not enough Gems"
}
```
```

--------------------------------

### Example Success Response for Rerolling User (JSON)

Source: https://habitica.com/apidoc/index

A successful response after rerolling a user's tasks, typically initiated by using a Fortify Potion. The 'data' field might be empty, and the 'message' confirms the operation's completion.

```json
{
    "success": true,
    "data": {},
    "message": "Fortify complete!"
}
```

--------------------------------

### Example Success Response for Releasing Pets and Mounts (JSON)

Source: https://habitica.com/apidoc/index

Demonstrates a successful API response after releasing a user's pets, mounts, and potentially granting Triad Bingo achievements. The 'data' field includes updated achievement and item information.

```json
{
    "success": true,
    "data": {
        "achievements": {
            "ultimateGearSets": {},
            "challenges": [],
            "quests": {},
            "perfect": 0,
            "beastMaster": true,
            "beastMasterCount": 1,
            "mountMasterCount": 1,
            "triadBingoCount": 1,
            "mountMaster": true,
            "triadBingo": true
        },
        "items": {}
    },
    "message": "Mounts and pets released"
}
```

--------------------------------

### Example Task Update Return (JSON)

Source: https://habitica.com/apidoc/index

This JSON object represents a successful (200 OK) response when updating a task. It includes the success status, the updated task data, and any associated notifications.

```json
{
    "success": true,
    "data": {
        "_id": "84f02d6a-7b43-4818-a35c-d3336cec4880",
        "userId": "b0413351-405f-416f-8787-947ec1c85199",
        "text": "Test API Params",
        "alias": "test-api-params",
        "type": "todo",
        "notes": "",
        "tags": [],
        "value": -1,
        "priority": 2,
        "attribute": "int",
        "challenge": {
            "taskId": "4a29874c-0308-417b-a909-2a7d262b49f6",
            "id": "f23c12f2-5830-4f15-9c36-e17fd729a812"
        },
        "group": {
            "assignedUsers": [],
            "approval": {
                "required": false,
                "approved": false,
                "requested": false
            }
        },
        "reminders": [],
        "createdAt": "2017-01-13T21:23:05.949Z",
        "updatedAt": "2017-01-14T20:02:18.206Z",
        "checklist": [],
        "collapseChecklist": false,
        "completed": false,
        "id": "84f02d6a-7b43-4818-a35c-d3336cec4880"
    },
    "notifications": []
}
```

--------------------------------

### Unsubscribe from Emails (GET)

Source: https://habitica.com/apidoc/index

This GET method is included in official Habitica emails to allow users to unsubscribe. It does not require authentication. A 'code' query parameter is necessary, which contains an encrypted user identifier.

```http
GET /unsubscribe?code=YOUR_UNSUBSCRIPTION_CODE

# Example Response (Success 200):
{
  "Webpage": "<html><body>Unsubscribed successfully.</body></html>"
}
```

--------------------------------

### Get Challenge Member Progress - Habitica API

Source: https://habitica.com/apidoc/index

Shows the GET request for fetching the progress of a specific member within a challenge on the Habitica API. It requires both the challenge ID and the member ID in the path.

```HTTP
GET /member/{challengeId}/{memberId}
```

--------------------------------

### Get Inbox Messages - Habitica API

Source: https://habitica.com/apidoc/index

Demonstrates the GET request for retrieving inbox messages for a user in the Habitica API. It supports pagination via the 'page' query parameter and filtering by conversation ID.

```HTTP
GET /inbox?page=1
GET /inbox?conversation=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

--------------------------------

### Invite Users to Group - Emails and UUIDs Example

Source: https://habitica.com/apidoc/index

This JSON payload demonstrates inviting users to a group by providing both email addresses and user IDs (UUIDs). This allows for a flexible invitation process, combining new and existing users. This endpoint requires a `groupId` in the path parameters.

```json
{
    "emails": [
        {
            "email": "user-1@example.com"
        },
        {
            "email": "user-2@example.com"
        }
    ],
    "uuids": [
        "user-id-of-existing-user"
    ]
}
```

--------------------------------

### Habitica API Delete Tag Request Example (curl)

Source: https://habitica.com/apidoc/index

This example demonstrates how to use curl to send a DELETE request to the Habitica API to remove a specific tag from a task. It requires the task ID and the tag ID as path parameters.

```curl
curl -X "DELETE" https://habitica.com/api/v3/tasks/test-api-params/tags/3d5d324d-a042-4d5f-872e-0553e228553e
```

--------------------------------

### POST /invite-to-quest

Source: https://habitica.com/apidoc/index

Invite users to a quest.

```APIDOC
## POST /invite-to-quest

### Description
Invites users to join a quest.

### Method
POST

### Endpoint
`/api/v4/groups/{groupId}/quests/{questKey}/invite`

### Parameters
#### Path Parameters
- **groupId** (String) - Required - The group _id (or 'party')
- **questKey** (String) - Required - The quest key for invitation

### Response
#### Success Response (200)
- **data** (Object) - Quest object

#### Error Response (404)
- **GroupNotFound** (NotFound) - The specified group could not be found.
- **QuestNotFound** (NotFound) - The specified quest could not be found.
```

--------------------------------

### Example Clear Completed Todos Return (JSON)

Source: https://habitica.com/apidoc/index

This JSON object represents a successful (200 OK) response after clearing completed To-Do tasks. It indicates success and returns an empty data object and notifications array.

```json
{
    "success": true,
    "data": {},
    "notifications": []
}
```

--------------------------------

### Get Challenge Tasks API Call (cURL)

Source: https://habitica.com/apidoc/index

This cURL command illustrates how to retrieve tasks associated with a specific challenge. It sends a GET request to the challenge tasks endpoint, requiring the challengeId. Optional query parameters can filter tasks by type.

```bash
curl -i https://habitica.com/api/v3/tasks/challenge/f23c12f2-5830-4f15-9c36-e17fd729a812
```

--------------------------------

### BugReport | Report an issue (API Example)

Source: https://habitica.com/apidoc/index

Example of reporting a bug through the Habitica V3 API. This POST request requires authentication and includes the bug message and user's email in the request body. Success returns a status object; failure returns a BadRequest or NotFound error.

```json
{
    "success": false,
    "error": "BadRequest",
    "message": "The report message is missing."
}
```

```json
{
    "success": false,
    "error": "NotFound",
    "message": "The specified user could not be found."
}
```

--------------------------------

### POST /user/auth/login

Source: https://habitica.com/apidoc/index

Logs a user into the system using their username or email and password.

```APIDOC
## POST /user/auth/login

### Description
Login a user with email / username and password.

### Method
POST

### Endpoint
/api/v3/user/auth/login

### Parameters
#### Request Body
- **username** (String) - Required - Username or email of the user.
- **password** (String) - Required - The user's password.

### Response
#### Success Response (200)
- **_id** (String) - The user's unique identifier.
- **apiToken** (String) - The user's api token that must be used to authenticate requests.
- **newUser** (Boolean) - Returns true if the user was just created (always false for local login).
```

--------------------------------

### POST /user/buy/mystery_item/{key}

Source: https://habitica.com/apidoc/index

Buys a mystery item set using an Hourglass.

```APIDOC
## POST /user/buy/mystery_item/{key}

### Description
Buys a mystery item set using an Hourglass.

### Method
POST

### Endpoint
/user/buy/mystery_item/{key}

### Parameters
#### Path Parameters
- **key** (String) - Required - The identifier of the mystery set to buy.

### Response
#### Success Response (200)
- **items** (Object) - User's items inventory.
- **purchasedPlanConsecutive** (Object) - Information about consecutive plan purchases.
- **message** (String) - Confirmation message of the purchase.

#### Response Example
```json
{
  "success": true,
  "data": {
    // ... user data truncated
  },
  "message": "Purchased an item set using a Mystic Hourglass!"
}
```

#### Error Response (400)
- **notEnoughHourglasses** (NotAuthorized) - Not enough Mystic Hourglasses.
- **mysterySetNotFound** (NotFound) - The specified item does not exist or is already owned.

#### Error Example (Not Enough Hourglasses)
```json
{
    "success": false,
    "error": "NotAuthorized",
    "message": "You don't have enough Mystic Hourglasses."
}
```

#### Error Example (Mystery Set Not Found/Owned)
```json
{
    "success": false,
    "error": "NotFound",
    "message": "Mystery set not found, or set already owned."
}
```
```

--------------------------------

### Habitica API: User - Set Custom Day Start Time

Source: https://habitica.com/apidoc/index

Sets a custom start time for the user's day. Accepts a 'dayStart' number (0-23) in the request body. Success returns a message and an empty data object. Validation errors occur if the input is not a number or out of range.

```json
{
    "dayStart": 2
}
```

```json
{
    "success": true,
    "data": {
        "message": "Your custom day start has changed."
    },
    "notifications": []
}
```

```json
{
    "success": false,
    "error": "BadRequest",
    "message": "User validation failed",
    "errors": [
        {
            "message": "Path `preferences.dayStart` (25) is more than maximum allowed value (23).",
            "path": "preferences.dayStart",
            "value": 25
        }
    ]
}
```

--------------------------------

### Get a task

Source: https://habitica.com/apidoc/index

Retrieves a specific task by its ID or alias.

```APIDOC
## GET /api/v3/tasks/{taskId}

### Description
Retrieves a specific task by its ID or alias.

### Method
GET

### Endpoint
/api/v3/tasks/{taskId}

### Parameters
#### Path Parameters
- **taskId** (String) - Required - The task _id or alias

### Request Example
```bash
curl -i https://habitica.com/api/v3/tasks/54a81d23-529c-4daa-a6f7-c5c6e7e84936
```

### Response
#### Success Response (200)
- **data** (Object) - The task object details

#### Response Example
```json
{
    "success": true,
    "data": {
        "_id": "54a81d23-529c-4daa-a6f7-c5c6e7e84936",
        "text": "Challenge TODO",
        "type": "todo",
        "notes": "",
        "tags": [],
        "value": 2,
        "priority": 2,
        "attribute": "str",
        "challenge": {
            "id": "f23c12f2-5830-4f15-9c36-e17fd729a812"
        },
        "group": {
            "assignedUsers": [],
            "approval": {
                "required": false,
                "approved": false,
                "requested": false
            }
        },
        "reminders": [],
        "createdAt": "2017-01-12T19:07:10.310Z",
        "updatedAt": "2017-01-13T20:24:51.070Z",
        "checklist": [],
        "collapseChecklist": false,
        "completed": false,
        "id": "54a81d23-529c-4daa-a6f7-c5c6e7e84936"
    },
    "notifications": []
}
```
```

--------------------------------

### Example Success Response for User Items (JSON)

Source: https://habitica.com/apidoc/index

Illustrates a successful response when retrieving user-specific items like special items and card status. This JSON structure is typically returned for operations involving user inventories or flags.

```json
{
    "success": true,
    "data": {
        "specialItems": {
            "snowball": 0,
            "spookySparkles": 0,
            "shinySeed": 0,
            "seafoam": 0,
            "valentine": 0,
            "valentineReceived": [],
            "nye": 0,
            "nyeReceived": [],
            "greeting": 0,
            "greetingReceived": [
                "MadPink"
            ],
            "thankyou": 0,
            "thankyouReceived": [],
            "birthday": 0,
            "birthdayReceived": []
        },
        "cardReceived": false
    },
    "message": "valentine has been read"
}
```

--------------------------------

### Get Specific Task

Source: https://habitica.com/apidoc/index

Retrieves details for a specific task by its ID.

```APIDOC
## GET /tasks/{taskId}

### Description
Retrieves details for a specific task by its ID.

### Method
GET

### Endpoint
/tasks/{taskId}

### Parameters
#### Path Parameters
- **taskId** (String) - Required - The ID of the task to retrieve.

### Response
#### Success Response (200)
- **data** (Object) - The task object.

#### Response Example
```json
{
    "success": true,
    "data": {
        "_id": "2b774d70-ec8b-41c1-8967-eb6b13d962ba",
        "userId": "b0413351-405f-416f-8787-947ec1c85199",
        "text": "API Trial",
        "alias": "apiTrial",
        "type": "habit",
        "notes": "",
        "tags": [],
        "value": 11.996661122825959,
        "priority": 1.5,
        "attribute": "str",
        "challenge": {
            "taskId": "5f12bfba-da30-4733-ad01-9c42f9817975",
            "id": "f23c12f2-5830-4f15-9c36-e17fd729a812"
        },
        "group": {
            "assignedUsers": [],
            "approval": {
                "required": false,
                "approved": false,
                "requested": false
            }
        },
        "reminders": [],
        "createdAt": "2017-01-12T19:03:33.495Z",
        "updatedAt": "2017-01-13T20:52:02.927Z",
        "history": [
            {
                "value": 1,
                "date": 1484248053486
            },
            {
                "value": 1.9747,
                "date": 1484252965224
            },
            {
                "value": 2.9253562257358428,
                "date": 1484252966902
            },
            {
                "value": 6.415599723011605,
                "date": 1484329050485
            },
            {
                "value": 10.482627142836241,
                "date": 1484329089835
            },
            {
                "value": 11.24705848799571,
                "date": 1484329095500
            },
            {
                "value": 11.996661122825959,
                "date": 1484329552423
            }
        ],
        "down": false,
        "up": true,
        "id": "2b774d70-ec8b-41c1-8967-eb6b13d962ba"
    },
    "notifications": []
}
```

#### Error Responses
- **404** - **TaskNotFound** (NotFound) - The specified task could not be found.
```

--------------------------------

### GET /api/v3/groups/seeking-party

Source: https://habitica.com/apidoc/index

Retrieves a list of users who are currently looking for a party.

```APIDOC
## GET /api/v3/groups/seeking-party

### Description
Retrieves a list of users who are currently looking for a party.

### Method
GET

### Endpoint
/api/v3/groups/seeking-party

### Parameters
#### Query Parameters
- **page** (Number) - Optional - Page number, defaults to 0.

### Response
#### Success Response (200)
- **data** (Object[]) - An array of users looking for a party.

### Error Handling
- **400**: You are not the leader of a Party.
```

--------------------------------

### User | Purchase Gem or Gem-Purchasable Item

Source: https://habitica.com/apidoc/index

Facilitates the purchase of various in-game items using gems. Users specify the item type and key, and optionally the quantity. The API returns the updated user items and balance. It includes error handling for unavailable items, insufficient gems, and invalid keys or types.

```bash
POST /api/v3/user/buy-item/:type/:key
```
Tokens:
Raw