Create and Update Examples

Creating Items Examples (POST)

Example: Add a task

To create a task, you:

  1. POST to the /tasks resource of the workspace
  2. With a parameter named “task” whose value is a hash of task attributes
  3. With task attributes including at least “name” parameter.

Supposing we want to add a task “learn the API”:

% curl -d 
'{"task": {"name": "learn the API"}}' -X POST
  "name": "learn the API",
  "id":   79104 
Status: 201

If you get an error here, double-check that you’ve set the Content-Type of your request to application/json using your curl configuration file.

When creating a task, you can add optional parameters besides "name", for example:

% curl -d 
'{"task": {"name":"learn the API", "parent_id":"12345", "assignments":
[{"person_id":121212,"estimate":{"low":2.25,"high":3.0}}]}}'-X POST

Example: Comment on a Task

To create a comment, you:

  1. POST to the …/comments resource of an item
  2. With a parameter named “comment” whose value is a hash of comment attributes
  3. With an attribute “comment” in the hash whose value is the text of the comment

Supposing we want to comment “working on it…” on our task “learn the API”:

% curl -d '{"comment": {"comment": "working on it…"}}' -X POST
  "comment": "working on it...",
  "id":       10941,
  "type":     "Comment",
  "item_id":  79104,
Status: 201

Updating Items Examples (PUT)

Example: Mark a task done (update a task)

To update a task, use the PUT HTTP method and specify the task ID.

% curl -X PUT -d '{"task": {"is_done": true}}'
  "name":    "learn the API",
  "id":      79104,
  "is_done": true,
Status: 200

Example: Update Custom Fields

You can configure existing custom fields for your projects and tasks. The custom fields for a given item are returned as a hash, and are settable in the same way.

Suppose you have a custom field “Urgency” with values of “High” and “Low”. Then if you get a task whose Urgency is High, you will see:


and you can change the Urgency to Low with a PUT that includes:


as one of the attributes.

To clear a custom field value, just use empty quotes for the value, for example:

% curl -X PUT -d '{"task":{"custom_field_values":{"Urgency":""}}}'