AgileZen API Documentation

Tasks

Task Endpoints

List tasks within a story

GET https://agilezen.com/api/v1/projects/{projectid}/stories/{storyid}/tasks

Retrieves the list of tasks from the specified story.

Requires Read access to the project.
Supports: Enrichments, Filters, Pagination

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 4,
  "items": [
    {
      "id": 1,
      "text": "Get George Michael to help",
      "createTime": "2011-02-17T20:01:40",
      "finishTime": "2011-02-17T20:03:17",
      "finishedBy": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "status": "incomplete"
    },
    {
      "id": 2,
      "text": "Try to get Gob to help",
      "createTime": "2011-02-17T20:01:49",
      "status": "incomplete"
    },
    {
      "id": 3,
      "text": "Only build exterior walls",
      "createTime": "2011-02-17T20:02:00",
      "status": "incomplete"
    },
    {
      "id": 9,
      "text": "this is a test 2",
      "createTime": "2011-02-18T17:12:30",
      "status": "incomplete"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<tasks>
  <items>
    <task>
      <createTime>2011-02-17T20:01:40</createTime>
      <finishTime>2011-02-17T20:03:17</finishTime>
      <finishedBy>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </finishedBy>
      <id>1</id>
      <status>incomplete</status>
      <text>Get George Michael to help</text>
    </task>
    <task>
      <createTime>2011-02-17T20:01:49</createTime>
      <id>2</id>
      <status>incomplete</status>
      <text>Try to get Gob to help</text>
    </task>
    <task>
      <createTime>2011-02-17T20:02:00</createTime>
      <id>3</id>
      <status>incomplete</status>
      <text>Only build exterior walls</text>
    </task>
    <task>
      <createTime>2011-02-18T17:12:30</createTime>
      <id>9</id>
      <status>incomplete</status>
      <text>this is a test 2</text>
    </task>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>4</totalItems>
  <totalPages>1</totalPages>
</tasks>

Create a new task

POST https://agilezen.com/api/v1/projects/{projectid}/stories/{storyid}/tasks

Creates a new task in the specified story.

Requires ReadWrite access to the project.
Supports: Enrichments

The request data should be an object with the following properties. You don’t need to specify all of the properties – any omitted ones will be given the specified default value.

PropertyTypeRequiredDefaultDescription
textstringyesn/aThe text of the task.
statusstatusnoincompleteThe status of the task. Either complete or incomplete.

On success, returns the created task.

{
  "id": 1,
  "text": "Get George Michael to help",
  "createTime": "2011-02-17T20:01:40",
  "finishTime": "2011-02-17T20:03:17",
  "finishedBy": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "status": "incomplete"
}
<?xml version="1.0" encoding="utf-8"?>
<task>
  <createTime>2011-02-17T20:01:40</createTime>
  <finishTime>2011-02-17T20:03:17</finishTime>
  <finishedBy>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </finishedBy>
  <id>1</id>
  <status>incomplete</status>
  <text>Get George Michael to help</text>
</task>

Reorder tasks within a story

PUT https://agilezen.com/api/v1/projects/{projectid}/stories/{storyid}/tasks

Reorders the existing tasks within a story.

Requires ReadWrite access to the project.
Supports: Enrichments

The request data should be an array using the reference syntax for tasks, in the desired order.

On success, retrieves the list of tasks from the specified story.

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 4,
  "items": [
    {
      "id": 1,
      "text": "Get George Michael to help",
      "createTime": "2011-02-17T20:01:40",
      "finishTime": "2011-02-17T20:03:17",
      "finishedBy": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "status": "incomplete"
    },
    {
      "id": 2,
      "text": "Try to get Gob to help",
      "createTime": "2011-02-17T20:01:49",
      "status": "incomplete"
    },
    {
      "id": 3,
      "text": "Only build exterior walls",
      "createTime": "2011-02-17T20:02:00",
      "status": "incomplete"
    },
    {
      "id": 9,
      "text": "this is a test 2",
      "createTime": "2011-02-18T17:12:30",
      "status": "incomplete"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<tasks>
  <items>
    <task>
      <createTime>2011-02-17T20:01:40</createTime>
      <finishTime>2011-02-17T20:03:17</finishTime>
      <finishedBy>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </finishedBy>
      <id>1</id>
      <status>incomplete</status>
      <text>Get George Michael to help</text>
    </task>
    <task>
      <createTime>2011-02-17T20:01:49</createTime>
      <id>2</id>
      <status>incomplete</status>
      <text>Try to get Gob to help</text>
    </task>
    <task>
      <createTime>2011-02-17T20:02:00</createTime>
      <id>3</id>
      <status>incomplete</status>
      <text>Only build exterior walls</text>
    </task>
    <task>
      <createTime>2011-02-18T17:12:30</createTime>
      <id>9</id>
      <status>incomplete</status>
      <text>this is a test 2</text>
    </task>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>4</totalItems>
  <totalPages>1</totalPages>
</tasks>

Get a task

GET https://agilezen.com/api/v1/projects/{projectid}/stories/{storyid}/tasks/{taskid}

Returns a single task.

Requires Read access to the project.
Supports: Enrichments

{
  "id": 1,
  "text": "Get George Michael to help",
  "createTime": "2011-02-17T20:01:40",
  "finishTime": "2011-02-17T20:03:17",
  "finishedBy": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "status": "incomplete"
}
<?xml version="1.0" encoding="utf-8"?>
<task>
  <createTime>2011-02-17T20:01:40</createTime>
  <finishTime>2011-02-17T20:03:17</finishTime>
  <finishedBy>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </finishedBy>
  <id>1</id>
  <status>incomplete</status>
  <text>Get George Michael to help</text>
</task>

Update a task

PUT https://agilezen.com/api/v1/projects/{projectid}/stories/{storyid}/tasks/{taskid}

Updates the properties on a certain task.

Requires ReadWrite access to the project.
Supports: Enrichments

This endpoint can be used to change the text of a task or change a task’s status between incomplete and complete.

The request data should be an object with any of the following properties. You don’t need to specify all of the properties – just the ones you want to modify.

PropertyTypeDescription
textstringThe text of the task
statusstringThe status of the task. Valid values: incomplete or complete.

On success, returns the updated task.

{
  "id": 1,
  "text": "Get George Michael to help",
  "createTime": "2011-02-17T20:01:40",
  "finishTime": "2011-02-17T20:03:17",
  "finishedBy": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "status": "incomplete"
}
<?xml version="1.0" encoding="utf-8"?>
<task>
  <createTime>2011-02-17T20:01:40</createTime>
  <finishTime>2011-02-17T20:03:17</finishTime>
  <finishedBy>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </finishedBy>
  <id>1</id>
  <status>incomplete</status>
  <text>Get George Michael to help</text>
</task>

Delete a task

DELETE https://agilezen.com/api/v1/projects/{projectid}/stories/{storyid}/tasks/{taskid}

Deletes the specified task.

Requires ReadWrite access to the project.

On success, returns an empty result with a 200 status code.

Reference Syntax

When sending data to an endpoint, you can refer to tasks in one of two ways:

  1. You can specify the task’s numeric identifier.
  2. You can specify an object representation of the task. The object that you send must have an id property with the task’s numeric identifier.

If the endpoint expects more than one task, you can send either an array of integers or an array of objects. We accept these two representations to allow you to send back the actual models that AgileZen sends to you — or if you’d rather not bother, you can just send the identifier for simplicity’s sake.

Filters

There are currently no filters available for tasks.

Enrichments

There are currently no enrichments available for tasks.