Taskforce API (Version 1)

Overview

Version 1 of the Taskforce API is brand new and currently in beta testing. It should be easy to get up and running, but if you run into any problems then email us.

The API consists of HTTP endpoints accessed via GET and POST. SSL is required, so make sure to use https instead of http.

Authentication

We require basic HTTP authentication for almost every call. The user's email address serves as the username, and the user's API key serves as the password.

Note: Some browsers don't allow the use of the "@" symbol during basic HTTP authentication, which obviously conflicts with using an email address as a username. In order to get around this issue, you can send "(at)" in place of "@". For example, a user with email "test@test.com" can be authenticated with the username "test(at)test.com".

Responses

Responses will be in XML format by default, or JSON if ".json" is added to the endpoint. For example, /api/v1/user.json will return a JSON response, and /api/v1/user will return an XML response (as will /api/v1/user.xml).

Note that XML responses will always be wrapped in a <response> stanza. Also, any underscores that appear in a JSON attribute name (api_key: "12345") will be hyphens in the XML version of the response (<api-key>12345</api-key>).

Libraries

We've developed a PHP library for accessing the API, and are working on libraries in other languages as well. If you'd like to see a library, or if you've written one of your own, let us know!

User

Create User

POST /api/v1/user.json

Creates an account for a new Taskforce user.

example response ▼ 
{
  success: true,
  api_key: "new user's API key"
}

Get User

GET /api/v1/user.json

Retrieves information about the user.

example response ▼ 
{
  success: true,
  user: {
    name: "John Doe",
    email: "johndoe@test.com",
    created: "2010-11-23 17:04:20 -0800",
    service: "Google Apps",
    api_key: "user's API key"
  }
}

Tasks

Get Tasks

GET /api/v1/tasks.json

Retrieves all tasks that belong to the user.

example response ▼ 
{
  success: true,
  tasks: [
    {
      id: 23416,
      user_id: id of the user who created the task,
      owner: was task created by the authenticated user?,
      name: "file the TPS reports",
      seen: has the task been seen in the Taskforce widget?,
      due_at: "12/02/2010",
      completed_at: "12/01/2010",
      delayed_until: "11/30/2010",
      created: "2010-11-23 17:04:20 -0800",
      modified: "2010-11-23 17:04:20 -0800",
      lists: [
        {
          id: 125
        },
        ...
      ],
      collaborators: [
        {
          email: "johndoe@test.com"
        },
        ...
      ],
      emails: [
        {
          sender: "johndoe@test.com",
          subject: "read this report and get back to me",
          gmail_thread_id: "Gmail thread id of the email",
        },
        ...
      ]
    },
    ...
  ]
}

Create Task

POST /api/v1/tasks.json

Creates a new task.

Required parameters: name, list_id

Optional parameters: details

example response ▼ 
{
  success: true,
  task_id: id of the new task
}

Get Task

GET /api/v1/tasks/:id.json

Retrieves a single task.

Required parameters: id

example response ▼ 
{
  success: true,
  task: {
    id: 24572,
    user_id: id of the user who created the task,
    owner: was task created by the authenticated user?,
    name: "file the TPS reports",
    seen: has the task been seen in the Taskforce widget?,
    due_at: "12/02/2010",
    completed_at: "12/01/2010",
    delayed_until: "11/30/2010",
    created: "2010-11-23 17:04:20 -0800",
    modified: "2010-11-23 17:04:20 -0800",
    lists: [
      {
        id: 2347
      },
      ...
    ],
    collaborators: [
      {
        email: "johndoe@test.com"
      },
      ...
    ],
    emails: [
      {
        sender: "johndoe@test.com",
        subject: "read this report and get back to me",
        gmail_thread_id: "Gmail thread id of the email",
      },
      ...
    ]
  }
}

Update Task

POST /api/v1/tasks/:id.json

Updates the task's attributes. Only the attributes specified will be changed.

Required parameters: id

Optional parameters: name, details

example response ▼ 
{
  success: true
}

Count Tasks

GET /api/v1/tasks/count.json

Returns the number of tasks belonging to the user broken down into the following categories: active, complete, delayed, unseen, and total. (Note that the total is just the sum of active, complete, and delayed.)

example response ▼ 
{
  success: true,
  task_counts: {
    total: 100,
    active: 50,
    complete: 25,
    delayed: 25,
    overdue: 10,
    unseen: 3
  }
}

Add Collaborator

POST /api/v1/tasks/:id/add_collaborator.json

Adds a collaborator to the task.

Required parameters: email

example response ▼ 
{
  success: true
}

Remove Collaborator

POST /api/v1/tasks/:id/remove_collaborator.json

Removes a collaborator from the task.

Required parameters: email

example response ▼ 
{
  success: true
}

Complete Task

POST /api/v1/tasks/:id/complete.json

Marks the task as complete.

example response ▼ 
{
  success: true
}

Uncomplete Task

POST /api/v1/tasks/:id/uncomplete.json

Marks the task as incomplete.

example response ▼ 
{
  success: true
}

Set Due Date

POST /api/v1/tasks/:id/set_due_date.json

Sets a due date for the task. Note the date should be in the format "MM/DD/YYYY".

Required parameters: date

example response ▼ 
{
  success: true,
  date: "03/22/2012"
}

Set Start Date

POST /api/v1/tasks/:id/set_start_date.json

Sets a start date for the task. (This is refered to as the "delay date" by the main Taskforce application.) Note the date should be in the format "MM/DD/YYYY".

Required parameters: date

example response ▼ 
{
  success: true,
  date: "03/22/2012"
}

Add To List

POST /api/v1/tasks/:id/add_to_list.json

Adds the task to the specified list.

Required parameters: list_id

example response ▼ 
{
  success: true
}

Remove From List

POST /api/v1/tasks/:id/remove_from_list.json

Removes the task from the specified list.

Required parameters: list_id

example response ▼ 
{
  success: true
}

Add Comment

POST /api/v1/tasks/:id/add_comment.json

Adds a comment to the task. Note that comments are individual chat-like messages.

Required parameters: comment

example response ▼ 
{
  success: true
}

Add Email

POST /api/v1/tasks/:id/add_email.json

Connects the task to an email.

Required parameters: gmail_thread_id

Optional parameters: subject, sender

example response ▼ 
{
  success: true
}

Remove Email

POST /api/v1/tasks/:id/remove_email.json

Disconnects an email from the task.

Required parameters: gmail_thread_id

example response ▼ 
{
  success: true
}

Delete Task

POST /api/v1/tasks/:id/delete.json

Deletes the task.

example response ▼ 
{
  success: true
}

Lists

Get Lists

GET /api/v1/lists.json

Retrieves all of the user's lists.

example response ▼ 
{
  success: true,
  lists: [
    {
      id: 512,
      name: "Business Tasks",
      description: "Tasks that have to do with business",
      flagship: is this the user's default (un-deletable) list?,
      added_by: id of user who created the list,
      created: "2010-11-23 17:04:20 -0800",
      modified: "2010-11-23 17:04:20 -0800",
      collaborators: [
        {
          email: "email of someone collaborating on the list"
        },
        ...
      ],
      task_counts: {
        total: 100,
        active: 50,
        complete: 25,
        delayed: 25,
        overdue: 10,
        unseen: 3
      }
    },
    ...
  ]
}

Create List

POST /api/v1/lists.json

Creates a new list.

Required parameters: name

Optional parameters: description

example response ▼ 
{
  success: true,
  list_id: id of the new list
}

Get List

GET /api/v1/lists/:id.json

Retrieves the specified list.

example response ▼ 
{
  success: true,
  list: {
    id: 512,
    name: "Business Tasks",
    description: "Tasks that have to do with business",
    flagship: is this the user's default (un-deletable) list?,
    added_by: id of user who created the list,
    created: "2010-11-23 17:04:20 -0800",
    modified: "2010-11-23 17:04:20 -0800",
    collaborators: [
      {
        email: "email of someone collaborating on the list"
      },
      ...
    ],
    task_counts: {
      total: 100,
      active: 50,
      complete: 25,
      delayed: 25,
      overdue: 10,
      unseen: 3
    }
  }
}

Update List

POST /api/v1/lists/:id.json

Updates the list's attributes. Only the attributes specified will be changed.

Required parameters: name and/or description

example response ▼ 
{
  success: true
}

Get Tasks

GET /api/v1/lists/:id/tasks.json

Retrieves all tasks that belong to the list.

example response ▼ 
{
  success: true,
  tasks: [
    {
      id: 23416,
      user_id: id of the user who created the task,
      owner: was task created by the authenticated user?,
      name: "file the TPS reports",
      seen: has the task been seen in the Taskforce widget?,
      created: "2010-11-23 17:04:20 -0800",
      modified: "2010-11-23 17:04:20 -0800",
      lists: [
        {
          id: 125
        },
        ...
      ],
      collaborators: [
        {
          email: "johndoe@test.com"
        },
        ...
      ],
      emails: [
        {
          sender: "johndoe@test.com",
          subject: "read this report and get back to me",
          gmail_thread_id: "Gmail thread id of the email",
        },
        ...
      ]
    },
    ...
  ]
}

Reorder Tasks

POST /api/v1/lists/:id/reorder_tasks.json

Rearrange the tasks in the list (they'll appear in the same order that they're specified in the array passed to this method). Only active (not completed, not delayed, not deleted) tasks will be reordered. Any active tasks that are part of the list but aren't included in the parameters will be added to the end.

Required parameters: task_ids

example response ▼ 
{
  success: true
}

Add Collaborator

POST /api/v1/lists/:id/add_collaborator.json

Adds a collaborator to the list.

Required parameters: email

example response ▼ 
{
  success: true
}

Remove Collaborator

POST /api/v1/lists/:id/remove_collaborator.json

Removes a collaborator from the list.

Required parameters: email

example response ▼ 
{
  success: true
}

Delete List

POST /api/v1/lists/:id/delete.json

Deletes a list. Any tasks that are part of a deleted list will be deleted as well (unless they also belong to other lists).

example response ▼ 
{
  success: true
}