AgileZen API Documentation

Phases

Phase Endpoints

List phases within a project

GET https://agilezen.com/api/v1/projects/{projectid}/phases

Retrieves the list of phases from the specified project.

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

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 5,
  "items": [
    {
      "id": 1,
      "name": "Backlog",
      "description": "Stories that will be worked on someday",
      "index": 0
    },
    {
      "id": 2,
      "name": "Ready",
      "description": "Stories that are ready to be worked on",
      "index": 1
    },
    {
      "id": 3,
      "name": "Working",
      "description": "Stories that are currently being worked on",
      "index": 2
    },
    {
      "id": 4,
      "name": "Complete",
      "description": "Stories that have been completed",
      "index": 3
    },
    {
      "id": 5,
      "name": "Archive",
      "description": "Stories that are history",
      "index": 4
    }
  ]
}

<?xml version="1.0" encoding="utf-8"?>
<phases>
  <items>
    <phase>
      <description>Stories that will be worked on someday</description>
      <id>1</id>
      <index>0</index>
      <limit />
      <name>Backlog</name>
    </phase>
    <phase>
      <description>Stories that are ready to be worked on</description>
      <id>2</id>
      <index>1</index>
      <limit />
      <name>Ready</name>
    </phase>
    <phase>
      <description>Stories that are currently being worked on</description>
      <id>3</id>
      <index>2</index>
      <limit />
      <name>Working</name>
    </phase>
    <phase>
      <description>Stories that have been completed</description>
      <id>4</id>
      <index>3</index>
      <limit />
      <name>Complete</name>
    </phase>
    <phase>
      <description>Stories that are history</description>
      <id>5</id>
      <index>4</index>
      <limit />
      <name>Archive</name>
    </phase>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>5</totalItems>
  <totalPages>1</totalPages>
</phases>

Create a new phase

POST https://agilezen.com/api/v1/projects/{projectid}/phases

Creates a new phase in the specified project.

Requires Admin access on 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
namestringyesn/aThe name of the phase.
descriptionstringyesn/aThe description of the phase.
indexnumbernolast before archiveZero based index into the list of phases. Backlog phase must have index 0 and Archive must have the last index.
limitnumbernonullWork in progress limit for phase.

On success, returns the created phase.

{
  "id": 1,
  "name": "Backlog",
  "description": "Stories that will be worked on someday",
  "index": 0
}

<?xml version="1.0" encoding="utf-8"?>
<phase>
  <description>Stories that will be worked on someday</description>
  <id>1</id>
  <index>0</index>
  <limit />
  <name>Backlog</name>
</phase>

Get a phase

GET https://agilezen.com/api/v1/projects/{projectid}/phases/{phaseid}

Returns a single phase.

Requires Read access on the project.
Supports: Enrichments

{
  "id": 1,
  "name": "Backlog",
  "description": "Stories that will be worked on someday",
  "index": 0
}

<?xml version="1.0" encoding="utf-8"?>
<phase>
  <description>Stories that will be worked on someday</description>
  <id>1</id>
  <index>0</index>
  <limit />
  <name>Backlog</name>
</phase>

Update a phase

PUT https://agilezen.com/api/v1/projects/{projectid}/phases/{phaseid}

Updates the properties on a certain phase.

Requires Admin access on the project.
Supports: Enrichments

This endpoint can be used to change the name of a phase or change a phase’s description. Also, the phase’s WIP limit can be both set or removed. Setting the phase’s limit to null will remove the limit.

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
namestringThe name of the phase.
descriptionstringThe description of the phase.
indexnumberZero based index into the list of phases. Backlog phase must have index 0 and Archive must have the last index.
limitnumberWork in progress limit for phase. Set value to null to remove the phase’s WIP limit.

On success, returns the updated task.

{
  "id": 1,
  "name": "Backlog",
  "description": "Stories that will be worked on someday",
  "index": 0
}

<?xml version="1.0" encoding="utf-8"?>
<phase>
  <description>Stories that will be worked on someday</description>
  <id>1</id>
  <index>0</index>
  <limit />
  <name>Backlog</name>
</phase>

Reorder phases within a project

PUT https://agilezen.com/api/v1/projects/{projectid}/phases

Reorders the existing phases within a project.

Requires Admin access on the project.
Supports: Enrichments

The request data should be an array using the reference syntax for phases, in the desired order. The project’s Backlog phase must be the first phase listed and the project’s Archive phase must be the last phase.

On success, retrieves the list of phases from the specified project.

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 5,
  "items": [
    {
      "id": 1,
      "name": "Backlog",
      "description": "Stories that will be worked on someday",
      "index": 0
    },
    {
      "id": 2,
      "name": "Ready",
      "description": "Stories that are ready to be worked on",
      "index": 1
    },
    {
      "id": 3,
      "name": "Working",
      "description": "Stories that are currently being worked on",
      "index": 2
    },
    {
      "id": 4,
      "name": "Complete",
      "description": "Stories that have been completed",
      "index": 3
    },
    {
      "id": 5,
      "name": "Archive",
      "description": "Stories that are history",
      "index": 4
    }
  ]
}

<?xml version="1.0" encoding="utf-8"?>
<phases>
  <items>
    <phase>
      <description>Stories that will be worked on someday</description>
      <id>1</id>
      <index>0</index>
      <limit />
      <name>Backlog</name>
    </phase>
    <phase>
      <description>Stories that are ready to be worked on</description>
      <id>2</id>
      <index>1</index>
      <limit />
      <name>Ready</name>
    </phase>
    <phase>
      <description>Stories that are currently being worked on</description>
      <id>3</id>
      <index>2</index>
      <limit />
      <name>Working</name>
    </phase>
    <phase>
      <description>Stories that have been completed</description>
      <id>4</id>
      <index>3</index>
      <limit />
      <name>Complete</name>
    </phase>
    <phase>
      <description>Stories that are history</description>
      <id>5</id>
      <index>4</index>
      <limit />
      <name>Archive</name>
    </phase>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>5</totalItems>
  <totalPages>1</totalPages>
</phases>

Delete a phase

DELETE https://agilezen.com/api/v1/projects/{projectid}/phases/{phaseid}

Deletes the specified phase. Please note that you cannot delete the project’s Backlog or Archive phases.

Requires Admin access on the project.

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

Phase Story Endpoints

List stories in a phase

GET https://agilezen.com/api/v1/projects/{projectid}/phases/{phaseid}/stories

Retrieves the list of stories in order from the specified phase.

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

{
  "id": 1,
  "name": "Backlog",
  "description": "Stories that will be worked on someday",
  "index": 0,
  "stories": [
    {
      "id": 12,
      "text": "Marry Me!",
      "size": "",
      "color": "red",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 7,
        "name": "Maeby Funke",
        "userName": "maeby",
        "email": "maeby@funke.com"
      }
    },
    {
      "id": 13,
      "text": "Become World's first Analyst + Therapist",
      "size": "",
      "color": "blue",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 5,
        "name": "Tobias Funke",
        "userName": "tobias",
        "email": "Tobias@funke.com"
      }
    },
    {
      "id": 14,
      "text": "Convince myself I don't need Mother",
      "size": "",
      "color": "yellow",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 8,
        "name": "Buster Bluth",
        "userName": "buster",
        "email": "Buster@bluth.com"
      }
    },
    {
      "id": 15,
      "text": "Perform amazing magic trick",
      "size": "",
      "color": "orange",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    }
  ]
}

<?xml version="1.0" encoding="utf-8"?>
<phase>
  <description>Stories that will be worked on someday</description>
  <id>1</id>
  <index>0</index>
  <limit />
  <name>Backlog</name>
  <stories>
    <story>
      <color>red</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>12</id>
      <owner>
        <email>maeby@funke.com</email>
        <id>7</id>
        <name>Maeby Funke</name>
        <userName>maeby</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Marry Me!</text>
    </story>
    <story>
      <color>blue</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>13</id>
      <owner>
        <email>Tobias@funke.com</email>
        <id>5</id>
        <name>Tobias Funke</name>
        <userName>tobias</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Become World's first Analyst + Therapist</text>
    </story>
    <story>
      <color>yellow</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>14</id>
      <owner>
        <email>Buster@bluth.com</email>
        <id>8</id>
        <name>Buster Bluth</name>
        <userName>buster</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Convince myself I don't need Mother</text>
    </story>
    <story>
      <color>orange</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>15</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Perform amazing magic trick</text>
    </story>
  </stories>
</phase>

Rearrange story order in a phase

PUT https://agilezen.com/api/v1/projects/{projectid}/phases/{phaseid}/stories

Rearranges order of stories in specified phase.

Requires Read/Write access on the project.

The request data should be an array using the story id and must include all stories in the specified phase.

On success, returns the new order of stories in the phase.

{
  "id": 1,
  "name": "Backlog",
  "description": "Stories that will be worked on someday",
  "index": 0,
  "stories": [
    {
      "id": 12,
      "text": "Marry Me!",
      "size": "",
      "color": "red",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 7,
        "name": "Maeby Funke",
        "userName": "maeby",
        "email": "maeby@funke.com"
      }
    },
    {
      "id": 13,
      "text": "Become World's first Analyst + Therapist",
      "size": "",
      "color": "blue",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 5,
        "name": "Tobias Funke",
        "userName": "tobias",
        "email": "Tobias@funke.com"
      }
    },
    {
      "id": 14,
      "text": "Convince myself I don't need Mother",
      "size": "",
      "color": "yellow",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 8,
        "name": "Buster Bluth",
        "userName": "buster",
        "email": "Buster@bluth.com"
      }
    },
    {
      "id": 15,
      "text": "Perform amazing magic trick",
      "size": "",
      "color": "orange",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    }
  ]
}

<?xml version="1.0" encoding="utf-8"?>
<phase>
  <description>Stories that will be worked on someday</description>
  <id>1</id>
  <index>0</index>
  <limit />
  <name>Backlog</name>
  <stories>
    <story>
      <color>red</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>12</id>
      <owner>
        <email>maeby@funke.com</email>
        <id>7</id>
        <name>Maeby Funke</name>
        <userName>maeby</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Marry Me!</text>
    </story>
    <story>
      <color>blue</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>13</id>
      <owner>
        <email>Tobias@funke.com</email>
        <id>5</id>
        <name>Tobias Funke</name>
        <userName>tobias</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Become World's first Analyst + Therapist</text>
    </story>
    <story>
      <color>yellow</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>14</id>
      <owner>
        <email>Buster@bluth.com</email>
        <id>8</id>
        <name>Buster Bluth</name>
        <userName>buster</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Convince myself I don't need Mother</text>
    </story>
    <story>
      <color>orange</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>15</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Perform amazing magic trick</text>
    </story>
  </stories>
</phase>

Reference Syntax

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

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

If the endpoint expects more than one phase, 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 phases.

Enrichments

This resource supports the following enrichments.

Stories

GET https://agilezen.com/api/v1/...?with=stories

Returns the phase or phases along with any stories that are contained with in the phase.

{
  "id": 1,
  "name": "Backlog",
  "description": "Stories that will be worked on someday",
  "index": 0,
  "stories": [
    {
      "id": 12,
      "text": "Marry Me!",
      "size": "",
      "color": "red",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 7,
        "name": "Maeby Funke",
        "userName": "maeby",
        "email": "maeby@funke.com"
      }
    },
    {
      "id": 13,
      "text": "Become World's first Analyst + Therapist",
      "size": "",
      "color": "blue",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 5,
        "name": "Tobias Funke",
        "userName": "tobias",
        "email": "Tobias@funke.com"
      }
    },
    {
      "id": 14,
      "text": "Convince myself I don't need Mother",
      "size": "",
      "color": "yellow",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 8,
        "name": "Buster Bluth",
        "userName": "buster",
        "email": "Buster@bluth.com"
      }
    },
    {
      "id": 15,
      "text": "Perform amazing magic trick",
      "size": "",
      "color": "orange",
      "priority": "",
      "status": "planned",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 1,
        "name": "Backlog"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    }
  ]
}

<?xml version="1.0" encoding="utf-8"?>
<phase>
  <description>Stories that will be worked on someday</description>
  <id>1</id>
  <index>0</index>
  <limit />
  <name>Backlog</name>
  <stories>
    <story>
      <color>red</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>12</id>
      <owner>
        <email>maeby@funke.com</email>
        <id>7</id>
        <name>Maeby Funke</name>
        <userName>maeby</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Marry Me!</text>
    </story>
    <story>
      <color>blue</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>13</id>
      <owner>
        <email>Tobias@funke.com</email>
        <id>5</id>
        <name>Tobias Funke</name>
        <userName>tobias</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Become World's first Analyst + Therapist</text>
    </story>
    <story>
      <color>yellow</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>14</id>
      <owner>
        <email>Buster@bluth.com</email>
        <id>8</id>
        <name>Buster Bluth</name>
        <userName>buster</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Convince myself I don't need Mother</text>
    </story>
    <story>
      <color>orange</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>15</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>1</id>
        <name>Backlog</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>planned</status>
      <text>Perform amazing magic trick</text>
    </story>
  </stories>
</phase>
Copyright ©2011 Rally Software Development Corp.