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)[edit | edit source]

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[edit | edit source]

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:

Errors in the API Documentation[edit | edit source]

As of January 2021, the Habitica V3 API Documentation contains a "Send a Sample Request" form under each route. These forms do not work. Refer to habitica Issue #13012 for more details.

If you find an error in the API documentation, including typos or misleading text, please report it in the Report a Bug guild. If you're not sure if it's an error or not, you can ask in the Aspiring Comrades guild.

Using the API[edit | edit source]

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

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 (e.g., see the type: 'GET' examples above). 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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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

Community content is available under CC-BY-SA unless otherwise noted.