Application Programming Interface

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 API
On 21 May, 2016, version 3 of Habitica's API was released. All new third-party software should use it and all existing software should be updated to use it. Version 2 will continue to work until 15 July, 2016, but after that date, any software that still uses it will stop working.

Quick note about the version 3 API documentation: variable names are prefixed with a colon in the documentation as in :variableName. The entire string, colon and all, should be replaced.

The following resources exist to help you update any tools you have written or create new ones:
 * Habitica V3 API Documentation
 * The Forge - Habitica's official blog for Blacksmiths:
 * Overview of Changes in Version 3 of the API - the major differences between versions 2 and 3
 * API v2 -> v3 Migration Guide
 * API v2 Deprecation Notice
 * Aspiring Coders guild for asking questions and seeking help
 * Habitica's GitHub repository for assistance and reporting problems with the API (e.g., errors or confusing documentation)

Version 2 of the API
IMPORTANT: ''The information in this section pertains to version 2 of the API, which will be disabled on 15 July, 2016. You should not create new tools using version 2. This information remains here only as a reference to assist you in upgrading existing tools to version 3 of the API.''

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

For extensions and scripts, Habitica has a simple API for up-scoring and down-scoring third-party Habits. Programmers should issue an HTTP POST to: /api/v2/user/tasks/{id}/{direction} 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"
 * {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

Version 1 of the API
Version 1 of the API has been deprecated.