API

##Two API Types HabitRPG's API is meant for two different audiences: (1) extensions & scripts, and (2) full-fledged applications. Extensions & scripts can utilize Habit's up/down scoring for individual tasks. An example of this in action is the Chrome Extension, which up-scores you for visiting productive websites, and down-scores you for visiting procrastination websites. Other examples currently in use are Pomodoro, Anki, and Github scripts - which up-score you for good behavior and downscore you for bad behavior - see the list. The second API consumer is for full-fledge applications, which need read / write access to the entire user document. An example of this would be an iPhone App or Desktop application.

##Extensions / Scripts HabitRPG has a simple API for up-scoring and down-scoring third party Habits: POST /v1/users/:userId/tasks/:taskId/:direction (apiToken required).

####Example

curl -X POST -H "Content-Type:application/json" -d '{"apiToken":"{TOKEN}"}' localhost:3000/v1/users/{UID}/tasks/productivity/up

• POST to the URL /v1/users/:userId/tasks/:taskId/:direction
  • :userId is your user-id
  • :direction is 'up' or 'down'
  • :taskId is a unique identifier for a task, which you make up, consisting of lowercase letters. Try to make it something common, 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 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.
  • apiToken (POST body) required

##Full API All API requests should be prefaced by https://habitrpg.com. Every authenticated request should include two headers. Your api key (x-api-key) and your user id (x-api-user). Do not include {} braces in your header (-H 'x-api-user: a94b6d9d-6b64-43ae-856c-2c3f211bd426') For example:

curl --compressed -H "Content-Type:application/json" \
  -H 'x-api-user: {user id}' \
  -H 'x-api-key: {api token}' \
  https://habitrpg.com/api/v1/user

Keep in mind, everything at habitrpg is in real-time. The API is no exception. Open up a browser at https://habitrpg.com – now execute the following curl command to create a new todo.

curl -X POST --compressed -H "Content-Type:application/json" \
  -H 'x-api-user: {user id}' \
  -H 'x-api-key: {api token}' \
  -d '{"text":"from the api!","type":"todo"}' \
  https://habitrpg.com/api/v1/user/task

You'll see it show up in your browser immediately!

Example response from above:

{
    "text": "from the api!",
    "type": "todo",
    "completed": false,
    "id": "7f4814d8-7a46-4eaa-a024-5f0b70178d05"
}

GET

• /api/v1/status - Returns { "status": "up" } if all is well.
  • Requires no special options
• /api/v1/user - (get user status)
  • x-api-user: uid
  • x-api-key: api token
• /api/v1/user/tasks
  • x-api-user: uid
  • x-api-key: api token
  • type: habit | daily | todo | reward (optional)
  • Eg: /api/v1/user/tasks?type=habit
• /api/v1/user/task/:id - (get task)
  • x-api-user: uid
  • x-api-key: api token

POST

• /api/v1/user/task - (create new task)

  • x-api-user: uid
  • x-api-key: api token
  • type: habit | daily | todo | reward (required)
  • text: This is an example title (required)
  • value: 0 (required or bad things will happen upon upping/downing)
  • notes: This is just a simple note (optional)
  • completed: false (optional, defaults to false)
  • up: true | false (optional, defaults to true)
  • down: true | false (optional, defaults to true)

• /api/v1/user/tasks/:task/:direction

  • x-api-user: uid
  • x-api-key: api token
  • :task is the task ID.
  • :direction is either up or down
  • Note: Despite this being a POST, the request body should be empty.
  • Note: This route will be shortly moved to /api/v1/user/task/:task/:direction (ie 'task' not 'tasks')

PUT

PUT updates a task. All JSON fields are optional, and existing task values will be used if no new values are supplied.

• /api/v1/user/task/:id - (update task)
  • x-api-user: uid
  • x-api-key: api token
  • type: habit | daily | todo | reward
  • text: This is an example title
  • value: 0
  • notes: This is just a simple note
  • completed: false
  • up: true | false
  • down: true | false

DELETE

• /api/v1/user/task/:id - (delete task)
  • x-api-user: uid
  • x-api-key: api token

curl -X DELETE --compressed -H "Content-Type:application/json" \
  -H "x-api-user: {USER_ID}" \
  -H "x-api-key: {API_TOKEN}" \
  https://habitrpg.com/api/user/task/{TASK_ID}

Responds with 204 No Content

Note, this is all subject to change. The API is not perfect, and should be used with caution. Please let us know if you have any issues.