Application Programming Interface

API Options Navigation — The API Options tab shows user credentials

Habitica's Application Programming Interface (API) allows programmers to create third-party applications, extensions, and other tools that interface with Habitica. With the user credentials on the API Options tab, the software can gain limited access to a user's Habitica account, allowing them to display and potentially change the user's data and preferences.

Version 4 of the API (do not use)[]

Habitica's staff are creating version 4 of Habitica's API but it is still in development, incomplete, and is not suitable for use in any third-party tools for any reason. Its behavior may change at any time without notice. Any tools that use it will stop working when it changes. Even without changes, any tools using it may find that their access to it is blocked without warning. Version 3 of the API is the only version that should be used in third-party tools.

In the Habitica V3 API Documentation you will see some entries for version 4. Ignore them.

Version 3 of the API[]

On 21 May 2016, version 3 of Habitica's API was released. All third-party software should use it. Versions 1 and 2 of the API have been turned off and cannot be used.

The following resources exist to help you update any tools you have written or create new ones:

Habitica V3 API Documentation
Guidance for Comrades page containing helpful and important information that you should read before creating third-party software
Aspiring Comrades guild for asking questions and seeking help

Errors in the API Documentation[]

If you find an error in the API documentation, including typos or misleading text, please report it by going to Help > Report a Bug on the website, or Support/About > Report a Bug on the apps. If you're not sure if it's an error or not, you can ask in the Aspiring Comrades guild. Please also edit this section of this page to list the incorrect/misleading information and the correct details; your edit can be removed when the API documentation has been updated.

Quantity can be Specified for "Purchase Gem or Gem-purchasable item"[]

The Purchase Gem or Gem-purchasable item route allows you to specify the amount of items you wish to buy (e.g., more than one Hatching Potion at once, or more than one gold-purchasable Gem at once). This isn't yet documented in the official apidocs page. You specify the amount by supplying a body parameter called quantity, with the value being an integer indicating the amount of the item to buy (see elsewhere on this page for how to specify body parameters for POST routes).

You can see an example of it in use in the POST-user_purchase.test.js test file (search for the word "quantity").

Using the API[]

To use the API, you send HTTPS requests to Habitica's server. The request's URL defines the type of information you want to fetch or the type of update you want to make. The supported URLs are listed in the API's documentation.

Many of the URLs contain variables to further specify the data to fetch or update (e.g., to specify a particular task to modify).

Variable names are prefixed with a colon as in :variableName. The entire string, colon and all, should be replaced. For example, the Group - Get group route is https://habitica.com/api/v3/groups/:groupId and so for the group with the ID 12345678-90ab-40a4-cdef-1234567890ab, you would use https://habitica.com/api/v3/groups/12345678-90ab-40a4-cdef-1234567890ab
Some routes have more than one variable and all must be replaced, for example User - Hatch a pet is https://habitica.com/api/v3/user/hatch/:egg/:hatchingPotion
When variables refer to content types, you can find the appropriate values from the Content - Get all available content objects route (https://habitica.com/api/v3/content). For example, :egg could be TigerCub and :hatchingPotion could be CottonCandyBlue

Most of the API routes require a User ID and API Token for authentication, which you always add to the HTTP headers of the request (do not try specifying them in any other way) using the header keys x-api-user and x-api-key for your User ID and API token respectively (see below for examples).

If you will be using the API route in a script or other tool, or using it multiple times on the command line, you must also use an x-client header key. As described in the "X-Client Header" section in Guidance for Comrades, the value of that key should be your User ID and the name of your tool. If you haven't yet created a full tool but are just experimenting with the API, you can use a word like "Testing" instead of the name of your tool. It is important that you read Guidance for Comrades to learn more about using the X-Client header correctly.

How you add the x-api-user, x-api-key, and x-client headers to your API call depends on how you are making the requests.

For shell scripts, you might choose to use the curl command-line tool to send the HTTPS requests. If so, you would format the URL and authentication headers like this:

curl https://habitica.com/api/v3/user -s -X GET --compressed \
    -H "Content-Type:application/json" \
    -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing"

You can also choose httpie to make requests

http GET https://habitica.com/api/v3/user Content-Type:application/json x-api-user:12345678-90ab-416b-cdef-1234567890ab x-api-key:12345678-90ab-416b-cdef-1234567890ab x-client:12345678-90ab-416b-cdef-1234567890ab
-Testing

For JavaScript using a jQuery Ajax request, you could use code similar to this:

    $.ajax({
        url: 'https://habitica.com/api/v3/user',
        type: 'GET',
        dataType: 'json',
        cache: false,
        beforeSend: function(xhr){
                xhr.setRequestHeader('x-api-user', '12345678-90ab-416b-cdef-1234567890ab');
                xhr.setRequestHeader('x-api-key',  '12345678-90ab-416b-cdef-1234567890ab');
                xhr.setRequestHeader('x-client', '12345678-90ab-416b-cdef-1234567890ab-MyHabiticaApp');
            },
        success: yourFunctionToProcessTheData,
        error: yourFunctionToReportAnError,
    });

If you are allowing your script or tool to be used by other players, you will want to insert the x-api-user and x-api-key values into your API calls with variables that contain the User ID and API Token of the player who is using your tool. It is important to note that the x-client header should not contain the User ID of that player - it should always be your own User ID because you are the author of the tool. Refer to the "X-Client Header" section in Guidance for Comrades for more information about this, including sample code that uses variables.

Each API route uses one of the HTTP request methods, such as GET, POST, PUT, or DELETE, indicated by colored labels in the documentation. It's important to use the correct method in your code, because some API calls may have the same url but different request method. You can use type: 'GET' (as in the examples above) or method: 'get' to signify the request method. The different request methods use different mechanisms for specifying the variables and their values:

For GET requests, specify them in the query string. For example, https://habitica.com/api/v3/groups?type=party,guilds

For POST, PUT, and DELETE requests, specify information in body parameters. The method for doing this depends on how you are making the requests. For HTML forms, use form fields such as input and textarea. jQuery provides a jQuery.post() method. For curl, use the -d option:

curl -X POST -d "type=todo&text=New Task Text&notes=Some Notes" \
    -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \
    https://habitica.com/api/v3/tasks/user

curl -X PUT -d "text=Edited Task Text" \
    -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \
    https://habitica.com/api/v3/tasks/7d4a623d-0a2c-48e2-b9d9-feea1fa2d467

curl -X DELETE -d "password=yourPasswordGoesHere" \
    -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \
    https://habitica.com/api/v3/user

When data needs to be specified in an array or an object, use constructors with { ... } and [ ... ] such as in this example that creates a To Do with two tags and a checklist containing two items:

curl -X POST \
    -d '{
        "type": "todo",
        "text": "task title",
        "tags": [
            "12345678-90ab-416b-cdef-1234567890ab",
            "abcdef12-90ab-416b-cdef-1234567890ab"
        ],
        "checklist": [
            { "text": "1st checklist item", "completed": false },
            { "text": "2nd checklist item", "completed": false }
        ],
        "collapseChecklist": true
        }' \
    -H "Content-Type: application/json" \
    -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \
    https://habitica.com/api/v3/tasks/user

Responses and Error Messages from the API[]

Every request made to the API will result in a response with an HTTP status code and a body.

If the request was successful, there will be a 2xx status code and the body's success property will be set to true.

If the request failed, there will be a 4xx or 5xx status code, the body's success property will be set to false, and specific information about the error will be in the body's error and message properties. That is the only source of information about failures but it should contain everything you need to work out what went wrong.

If you need advice about errors, ask in the Aspiring Comrades guild. Post the exact API command that is failing (with your API Token removed!) and the full error message (omit any private information if necessary).

Tips[]

To find your number of Gems, use the /api/v3/user GET route and then find the data.balance value. Multiply it by 4 to get the number of gems. The balance is the US dollar equivalent of the number of Gems, where $1 is 4 Gems.

The Extensions, Add-Ons, and Customizations page has some tools that make using the API easier. They are listed in the "Current Apps and Extensions" table with "API" in the "Type" column.

Version 2 of the API[]

The information in this section pertains to version 2 of the API, which has been turned off and cannot be used. This information remains here only as a reference to assist you in upgrading existing tools to version 3 of the API.

Extensions and scripts could use Habitica's up/down scoring system for individual tasks. An example of an extension that leveraged this is the Chrome Extension, which up-scored you for visiting productive websites and down-scored you for visiting procrastination-related websites. Other examples of extensions and scripts that up-scored you for good behavior and down-scored you for bad behavior include various Pomodoro-related tools, the Anki Extension, and GitHabit.

For extensions and scripts, Habitica had a simple API for up-scoring and down-scoring third-party Habits. Programmers should have issued an HTTP POST to:

/api/v2/user/tasks/{id}/{direction}

{id} is a unique identifier for a task consisting of lowercase letters. Try to make it something simple and straightforward, like 'productivity' or 'fitness', because other services may piggy-back off your task. For example, the Chrome extension down-scores a 'productivity' task when you visit vice-related websites (reddit, 9gag, etc). However, Pomodoro up-scores 'productivity' when you complete a task. So the two services share a single task to score your overall productivity. If the task doesn't yet exist, it is created the first time you POST to this URL.
{direction} is 'up' or 'down'
A POST body consisting of the API token is required

For example, this applescript command coupled with a timer can record a + on a habit at regular intervals. Replace xxxxx with your User ID and API key. Change 'productivity' to whatever you want to call your habit.

do shell script "curl -X POST—compressed -H 'Content-Type:application/json' -H 'x-api-user: xxxxx' -H 'x-api-key: xxxxx' https://habitica.com/api/v2/user/tasks/productivity/up"

Version 1 of the API[]

Version 1 of the API has been turned off and cannot be used.