API Documentation

This describes how to access the official Taskk API. Please contact us if you need any assistance.

API documentation examples use HTTPIE.

Access

All API access is over HTTPS, and accessed from the api.taskk.it domain. All data is sent and received as JSON.



Parameters

All parameters for GET requests may be passed as an HTTP query parameter.

Example:
http GET https://api.taskk.it/v1/tasks/?complete=true&token=abc123 

All parameters (with the exception of token) for POST/PUT requests must be encoded in JSON and passed within the specified object.

Example:
http POST https://api.taskk.it/v1/lists/?token=abc123 list:='{"title":"test", "description":"desc"} 

Authentication


Access to the Taskk API is through your API Key. Your API Key can be generated and reset from api.taskk.it and must be a parameter to each request you make. You can test your access to the API by sending a GET request to /v1/auth/ping

http GET https://api.taskk.it/v1/auth/ping\?token=API_KEY_HERE

If your token is valid you will receive "pong" back from the API.

{"message":"pong"}

Example on jsFiddle!


Login

You can retrieve the users API key by logging in via HTTP Basic. You can then store the key and use it for all subsequent requests.

http -a username:password POST https://api.taskk.it/v1/auth/login

Returns:

token


Tasks

This section shows how you retrieve, create and edit your tasks via the API.


Get all of your tasks

GET https://api.taskk.it/v1/tasks/

Optional parameters:

  • completed True/False. Default: false.
  • list_id Integer. Get tasks only from a specific list.

Returns:

id, estimate, list_id, tags, position, completed and title for each task.


Get a specific task

GET https://api.taskk.it/v1/tasks/:id

Returns:

id, estimate, list_id, tags, position, completed and titlefor that task.


Create a new task

POST https://api.taskk.it/v1/tasks/

Required parameters:

Parameters encoded in JSON object: task.

  • title Name of the task.
  • estimate Length of the task (4h = 4 hours. 15m = 15 minutes).
  • list_id ID of the list that this task will belong to.
  • tags (optional)
Example:
http POST https://api.taskk.it/v1/lists/1 token=abcd task:='{"title":"test", "estimate":"5m","list_id":1,"tags":["tag1","tag2"]}'

Returns:

id and a success message confirming your new task.


Edit a task

PUT https://api.taskk.it/v1/tasks/:id

Optional parameters:encoded in JSON object: task.

  • title Name of the task.
  • estimate Length of the task (4h = 4 hours. 15m = 15 minutes).
  • list_id ID of the list that this task will belong to.
  • tags
Example:
http PUT https://api.taskk.it/v1/lists/1 token=abcd task:='{"title":"test","tags":["new tag","tag2"]}'


Returns:

id, estimate, list_id, tags, completed and title for that task.


Complete a task

PUT https://api.taskk.it/v1/tasks/:id/complete

Returns:

the completed task.


Delete a task

DELETE https://api.taskk.it/v1/tasks/:id

Returns:

message confirming the task has been deleted.


Lists

This section shows how you retrieve, create and edit your lists via the API.


Get all of your lists

GET https://api.taskk.it/v1/lists/

Returns:

id, title, description, position(priority), color, icon, parent_task_id, tags, completed_percentage, and tasks_count, for each list.


Get a specific list

GET https://api.taskk.it/v1/lists/:id

Returns:

id, title, description, color, tags, percentage_completed, and tasks_count, for the specified list.


Prioritize lists

Changes the order of a users lists

PUT https://api.taskk.it/v1/lists/sort

Required Parameters:

  • lists array of lists ID's in order of position. Order is top to bottom.
Example:
/lists/sort?lists[]=123&lists[]=124&lists[]=111

Example:
http --verbose PUT https://api.taskk.it/v1/lists/sort token=123 lists:='[123,124,111]'

This would put task 123 at the top of your list and 111 at the bottom.

Returns:

message confirming the lists have been sorted.


Prioritize tasks

Changes the order of tasks within a list.

PUT https://api.taskk.it/v1/lists/:id/sort

Required Parameters:

  • tasks array of task ID's in order of position. Order is top to bottom.
Example:
/lists/:id/sort?tasks[]=3347&tasks[]=2348&tasks[]=5671

Example:
http --verbose PUT https://api.taskk.it/v1/lists/1/sort token=123 tasks:='[3347,2348,5671]'

This would put task 3347 at the top of your list and 5671 at the bottom.

Returns:

id, message for the sorted list.


Create a new list

POST https://api.taskk.it/v1/lists/

Parameters: submit JSON object list with the following parameters

  • title Name of the list.
  • color Hexidecimal color of the list (optional)
  • description(optional)
  • tags

Note: Tags are an array of strings.

Example:

http POST https://api.tassk.it/v1/lists/ token=abcd list:='{"title":"test", "tags":["tag1","tag2"]}'

Returns:

id and a success message confirming your new list.


Edit a list

PUT https://api.taskk.it/v1/lists/:id

Optional parameters encoded in JSON object: list.

  • title Name of the list.
  • color Hexidecimal color of the list.
  • description
  • tags

Note: Tags are an array of strings. To pass an array in a URL, do the following.


Example:
http --verbose PUT https://api.taskk.it/v1/lists/1 token=abcd list:='{"title":"test","tags":["tag1","tag2"]}

Returns:

id, title , color , tags , description for that list.


Delete a list

DELETE https://api.taskk.it/v1/lists/:id

Note: Also deletes all tasks belonging to the list.

Returns:

message confirming the list has been deleted.


Planner

The Brain (aka The Planner) is the algorithm that plans your workload for you. This section shows how to retrieve and update your plans.


Update your planner

POST https://api.taskk.it/v1/planner/update

Notes: This starts the planning algorithm. It takes all of your lists/tasks and populates them in your planner. The planner can take anywhere from 1-3 seconds to run depending on the number of tasks you have and current load on our servers.

Rate Limit: You can only update the planner once a minute.

Returns:

  • message
  • time Time the planner started.

Get all of your planned tasks.

GET https://api.taskk.it/v1/planner/

Returns:

  • id
  • mins Length of the task in minutes.
  • planned_for Date the task is planned for.
  • completed True/False.
  • day_position Position within the day that the task was planned.
  • list_id ID of the list the task belongs to.
  • list_title Title of the list the task belongs to.
  • priority Priority of the task.
  • estimate Length estimate of the task as entered by the user (15m, 4h).

Get plans for a specific day

GET https://api.taskk.it/v1/planner/:date

Required parameter:

  • date Format: YYYY-M-D

Returns:

  • id
  • mins Length of the task in minutes.
  • planned_for Date the task is planned for.
  • completed True/False.
  • day_position Position within the day that the task was planned.
  • list_id ID of the list the task belongs to.
  • list_title Title of the list the task belongs to.
  • priority Priority of the task.
  • estimate Length estimate of the task as entered by the user (15m, 4h).

Get the last time the planner was updated

GET https://api.taskk.it/v1/planner/update

Returns:

  • id
  • time Time the planner algorithm was last run.

Taskk.js

Using JavaScript? Use taskk.js to jumpstart your use of the taskk API. Available on Github.


Need more?

Contact us! We'd love to help!