If your local install was made before 24 April 2018, the database needs to be updated. See the "Updating Your Local Install" section in Using Your Local Install to Modify Habitica's Website and API

API - User ID

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 3 of the APIEdit

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 DocumentationEdit

If you find errors in the API documentation, report them in the Report a Bug guild or submit a pull request for them. You can expect them to be fixed quickly, but it might take a few days before we can deploy the fix to the website.

Current known errors are documented at habitica Issue #10943 .

Using the APIEdit

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. How to add them to the headers 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 -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"
  • For JavaScript using a jQuery Ajax request, you could use code similar to this:
            url: '',
            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');
            success: yourFunctionToProcessTheData,
            error: yourFunctionToReportAnError,

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,,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 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"
    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"
    curl -X DELETE -d "password=yourPasswordGoesHere" -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab"
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 -H "Content-Type: application/json" -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 "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab"

Version 2 of the APIEdit

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:

  • {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'"

Version 1 of the APIEdit

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

Start a Discussion Discussions about Application Programming Interface