API Reference

REST API Overview

flow supports a simple yet powerful REST API. You can send standard HTTP requests (GET, POST, PUT, DELETE) to read, add, update, and delete resources, respectively.

For example, to get the list of members on your board, you can send the following request: GET /members.format.

.format specifies the format of the output you would like to receive. It can be .json or .xml. The final request could be GET /members.json or GET /members.xml.

flow returns one of the following HTTP status codes for each request:

  • 200 OK
  • 400 Bad Request
  • 403 Permission Denied
  • 404 Not Found

Notes:

  • If you cannot send PUT or DELETE requests, you can use POST instead. Including a method parameter in your request, and setting it to "put" or "delete" will have the same effect.
  • All dates are in US Eastern time (GMT-5 or GMT-4 depending on daylight saving time).
  • Although flow outputs standard JSON, quotes and curly braces are omitted in the sample JSON listings in this document to make them easier to read. We call this light JSON format "JSON-L".




API Location and Authentication

The flow API can be reached at http://myboard.flow.io/api/version/

flow uses version numbers to ensure that no API client would break because of API changes. The API version will only change when there are changes to existing methods. The current version is v10.05

If your board's name is "midori", the location for the API would be http://midori.flow.io/api/v10.05/

You can send an X-Flow-Authentication header to authenticate your requests. The value of this header must be one of the authentication keys displayed in the interactive console.

Note: The first authentication key is special. It can be used to create new keys by using POST /authentication.format.





API Change History

June 28th, 2010: Added GET /project_id/tasks/recent_activity.format.

May 4th, 2010: First release.




Interactive Console

REST Console

The interactive console allows you test your REST API requests from inside flow.

There is no need to construct queries. You can directly enter requests like:

GET /task/2444.json


For non-GET requests, you can enter parameters in JSON format. For example:

POST /task.xml { user_id: 1, project_id: 1, task_text: "Test", task_type_id: 1 }





GET /members.format

Returns the list of all members on your board.

For example: GET /members.json

Sample Output
  • 1:
    • board_name   : midori
    • user_id      : 1
    • user_joined  : 2010-02-25 06:00:00
    • user_name    : Aycan Gulez
    • user_avatar  : http://files.flow.io/avatars/1-Aycan-Gulez.jpg
    • user_escaped : Aycan-Gulez
  • 23:
    • board_name   : midori
    • user_id      : 23
    • user_joined  : 2010-02-25 07:47:19
    • user_name    : Jim Hale
    • user_avatar  : http://files.flow.io/avatars/23-Jim-Hale.jpg
    • user_escaped : Jim-Hale
  • 2:
    • board_name   : midori
    • user_id      : 2
    • user_joined  : 2010-02-25 22:28:25
    • user_name    : Midori Kobayashi
    • user_avatar  : http://files.flow.io/avatars/default.gif
    • user_escaped : Midori-Kobayashi




GET /projects.format

Returns the list of all projects on your board.

For example: GET /projects.json

Sample Output
  • 16:
    • project_id    : 16
    • project_title : Simple Blog
    • project_order : 7.5
    • user_id       : 1
    • forum_id      : 16
    • col_id        : 2
  • 11:
    • project_id    : 11
    • project_title : Site
    • project_order : 6.5
    • user_id       : 1
    • forum_id      : 11
    • col_id        : 1
  • 1:
    • project_id    : 1
    • project_title : Software
    • project_order : 4.5
    • user_id       : 1
    • forum_id      : 1
    • col_id        : 1
  • 19:
    • project_id    : 19
    • project_title : Test
    • project_order : 2.5
    • user_id       : 1
    • forum_id      : 19
    • col_id        : 1

Notes:

  • If col_id is 2, it means the project is archived.
  • project_order is a floating point number used to define the sorting order of projects (in descending order).
  • user_id is the last user who made a change to the project (renaming, changing its order, etc.).




GET /project_id/cols.format

Returns the columns of a project.

For example: GET /1/cols.json

Sample Output
  • 1:
    • col_id     : 1
    • project_id : 1
    • col_title  : Backlog
    • col_type   : B
    • col_limit  : 0
    • col_order  : 4
    • num_tasks  : 12
    • user_id    : 0
  • 2:
    • col_id     : 2
    • project_id : 1
    • col_title  : To-do
    • col_type   :
    • col_limit  : 5
    • col_order  : 5
    • num_tasks  : 2
    • user_id    : 1
  • 3:
    • col_id     : 3
    • project_id : 1
    • col_title  : In-progress
    • col_type   :
    • col_limit  : 2
    • col_order  : 2
    • num_tasks  : 2
    • user_id    : 1
  • 4:
    • col_id     : 4
    • project_id : 1
    • col_title  : Done
    • col_type   : D
    • col_limit  : 0
    • col_order  : -1000
    • num_tasks  : 89
    • user_id    : 0

Notes:

  • col_type can be empty, "B" (Backlog), or "D" (Done).
  • col_limit is the Work In Progress (WIP) limit (0 for no limit).
  • col_order is a floating point number used to define the sorting order of columns (in descending order). Backlog always appears first regardless of the order.
  • num_tasks is the number of tasks in the column.
  • user_id is the last user who made a change on the column.




GET /project_id/task_types.format

Returns the task types of a project.

For example: GET /1/task_types.json

Sample Output
  • 1:
    • task_type_id    : 1
    • project_id      : 1
    • task_type_color : EEEE99
    • task_type_text  : Feature
    • task_type_order : 1
    • user_id         : 1
  • 6:
    • task_type_id    : 6
    • project_id      : 1
    • task_type_color : 77EE77
    • task_type_text  : Improvement
    • task_type_order : 0
    • user_id         : 1
  • 7:
    • task_type_id    : 7
    • project_id      : 1
    • task_type_color : EE9977
    • task_type_text  : Bug
    • task_type_order : -1
    • user_id         : 1

Notes:

  • task_type_color is an HTML RGB hex color value.
  • task_type_order is a floating point number used to define the sorting order of task types (in descending order).
  • user_id is the last user who made a change to the task type.




GET /project_id/tasks.format

Returns all tasks in a project.

Note: Only the first 50 tasks in the Done column are returned.

For example: GET /16/tasks.json

Sample Output
  • 2406:
    • task_id      : 2406
    • col_id       : 39
    • topic_id     : 2406
    • task_type_id : 24
    • task_text    : Delete article
    • task_status  :
    • task_order   : 16
  • 2407:
    • task_id      : 2407
    • col_id       : 39
    • topic_id     : 2407
    • task_type_id : 24
    • task_text    : Post comments to articles
    • task_status  :
    • task_order   : 15
  • 2408:
    • task_id      : 2408
    • col_id       : 39
    • topic_id     : 2408
    • task_type_id : 24
    • task_text    : Delete user comments
    • task_status  :
    • task_order   : 14
  • 2398:
    • task_id      : 2398
    • col_id       : 40
    • topic_id     : 2398
    • task_type_id : 24
    • task_text    : List articles
    • task_status  :
    • task_order   : 3
    • assignments:
      • 0 : 1
  • 2405:
    • task_id      : 2405
    • col_id       : 40
    • topic_id     : 2405
    • task_type_id : 24
    • task_text    : Edit article
    • task_status  :
    • task_order   : 2
  • 2411:
    • task_id      : 2411
    • col_id       : 41
    • topic_id     : 2411
    • task_type_id : 25
    • task_text    : Custom CSS
    • task_status  :
    • task_order   : 1
    • assignments:
      • 0 : 1
  • 2404:
    • task_id      : 2404
    • col_id       : 42
    • topic_id     : 2404
    • task_type_id : 24
    • task_text    : Add article
    • task_status  :
    • task_order   : 2
  • 2409:
    • task_id      : 2409
    • col_id       : 42
    • topic_id     : 2409
    • task_type_id : 24
    • task_text    : Create database
    • task_status  :
    • task_order   : 1

Notes:

  • task_order is a floating point number used to define the order of the task in its column.
  • task_status can be empty, "R" (Ready), "B" (Blocked), "D" (Deleted), or "U" (Undeleted).
  • assignments contains the ids of users assigned to this task.




GET /project_id/tasks/recent_activity.format

Returns all changes made to tasks within the last 24 hours, ordered from most recent to oldest.

If there are no changes, it returns 404 Not Found.

For example: GET /1/tasks/recent_activity.json

Sample Output
  • 1348:
    • change_made : 2009-12-24 05:56:28
    • change_type : T
    • change_content:
      • project_id   : 1
      • topic_id     : 2444
      • user_id      : 1
      • col_id       : 1
      • task_type_id : 1
      • task_text    : Archive projects
      • task_order   : 13
      • task_created : 2009-12-24 05:56:28
      • task_id      : 2444
    • project_id  : 1
    • item_id     : 2444
    • user_id     : 1
    • ip          : 127.0.0.1
    • change_id   : 1348
  • 1349:
    • change_made : 2009-12-24 05:56:39
    • change_type : T
    • change_content:
      • col_id         : 2
      • task_order     : 5
      • old_task_text  : Archive projects
      • old_task_order : 13
      • old_col_title  : To-do
    • project_id  : 1
    • item_id     : 2444
    • user_id     : 1
    • ip          : 127.0.0.1
    • change_id   : 1349

Notes:

  • change_content contains the fields changed by the user. You will see references to old_task_text often. This is used to preserve the task text at the time of the change.
  • user_id is the user who made the change.




GET /item_history/item_type/item_id.format

Returns the history of an item (task, task type, column, project, or user group).

Note: Valid item_type values are: "task", "task_type", "col", "project", and "group".

For example: GET /item_history/task/2444.json

Sample Output
  • 1348:
    • change_made : 2009-12-24 05:56:28
    • change_type : T
    • change_content:
      • project_id   : 1
      • topic_id     : 2444
      • user_id      : 1
      • col_id       : 1
      • task_type_id : 1
      • task_text    : Archive projects
      • task_order   : 13
      • task_created : 2009-12-24 05:56:28
      • task_id      : 2444
    • project_id  : 1
    • item_id     : 2444
    • user_id     : 1
    • ip          : 127.0.0.1
    • change_id   : 1348
  • 1349:
    • change_made : 2009-12-24 05:56:39
    • change_type : T
    • change_content:
      • col_id         : 2
      • task_order     : 5
      • old_task_text  : Archive projects
      • old_task_order : 13
      • old_col_title  : To-do
    • project_id  : 1
    • item_id     : 2444
    • user_id     : 1
    • ip          : 127.0.0.1
    • change_id   : 1349
  • 2018:
    • change_made : 2010-02-05 07:36:25
    • change_type : T
    • change_content:
      • col_id         : 1
      • task_order     : 21.5
      • old_task_text  : Archive projects
      • old_task_order : 5
      • old_col_title  : Backlog
    • project_id  : 1
    • item_id     : 2444
    • user_id     : 1
    • ip          : 127.0.0.1
    • change_id   : 2018
  • 2119:
    • change_made : 2010-03-24 06:58:25
    • change_type : T
    • change_content:
      • col_id         : 2
      • task_order     : 4
      • old_task_text  : Archive projects
      • old_task_order : 21.5
      • old_col_title  : To-do
    • project_id  : 1
    • item_id     : 2444
    • user_id     : 1
    • ip          : 127.0.0.1
    • change_id   : 2119
  • 2120:
    • change_made : 2010-03-24 07:17:11
    • change_type : T
    • change_content:
      • col_id         : 3
      • task_order     : 2
      • old_task_text  : Archive projects
      • old_task_order : 4
      • old_col_title  : In-progress
    • project_id  : 1
    • item_id     : 2444
    • user_id     : 1
    • ip          : 127.0.0.1
    • change_id   : 2120
  • 2162:
    • change_made : 2010-03-24 16:51:38
    • change_type : T
    • change_content:
      • col_id         : 4
      • task_order     : 84
      • task_completed : 2010-03-24 16:51:38
      • task_metrics:
        • phase_times:
          • 1 : 4054931
          • 2 : 3722312
          • 3 : 34467
        • idle_times:
          • ready   : 0
          • blocked : 0
        • cycle_time         : 7811710
        • working_cycle_time : 3756779
      • old_task_text  : Archive projects
      • old_task_order : 2
      • old_col_title  : Done
    • project_id  : 1
    • item_id     : 2444
    • user_id     : 1
    • ip          : 127.0.0.1
    • change_id   : 2162

Notes:

  • change_content contains the fields changed by the user. You will see references to old_task_text often. This is used to preserve the task text at the time of the change.
  • user_id is the user who made the change.




GET /task/task_id.format

Returns information about a task.

For example: GET /task/2444.json

Sample Output
  • task_id        : 2444
  • project_id     : 1
  • user_id        : 1
  • col_id         : 4
  • task_type_id   : 1
  • task_text      : Archive projects
  • task_order     : 84
  • task_created   : 2009-12-24 05:56:28
  • task_completed : 2010-03-24 16:51:38
  • task_status    :
  • task_metrics:
    • phase_times:
      • 1 : 4054931
      • 2 : 3722312
      • 3 : 34467
    • idle_times:
      • ready   : 0
      • blocked : 0
    • cycle_time         : 7811710
    • working_cycle_time : 3756779
  • topic_id       : 2444

Notes:

  • user_id is the last user who made a change to the task.
  • col_id is the column the task is currently in.
  • task_order is a floating point number used to define the order of the task in its column.
  • task_status can be empty, "R" (Ready), "B" (Blocked), "D" (Deleted), or "U" (Undeleted).
  • task_metrics contains information about the time spent in each phase (column), any idle time (ready/blocked), and cycle/working cycle time calculated from these data. All metrics times are in seconds.




POST /task.format

Adds a new task and returns its id.

Accepts the following parameters (all required):

user_id User adding the task (must be a board member)
project_id Task's project
task_text Text of the task
task_type_id Type of the task

For example, try entering the following in the flow console (with an appropriate task_type_id and project_id):

POST /task.json { user_id: 1, project_id: 1, task_text: "Test", task_type_id: 1 }

Sample Output
  • task_id : 2569




POST /authentication.format

Adds a randomly generated authentication key. There is a limit of 10 keys.

Only the first authentication key displayed in the console can be used to create additional keys for security reasons.

For example: POST /authentication.json

Sample Output
  • authentication_key : b2401f37986bc90fb0cc




PUT /task/task_id.format

Edits a task, and returns which properties have changed.

Accepts the following parameters (user_id is required; you must also provide at least one other parameter):

user_id User editing the task (must be a board member)
task_text Text of the task
task_type_id Type of the task
task_status Can be empty, "R" (Ready), "B" (Blocked), "D" (Deleted), or "U" (Undeleted)
user_ids Comma separated ids of board members to assign this task to
col_id New column id
prev_task_order The order of the task before this one (use "none" to move to the top)

For example, the following request (with an appropriate task_id and user_id) will set the task's text to "Evolved" and its status to "Ready":

PUT /task/2569.json { user_id: 1, task_text: "Evolved", task_status: "R" }

Sample Output
  • task_id     : 2569
  • user_id     : 1
  • task_text   : Evolved
  • task_status : R




DELETE /task/task_id.format

Marks a task as deleted.

Accepts the following parameter (required):

user_id User deleting the task (must be a board member)

For example, try entering the following in the flow console (with an appropriate task_id and user_id): DELETE /task/2572.json { user_id: 1 }

Sample Output
  • task_id     : 2572
  • user_id     : 1
  • task_status : D




DELETE /authentication/key.format

Deletes an authentication key.

For example: DELETE /authentication/b2401f37986bc90fb0cc.json

Sample Output
  • authentication_key : b2401f37986bc90fb0cc




© 2010-11 Aycan Gulez