To-do Lists API Calls

Complete item

/todos/complete_item/#{id}

Marks the specified item as "complete". If the item is already completed, this does nothing.

Response

<todo-item>
  ...
</todo-item>

Create item

/todos/create_item/#{list_id}

This call lets you add an item to an existing list. The item is added to the bottom of the list. If a person is responsible for the item, give their id as the party_id value. If a company is responsible, prefix their company id with a 'c' and use that as the party_id value. If the item has a person as the responsible party, you can use the notify key to indicate whether an email should be sent to that person to tell them about the assignment.

XML Request

<request>
  <content>#{content}</content>

  <!-- if the item has a responsible party -->
  <responsible-party>#{party_id}</responsible-party>
  <notify>#{true|false}</notify>
<request>

YAML Request

---
content: #{content}

# if the item has a responsible party
responsible-party: #{party_id}
notify: #{true|false}

Response

<todo-item>
  ...
</todo-item>

Create list

/projects/#{project_id}/todos/create_list

This will create a new, empty list. You can create the list explicitly, or by giving it a list template id to base the new list off of.

XML Request

<request>
  <milestone-id>#{milestone_id}</milestone-id> <!-- optional -->
  <private>#{true|false}</private> <!-- optional -->
  <tracked>#{true|false}</tracked> <!-- enable/disable time tracking -->

  <!-- if created from explicit metadata -->
  <name>#{name}</name>
  <description>#{description}</description>

  <!-- if created by a template id -->
  <use-template>true</use-template>
  <template-id>#{template_id}</template-id>
</request>

YAML Request

---
milestone-id: #{milestone_id} # optional
private: #{true|false} # optional
tracked: #{true|false} # enable/disable time tracking, optional

# if created from explicit metadata
name: #{name}
description: #{description}

# if created by a template id
use-template: true
template-id: #{template_id}

Response

<todo-list>
  ...
</todo-list>

Delete item

/todos/delete_item/#{id}

Deletes the specified item, removing it from its parent list.

Response

<todo-item>
  ...
</todo-item>

Delete list

/todos/delete_list/#{id}

This call will delete the entire referenced list and all items associated with it. Use it with caution, because a deleted list cannot be restored!

Response

<todo-list>
  ...
</todo-list>

List

/todos/list/#{id}

This will return the metadata and items for a specific list.

Response

<todo-list>
  ...
  <todo-items>
    ...
  </todo-items>
</todo-list>

Lists

/projects/#{project_id}/todos/lists

This will return the metadata for all of the lists in a given project. You can further constrain the query to only return those lists that are "complete" (have no uncompleted items) or "uncomplete" (have uncompleted items remaining).

XML Request

<request>
  <complete>#{true|false}</complete> <!-- optional -->
</request>

YAML Request

---
complete: #{true|false} # optional

Response

<todo-lists>
  <todo-list>
    ...
  </todo-list>
  <todo-list>
    ...
  </todo-list>
  ...
</todo-lists>

Move item

/todos/move_item/#{id}

Changes the position of an item within its parent list. It does not currently support reparenting an item. Position 1 is at the top of the list. Moving an item beyond the end of the list puts it at the bottom of the list.

XML Request

<request>
  <to>#{to}</to>
<request>

YAML Request

---
to: #{to}

Response

<todo-list>
  ...
</todo-list>

Move list

/todos/move_list/#{id}

This allows you to reposition a list relative to the other lists in the project. A list with position 1 will show up at the top of the page. Moving lists around lets you prioritize. Moving a list to a position less than 1, or more than the number of lists in a project, will force the position to be between 1 and the number of lists (inclusive).

XML Request

<request>
  <to>#{to}</to>
</request>

YAML Request

---
to: #{to}

Response

<todo-list>
  ...
</todo-list>

Uncomplete item

/todos/uncomplete_item/#{id}

Marks the specified item as "uncomplete". If the item is already uncompleted, this does nothing.

Response

<todo-item>
  ...
</todo-item>

Update item

/todos/update_item/#{id}

Modifies an existing item. The values work much like the "create item" operation, so you should refer to that for a more detailed explanation.

XML Request

<request>
  <item>
    <content>#{content}</content>
  </item>

  <!-- if the item has a responsible party -->
  <responsible-party>#{party_id}</responsible-party>
  <notify>#{true|false}</notify>
<request>

YAML Request

---
item:
  content: #{content}

# if the item has a responsible party
responsible-party: #{party_id}
notify: #{true|false}

Response

<todo-item>
  ...
</todo-item>

Update list

/todos/update_list/#{id}

With this call you can alter the metadata for a list.

XML Request

<request>
  <list>
    <name>#{name}</name>
    <description>#{description}</description>
    <milestone-id>#{milestone_id}</milestone-id>
    <private>#{true|false}</private>
    <tracked>#{true|false}</tracked> <!-- enable/disable time tracking -->
  </list>
<request>

YAML Request

---
list:
  name: #{name}
  description: #{description}
  milestone-id: #{milestone_id}
  private: #{true|false}
  tracked: #{true|false}

Response

<todo-list>
  ...
</todo-list>