Habitica


This component allows you to monitor and manage your Habitica profile. This component exposes the Habitica’s API as a Home Assistant service. It supports multiple users and allows you to automate checking out your habits and daily tasks or casting magics using Home Assistant. This component enables usage of sensor.habitica platform. To use the component you should use this example configuration:

# Minimum viable configuration.yaml entry
habitica:
  - api_user: YOUR_USER_ID
    api_key: YOUR_API_KEY

You can specify several users, providing api_user and api_key for each. At runtime you will be able to use API for each respective user by their Habitica’s username. You can override this by passing name key, this value will be used instead of the username. If you are hosting your own instance of Habitica, you can specify a URL to it in url key.

Configuration Variables

api_user

(string)(Required)Habitica’s API user ID. This value can be grabbed from account setting

api_key

(string)(Required)Habitica’s API password (token). This value can be grabbed from account setting by pressing ‘Show API token’

name

(string)(Optional)Override for Habitica’s username. Will be used for service calls

Default value: Deduced at startup

url

(string)(Optional)URL to your Habitica instance, if you are hosting your own

Default value: http://habitica.com

sensors

(list)(Optional)List of sensors to generate for this user. If you don’t specify this entry then the default (all sensors) will be generated. If you specify this entry empty then no sensors will be generated.

Default value: all (name, hp, maxHealth, mp, maxMP, exp, toNextLevel, lvl, gp, class)

API Service Parameters

The API is exposed to Home Assistant as a service called habitica.api_call. To call it you should specify this keys in service data:

Service data attribute Required Type Description
name yes string Habitica’s username as per configuration.yaml entry.
path yes [string] Items from API URL in form of an array with method attached at the end. See the example below.
args no map Any additional json or url parameter arguments. See the example below and apidoc.

A successful call to this service will fire an event habitica_api_call_success.

Event data attribute Type Description
name string Copied from service data attribute.
path [string] Copied from service data attribute.
data map Deserialized data field of JSON object Habitica’s server returned in response to api call. For more info see docs.

Let’s consider some examples on how to call the service.

For example, let’s say that there is a configured habitica platform for user xxxNotAValidNickxxx with their respective api_user and api_key. Let’s create a new task (a todo) for this user via Home Assistant. There is an API call for this purpose. To create a new task one should hit https://habitica.com/api/v3/tasks/user endpoint with POST request with a json object with task properties. So let’s call the API on habitica.api_call.

  • The name key becomes xxxNotAValidNickxxx.
  • The path key is trickier.
    • Remove ‘https://habitica.com/api/v3/’ at the beginning of the endpoint URL.
    • Split the remaining on slashes (/) and append the lowercase method at the end.
    • You should get ["tasks", "user", "post"]. To get a better idea of the API you are recommended to try all of the API calls in IPython console using this package.
  • The args key is more or less described in the docs.

Combining all together: call habitica.api_call with data

{
  "name": "xxxNotAValidNickxxx",
  "path": ["tasks", "user", "post"],
  "args": {"text": "Use API from Home Assistant", "type": "todo"}
}

This call will create a new todo on xxxNotAValidNickxxx’s account with text Use API from Home Assistant like this:

example task created

Also an event habitica_api_call_success will be fired with the following data:

{
  "name": "xxxNotAValidNickxxx",
  "path": ["tasks", "user", "post"],
  "data": {
    "challenge": {},
    "group": {"approval": {"required": false,
     "approved": false,
     "requested": false},
    "assignedUsers": [],
    "sharedCompletion": "recurringCompletion"},
    "completed": false,
    "collapseChecklist": false,
    "type": "todo",
    "notes": "",
    "tags": [],
    "value": 0,
    "priority": 1,
    "attribute": "str",
    "text": "Use API from Home Assistant",
    "checklist": [],
    "reminders": [],
    "_id": "NEW_TASK_UUID",
    "createdAt": "2018-08-09T18:03:27.759Z",
    "updatedAt": "2018-08-09T18:03:27.759Z",
    "userId": "xxxNotAValidNickxxx's ID",
    "id": "NEW_TASK_UUID"}
}