diff --git a/source/_integrations/habitica.markdown b/source/_integrations/habitica.markdown index e2c3976692d..db85c985a10 100644 --- a/source/_integrations/habitica.markdown +++ b/source/_integrations/habitica.markdown @@ -323,91 +323,6 @@ actions: {% enddetails %} -## API Service - -At runtime, you will be able to use the 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. - -### API Service Parameters - -The API is exposed to Home Assistant as an action called `habitica.api_call`. To call it, you should specify these keys in the data: - -| 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](https://habitica.com/apidoc/). | - -A successful run of this action will fire an event `habitica_api_call_success`. - -| Event data attribute | Type | Description | -| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | string | Copied from the data attribute. | -| `path` | [string] | Copied from the data attribute. | -| `data` | map | Deserialized `data` field of JSON object Habitica's server returned in response to API call. For more info see the [API documentation](https://habitica.com/apidoc/). | - -#### Let's consider some examples on how to use the action - -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](https://habitica.com/apidoc/#api-Task-CreateUserTasks) 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](https://github.com/ASMfreaK/habitipy/blob/master/README.md). -- The `args` key is more or less described in the [API documentation](https://habitica.com/apidoc/). - -Combining all together: -call `habitica.api_call` with data - -```json -{ - "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](/images/screenshots/habitica_new_task.png) - -Also an event `habitica_api_call_success` will be fired with the following data: - -```json -{ - "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"} -} -``` - ## Templating `sensor.habitica_USER_habits` and `sensor.habitica_USER_rewards` have state attributes listing the user's respective tasks. For example, you can see this information in **{% my developer_states title="Developer Tools > States" %}** under `sensor.habitica_USER_habits` > **Attributes**, or by adding a [Markdown card](/dashboards/markdown/) to a dashboard with the following code: