AgileZen API Documentation

Stories

A story represents a basic unit of work in AgileZen. Each story must belong to a single project, and may contain tags, tasks, comments, and attachments.

Story Endpoints

List stories within a project

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

Retrieves the list of stories from the specified project.

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

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 16,
  "items": [
    {
      "id": 1,
      "text": "Build Spec house",
      "size": "5",
      "color": "teal",
      "priority": "9",
      "deadline": "2011-02-24T00:00:00",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    },
    {
      "id": 2,
      "text": "Unveil Business Model, Starla",
      "size": "",
      "color": "orange",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 4,
        "name": "Complete"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    },
    {
      "id": 3,
      "text": "Buy boat \"The Sea Word\"",
      "size": "",
      "color": "orange",
      "priority": "",
      "status": "finished",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 5,
        "name": "Archive"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    },
    {
      "id": 4,
      "text": "Find Dad, win his approval",
      "size": "",
      "color": "orange",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    },
    {
      "id": 5,
      "text": "Get acting job",
      "size": "",
      "color": "blue",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "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": 6,
      "text": "Find new son",
      "size": "",
      "color": "purple",
      "priority": "",
      "status": "finished",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 5,
        "name": "Archive"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 3,
        "name": "Lucille Bluth",
        "userName": "lucille",
        "email": "Lucille@bluth.com"
      }
    },
    {
      "id": 7,
      "text": "Get back control of company",
      "size": "",
      "color": "teal",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    },
    {
      "id": 8,
      "text": "Go out with Steve Holt (Steve Holt!)",
      "size": "",
      "color": "red",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 2,
        "name": "Ready"
      },
      "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": 9,
      "text": "Blue myself",
      "size": "",
      "color": "blue",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 4,
        "name": "Complete"
      },
      "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": 10,
      "text": "Kiss Maeby",
      "size": "",
      "color": "green",
      "priority": "",
      "status": "finished",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 5,
        "name": "Archive"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 6,
        "name": "George Michael Bluth",
        "userName": "georgemichael",
        "email": "georgemichael@bluth.com"
      }
    },
    {
      "id": 11,
      "text": "Get new car.  Too many hop-ons in StairCar.",
      "size": "",
      "color": "teal",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 2,
        "name": "Ready"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 2,
        "name": "Michael Bluth",
        "userName": "Michael",
        "email": "Michael@bluth.com"
      }
    },
    {
      "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"
      }
    },
    {
      "id": 16,
      "text": "Work in the Banana stand",
      "size": "",
      "color": "green",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 6,
        "name": "George Michael Bluth",
        "userName": "georgemichael",
        "email": "georgemichael@bluth.com"
      }
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<stories>
  <items>
    <story>
      <color>teal</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <deadline>2011-02-24T00:00:00</deadline>
      <id>1</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <priority>9</priority>
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size>5</size>
      <status>started</status>
      <text>Build Spec house</text>
    </story>
    <story>
      <color>orange</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>2</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>4</id>
        <name>Complete</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Unveil Business Model, Starla</text>
    </story>
    <story>
      <color>orange</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>3</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>5</id>
        <name>Archive</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>finished</status>
      <text>Buy boat "The Sea Word"</text>
    </story>
    <story>
      <color>orange</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>4</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Find Dad, win his approval</text>
    </story>
    <story>
      <color>blue</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>5</id>
      <owner>
        <email>Tobias@funke.com</email>
        <id>5</id>
        <name>Tobias Funke</name>
        <userName>tobias</userName>
      </owner>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Get acting job</text>
    </story>
    <story>
      <color>purple</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>6</id>
      <owner>
        <email>Lucille@bluth.com</email>
        <id>3</id>
        <name>Lucille Bluth</name>
        <userName>lucille</userName>
      </owner>
      <phase>
        <id>5</id>
        <name>Archive</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>finished</status>
      <text>Find new son</text>
    </story>
    <story>
      <color>teal</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>7</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Get back control of company</text>
    </story>
    <story>
      <color>red</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>8</id>
      <owner>
        <email>maeby@funke.com</email>
        <id>7</id>
        <name>Maeby Funke</name>
        <userName>maeby</userName>
      </owner>
      <phase>
        <id>2</id>
        <name>Ready</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Go out with Steve Holt (Steve Holt!)</text>
    </story>
    <story>
      <color>blue</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>9</id>
      <owner>
        <email>Tobias@funke.com</email>
        <id>5</id>
        <name>Tobias Funke</name>
        <userName>tobias</userName>
      </owner>
      <phase>
        <id>4</id>
        <name>Complete</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Blue myself</text>
    </story>
    <story>
      <color>green</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>10</id>
      <owner>
        <email>georgemichael@bluth.com</email>
        <id>6</id>
        <name>George Michael Bluth</name>
        <userName>georgemichael</userName>
      </owner>
      <phase>
        <id>5</id>
        <name>Archive</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>finished</status>
      <text>Kiss Maeby</text>
    </story>
    <story>
      <color>teal</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>11</id>
      <owner>
        <email>Michael@bluth.com</email>
        <id>2</id>
        <name>Michael Bluth</name>
        <userName>Michael</userName>
      </owner>
      <phase>
        <id>2</id>
        <name>Ready</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Get new car.  Too many hop-ons in StairCar.</text>
    </story>
    <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>
    <story>
      <color>green</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>16</id>
      <owner>
        <email>georgemichael@bluth.com</email>
        <id>6</id>
        <name>George Michael Bluth</name>
        <userName>georgemichael</userName>
      </owner>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Work in the Banana stand</text>
    </story>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>16</totalItems>
  <totalPages>1</totalPages>
</stories>

Create a new story

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

Creates a new story in the specified project.

Requires ReadWrite 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
textstringyesn/aThe text of the story, displayed on the card
detailsstringnonullThe details of the story in Markdown format
sizestringnonullThe story’s size
prioritystringnonullThe story’s priority
colorcolornogreyPotential colors: grey, blue, red, green, orange, yellow, purple, and teal.
phasemixednobacklog phaseThe id or object representing the phase in which to create the story
ownermixednonullThe id or username of the user who will be assigned the story
tagsarraynonullAn array of tag ids or names to apply to the story
tasksarraynonullAn array of task objects to add to the story

On success, returns the created story.

{
  "id": 1,
  "text": "Build Spec house",
  "size": "5",
  "color": "teal",
  "priority": "9",
  "deadline": "2011-02-24T00:00:00",
  "status": "started",
  "project": {
    "id": 1,
    "name": "Sudden Valley"
  },
  "phase": {
    "id": 3,
    "name": "Working"
  },
  "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"?>
<story>
  <color>teal</color>
  <creator>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </creator>
  <deadline>2011-02-24T00:00:00</deadline>
  <id>1</id>
  <owner>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </owner>
  <phase>
    <id>3</id>
    <name>Working</name>
  </phase>
  <priority>9</priority>
  <project>
    <id>1</id>
    <name>Sudden Valley</name>
  </project>
  <size>5</size>
  <status>started</status>
  <text>Build Spec house</text>
</story>

Get a story

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

Returns a single story with the specified id.

Requires Read access on the project.
Supports: Enrichments

{
  "id": 1,
  "text": "Build Spec house",
  "size": "5",
  "color": "teal",
  "priority": "9",
  "deadline": "2011-02-24T00:00:00",
  "status": "started",
  "project": {
    "id": 1,
    "name": "Sudden Valley"
  },
  "phase": {
    "id": 3,
    "name": "Working"
  },
  "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"?>
<story>
  <color>teal</color>
  <creator>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </creator>
  <deadline>2011-02-24T00:00:00</deadline>
  <id>1</id>
  <owner>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </owner>
  <phase>
    <id>3</id>
    <name>Working</name>
  </phase>
  <priority>9</priority>
  <project>
    <id>1</id>
    <name>Sudden Valley</name>
  </project>
  <size>5</size>
  <status>started</status>
  <text>Build Spec house</text>
</story>

Update a story

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

Sets the specified properties on the story with the specified id.

Requires ReadWrite access on the project.
Supports: Enrichments

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 story, displayed on the card
detailsstringThe details of the story in Markdown format
sizestringThe story’s size
prioritystringThe story’s priority
colorcolorPotential colors: grey, blue, red, green, orange, yellow, purple, and teal.
statusstatusThe story’s status. Valid values for stories on board: started, ready, blocked
blockedReasonstringThe reason the story is blocked, if its status is set to ‘blocked’
phasemixedThe id or object representing the phase in which the story exists
ownermixedThe id or username of the user who is assigned the story

On success, returns the updated story.

{
  "id": 1,
  "text": "Build Spec house",
  "size": "5",
  "color": "teal",
  "priority": "9",
  "deadline": "2011-02-24T00:00:00",
  "status": "started",
  "project": {
    "id": 1,
    "name": "Sudden Valley"
  },
  "phase": {
    "id": 3,
    "name": "Working"
  },
  "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"?>
<story>
  <color>teal</color>
  <creator>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </creator>
  <deadline>2011-02-24T00:00:00</deadline>
  <id>1</id>
  <owner>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </owner>
  <phase>
    <id>3</id>
    <name>Working</name>
  </phase>
  <priority>9</priority>
  <project>
    <id>1</id>
    <name>Sudden Valley</name>
  </project>
  <size>5</size>
  <status>started</status>
  <text>Build Spec house</text>
</story>

Delete a story

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

Deletes the story with the specified id.

Requires ReadWrite access on the project.

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

Update multiple stories

PUT https://agilezen.com/api/v1/projects/{projectid}/stories?where={filter}

Sets the same properties on all stories that match the supplied filter.

Requires ReadWrite access on the project.
Supports: Filters, Enrichments

A filter is required to ensure that you don’t inadvertently update all stories in the project at once. If you would like to update all stories, you can filter on a tautology, such as where=color:red or not(color:red).

On success, returns the list of affected stories with the requested updates applied.

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 16,
  "items": [
    {
      "id": 1,
      "text": "Build Spec house",
      "size": "5",
      "color": "teal",
      "priority": "9",
      "deadline": "2011-02-24T00:00:00",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    },
    {
      "id": 2,
      "text": "Unveil Business Model, Starla",
      "size": "",
      "color": "orange",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 4,
        "name": "Complete"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    },
    {
      "id": 3,
      "text": "Buy boat \"The Sea Word\"",
      "size": "",
      "color": "orange",
      "priority": "",
      "status": "finished",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 5,
        "name": "Archive"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    },
    {
      "id": 4,
      "text": "Find Dad, win his approval",
      "size": "",
      "color": "orange",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    },
    {
      "id": 5,
      "text": "Get acting job",
      "size": "",
      "color": "blue",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "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": 6,
      "text": "Find new son",
      "size": "",
      "color": "purple",
      "priority": "",
      "status": "finished",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 5,
        "name": "Archive"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 3,
        "name": "Lucille Bluth",
        "userName": "lucille",
        "email": "Lucille@bluth.com"
      }
    },
    {
      "id": 7,
      "text": "Get back control of company",
      "size": "",
      "color": "teal",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    },
    {
      "id": 8,
      "text": "Go out with Steve Holt (Steve Holt!)",
      "size": "",
      "color": "red",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 2,
        "name": "Ready"
      },
      "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": 9,
      "text": "Blue myself",
      "size": "",
      "color": "blue",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 4,
        "name": "Complete"
      },
      "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": 10,
      "text": "Kiss Maeby",
      "size": "",
      "color": "green",
      "priority": "",
      "status": "finished",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 5,
        "name": "Archive"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 6,
        "name": "George Michael Bluth",
        "userName": "georgemichael",
        "email": "georgemichael@bluth.com"
      }
    },
    {
      "id": 11,
      "text": "Get new car.  Too many hop-ons in StairCar.",
      "size": "",
      "color": "teal",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 2,
        "name": "Ready"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 2,
        "name": "Michael Bluth",
        "userName": "Michael",
        "email": "Michael@bluth.com"
      }
    },
    {
      "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"
      }
    },
    {
      "id": 16,
      "text": "Work in the Banana stand",
      "size": "",
      "color": "green",
      "priority": "",
      "status": "started",
      "project": {
        "id": 1,
        "name": "Sudden Valley"
      },
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "creator": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      },
      "owner": {
        "id": 6,
        "name": "George Michael Bluth",
        "userName": "georgemichael",
        "email": "georgemichael@bluth.com"
      }
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<stories>
  <items>
    <story>
      <color>teal</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <deadline>2011-02-24T00:00:00</deadline>
      <id>1</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <priority>9</priority>
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size>5</size>
      <status>started</status>
      <text>Build Spec house</text>
    </story>
    <story>
      <color>orange</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>2</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>4</id>
        <name>Complete</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Unveil Business Model, Starla</text>
    </story>
    <story>
      <color>orange</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>3</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>5</id>
        <name>Archive</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>finished</status>
      <text>Buy boat "The Sea Word"</text>
    </story>
    <story>
      <color>orange</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>4</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Find Dad, win his approval</text>
    </story>
    <story>
      <color>blue</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>5</id>
      <owner>
        <email>Tobias@funke.com</email>
        <id>5</id>
        <name>Tobias Funke</name>
        <userName>tobias</userName>
      </owner>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Get acting job</text>
    </story>
    <story>
      <color>purple</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>6</id>
      <owner>
        <email>Lucille@bluth.com</email>
        <id>3</id>
        <name>Lucille Bluth</name>
        <userName>lucille</userName>
      </owner>
      <phase>
        <id>5</id>
        <name>Archive</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>finished</status>
      <text>Find new son</text>
    </story>
    <story>
      <color>teal</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>7</id>
      <owner>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </owner>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Get back control of company</text>
    </story>
    <story>
      <color>red</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>8</id>
      <owner>
        <email>maeby@funke.com</email>
        <id>7</id>
        <name>Maeby Funke</name>
        <userName>maeby</userName>
      </owner>
      <phase>
        <id>2</id>
        <name>Ready</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Go out with Steve Holt (Steve Holt!)</text>
    </story>
    <story>
      <color>blue</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>9</id>
      <owner>
        <email>Tobias@funke.com</email>
        <id>5</id>
        <name>Tobias Funke</name>
        <userName>tobias</userName>
      </owner>
      <phase>
        <id>4</id>
        <name>Complete</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Blue myself</text>
    </story>
    <story>
      <color>green</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>10</id>
      <owner>
        <email>georgemichael@bluth.com</email>
        <id>6</id>
        <name>George Michael Bluth</name>
        <userName>georgemichael</userName>
      </owner>
      <phase>
        <id>5</id>
        <name>Archive</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>finished</status>
      <text>Kiss Maeby</text>
    </story>
    <story>
      <color>teal</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>11</id>
      <owner>
        <email>Michael@bluth.com</email>
        <id>2</id>
        <name>Michael Bluth</name>
        <userName>Michael</userName>
      </owner>
      <phase>
        <id>2</id>
        <name>Ready</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Get new car.  Too many hop-ons in StairCar.</text>
    </story>
    <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>
    <story>
      <color>green</color>
      <creator>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </creator>
      <id>16</id>
      <owner>
        <email>georgemichael@bluth.com</email>
        <id>6</id>
        <name>George Michael Bluth</name>
        <userName>georgemichael</userName>
      </owner>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <priority />
      <project>
        <id>1</id>
        <name>Sudden Valley</name>
      </project>
      <size />
      <status>started</status>
      <text>Work in the Banana stand</text>
    </story>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>16</totalItems>
  <totalPages>1</totalPages>
</stories>

Delete multiple stories

DELETE https://agilezen.com/api/v1/projects/{projectid}/stories?where={filter}

Deletes all stories that match the supplied filter.

Requires ReadWrite access on the project.
Supports: Filters

As with the bulk update endpoint, a filter is required to ensure that you don’t inadvertently update all stories in the project at once. If you would like to delete all stories, you can filter on a tautology, such as where=color:red or not(color:red).

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

Story Tag Endpoints

Several endpoints are available to manipulate the relationship between stories and their tags. You can also accomplish some of the same functionality by using the tag stories endpoints as well.

List tags on a story

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

Returns a list of the tags that are set on the specified story.

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

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 1,
  "items": [
    {
      "id": 3,
      "name": "solid as a rock"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<tags>
  <items>
    <tag>
      <id>3</id>
      <name>solid as a rock</name>
    </tag>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>1</totalItems>
  <totalPages>1</totalPages>
</tags>

Add a tag to a story

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

Adds a tag to the specified story.

Requires ReadWrite access on the project.
Supports: Enrichments

The request data should use the reference syntax for tags. Also, if you specify the textual name or an object with the name property, the tag will be created if it doesn’t already exist.

On success, returns the new list of tags for the story.

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 1,
  "items": [
    {
      "id": 3,
      "name": "solid as a rock"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<tags>
  <items>
    <tag>
      <id>3</id>
      <name>solid as a rock</name>
    </tag>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>1</totalItems>
  <totalPages>1</totalPages>
</tags>

Set the tags on a story

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

Removes all tags from the story and sets the specified tags on the story instead.

Requires ReadWrite access on the project.
Supports: Enrichments

The request data should be an array using the reference syntax for tags. Also, if you specify the textual name or an object with the name property, any tags that don’t already exist will be created.

On success, returns the updated story along with all of its tags.

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 1,
  "items": [
    {
      "id": 3,
      "name": "solid as a rock"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<tags>
  <items>
    <tag>
      <id>3</id>
      <name>solid as a rock</name>
    </tag>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>1</totalItems>
  <totalPages>1</totalPages>
</tags>

Remove a tag from a story

DELETE https://agilezen.com/api/v1/projects/{projectid}/stories/{storyid}/tags/{tag}

Removes the specified tag from the story.

Requires ReadWrite access on the project.

The tag segment in the URI can be either the tag’s numeric identifier or its textual name.

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

Reference Syntax

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

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

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

This resource supports the following filters.

PropertyTypeMatches
blockedbooleanStories which are marked blocked (or not)
colorcolorPotential colors: grey, blue, red, green, orange, yellow, purple, and teal.
creatormixedThe username, name, or id of the story’s owner
detailsstringThe story’s details field
idintegerThe story’s numeric identifier
ownermixedThe username, name, or id of the story’s owner
phasemixedThe name or id of the story’s current phase
readybooleanStories which are marked ready (or not)
blockedReasonstringThe reason field, for stories which are blocked
sizestringThe story’s size field
prioritystringThe story’s priority field
tagstringStories which have the specified tag
textstringThe story’s text field

Enrichments

This resource supports the following enrichments.

Comments

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

Returns the story or stories along with any comments that have been made.

{
  "id": 1,
  "text": "Build Spec house",
  "size": "5",
  "color": "teal",
  "priority": "9",
  "deadline": "2011-02-24T00:00:00",
  "status": "started",
  "project": {
    "id": 1,
    "name": "Sudden Valley"
  },
  "phase": {
    "id": 3,
    "name": "Working"
  },
  "creator": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "owner": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "comments": [
    {
      "id": 1,
      "text": "No way we can build it in 2 weeks.",
      "createTime": "2011-02-17T20:01:01",
      "author": {
        "id": 1,
        "name": "Gob Bluth",
        "userName": "gob",
        "email": "Gob@bluth.com"
      }
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<story>
  <color>teal</color>
  <comments>
    <comment>
      <author>
        <email>Gob@bluth.com</email>
        <id>1</id>
        <name>Gob Bluth</name>
        <userName>gob</userName>
      </author>
      <createTime>2011-02-17T20:01:01</createTime>
      <id>1</id>
      <text>No way we can build it in 2 weeks.</text>
    </comment>
  </comments>
  <creator>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </creator>
  <deadline>2011-02-24T00:00:00</deadline>
  <id>1</id>
  <owner>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </owner>
  <phase>
    <id>3</id>
    <name>Working</name>
  </phase>
  <priority>9</priority>
  <project>
    <id>1</id>
    <name>Sudden Valley</name>
  </project>
  <size>5</size>
  <status>started</status>
  <text>Build Spec house</text>
</story>

Details

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

Returns the story or stories with the details field in Markdown format. The details field is not normally returned since it has no limit on size.

{
  "id": 1,
  "text": "Build Spec house",
  "details": "Only have 2 weeks to build a spec house to announce to the press.  Can't actually build a house in that time so will focus son only building the walls. ",
  "size": "5",
  "color": "teal",
  "priority": "9",
  "deadline": "2011-02-24T00:00:00",
  "status": "started",
  "project": {
    "id": 1,
    "name": "Sudden Valley"
  },
  "phase": {
    "id": 3,
    "name": "Working"
  },
  "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"?>
<story>
  <color>teal</color>
  <creator>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </creator>
  <deadline>2011-02-24T00:00:00</deadline>
  <details>Only have 2 weeks to build a spec house to announce to the press.  Can't actually build a house in that time so will focus son only building the walls. </details>
  <id>1</id>
  <owner>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </owner>
  <phase>
    <id>3</id>
    <name>Working</name>
  </phase>
  <priority>9</priority>
  <project>
    <id>1</id>
    <name>Sudden Valley</name>
  </project>
  <size>5</size>
  <status>started</status>
  <text>Build Spec house</text>
</story>

Metrics

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

Returns the story or stories with summary performance metrics.

{
  "id": 1,
  "text": "Build Spec house",
  "size": "5",
  "color": "teal",
  "priority": "9",
  "deadline": "2011-02-24T00:00:00",
  "status": "started",
  "project": {
    "id": 1,
    "name": "Sudden Valley"
  },
  "phase": {
    "id": 3,
    "name": "Working"
  },
  "creator": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "owner": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "metrics": {
    "createTime": "2011-02-17T19:26:03",
    "startTime": "2011-02-17T19:26:03"
  }
}
<?xml version="1.0" encoding="utf-8"?>
<story>
  <color>teal</color>
  <creator>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </creator>
  <deadline>2011-02-24T00:00:00</deadline>
  <id>1</id>
  <metrics>
    <createTime>2011-02-17T19:26:03</createTime>
    <startTime>2011-02-17T19:26:03</startTime>
  </metrics>
  <owner>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </owner>
  <phase>
    <id>3</id>
    <name>Working</name>
  </phase>
  <priority>9</priority>
  <project>
    <id>1</id>
    <name>Sudden Valley</name>
  </project>
  <size>5</size>
  <status>started</status>
  <text>Build Spec house</text>
</story>

Milestones

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

Returns the story or stories with milestones – each milestone represents a move between phases.

{
  "id": 1,
  "text": "Build Spec house",
  "size": "5",
  "color": "teal",
  "priority": "9",
  "deadline": "2011-02-24T00:00:00",
  "status": "started",
  "project": {
    "id": 1,
    "name": "Sudden Valley"
  },
  "phase": {
    "id": 3,
    "name": "Working"
  },
  "creator": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "owner": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "milestones": [
    {
      "id": 1,
      "phase": {
        "id": 2,
        "name": "Ready"
      },
      "startTime": "2011-02-17T19:26:03",
      "endTime": "2011-02-17T19:45:43",
      "duration": 1180
    },
    {
      "id": 13,
      "phase": {
        "id": 4,
        "name": "Complete"
      },
      "startTime": "2011-02-17T19:45:43",
      "endTime": "2011-02-17T20:21:20",
      "duration": 2137
    },
    {
      "id": 31,
      "phase": {
        "id": 3,
        "name": "Working"
      },
      "startTime": "2011-02-17T20:21:20",
      "duration": 694908
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<story>
  <color>teal</color>
  <creator>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </creator>
  <deadline>2011-02-24T00:00:00</deadline>
  <id>1</id>
  <milestones>
    <milestone>
      <duration>1180</duration>
      <endTime>2011-02-17T19:45:43</endTime>
      <id>1</id>
      <phase>
        <id>2</id>
        <name>Ready</name>
      </phase>
      <startTime>2011-02-17T19:26:03</startTime>
    </milestone>
    <milestone>
      <duration>2137</duration>
      <endTime>2011-02-17T20:21:20</endTime>
      <id>13</id>
      <phase>
        <id>4</id>
        <name>Complete</name>
      </phase>
      <startTime>2011-02-17T19:45:43</startTime>
    </milestone>
    <milestone>
      <duration>694909</duration>
      <id>31</id>
      <phase>
        <id>3</id>
        <name>Working</name>
      </phase>
      <startTime>2011-02-17T20:21:20</startTime>
    </milestone>
  </milestones>
  <owner>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </owner>
  <phase>
    <id>3</id>
    <name>Working</name>
  </phase>
  <priority>9</priority>
  <project>
    <id>1</id>
    <name>Sudden Valley</name>
  </project>
  <size>5</size>
  <status>started</status>
  <text>Build Spec house</text>
</story>

Steps

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

Returns the story or stories with its steps – each step represents a change in status.

{
  "id": 1,
  "text": "Build Spec house",
  "size": "5",
  "color": "teal",
  "priority": "9",
  "deadline": "2011-02-24T00:00:00",
  "status": "started",
  "project": {
    "id": 1,
    "name": "Sudden Valley"
  },
  "phase": {
    "id": 3,
    "name": "Working"
  },
  "creator": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "owner": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "steps": [
    {
      "id": 1,
      "type": "working",
      "startTime": "2011-02-17T19:26:03",
      "endTime": "2011-02-17T19:45:43",
      "duration": 1180
    },
    {
      "id": 13,
      "type": "working",
      "startTime": "2011-02-17T19:45:43",
      "endTime": "2011-02-17T20:21:20",
      "duration": 2137
    },
    {
      "id": 31,
      "type": "working",
      "startTime": "2011-02-17T20:21:20",
      "duration": 694907
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<story>
  <color>teal</color>
  <creator>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </creator>
  <deadline>2011-02-24T00:00:00</deadline>
  <id>1</id>
  <owner>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </owner>
  <phase>
    <id>3</id>
    <name>Working</name>
  </phase>
  <priority>9</priority>
  <project>
    <id>1</id>
    <name>Sudden Valley</name>
  </project>
  <size>5</size>
  <status>started</status>
  <steps>
    <step>
      <duration>1180</duration>
      <endTime>2011-02-17T19:45:43</endTime>
      <id>1</id>
      <startTime>2011-02-17T19:26:03</startTime>
      <type>working</type>
    </step>
    <step>
      <duration>2137</duration>
      <endTime>2011-02-17T20:21:20</endTime>
      <id>13</id>
      <startTime>2011-02-17T19:45:43</startTime>
      <type>working</type>
    </step>
    <step>
      <duration>694908</duration>
      <id>31</id>
      <startTime>2011-02-17T20:21:20</startTime>
      <type>working</type>
    </step>
  </steps>
  <text>Build Spec house</text>
</story>

Tags

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

Returns the story or stories along with the list of tags that have been applied.

{
  "id": 1,
  "text": "Build Spec house",
  "size": "5",
  "color": "teal",
  "priority": "9",
  "deadline": "2011-02-24T00:00:00",
  "status": "started",
  "project": {
    "id": 1,
    "name": "Sudden Valley"
  },
  "phase": {
    "id": 3,
    "name": "Working"
  },
  "creator": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "owner": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "tags": [
    {
      "id": 3,
      "name": "solid as a rock"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<story>
  <color>teal</color>
  <creator>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </creator>
  <deadline>2011-02-24T00:00:00</deadline>
  <id>1</id>
  <owner>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </owner>
  <phase>
    <id>3</id>
    <name>Working</name>
  </phase>
  <priority>9</priority>
  <project>
    <id>1</id>
    <name>Sudden Valley</name>
  </project>
  <size>5</size>
  <status>started</status>
  <tags>
    <tag>
      <id>3</id>
      <name>solid as a rock</name>
    </tag>
  </tags>
  <text>Build Spec house</text>
</story>

Tasks

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

Returns the story or stories along with the list of tasks that have been created.

{
  "id": 1,
  "text": "Build Spec house",
  "size": "5",
  "color": "teal",
  "priority": "9",
  "deadline": "2011-02-24T00:00:00",
  "status": "started",
  "project": {
    "id": 1,
    "name": "Sudden Valley"
  },
  "phase": {
    "id": 3,
    "name": "Working"
  },
  "creator": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "owner": {
    "id": 1,
    "name": "Gob Bluth",
    "userName": "gob",
    "email": "Gob@bluth.com"
  },
  "tasks": [
    {
      "id": 9,
      "text": "this is a test 2",
      "createTime": "2011-02-18T17:12:30",
      "status": "incomplete"
    },
    {
      "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"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<story>
  <color>teal</color>
  <creator>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </creator>
  <deadline>2011-02-24T00:00:00</deadline>
  <id>1</id>
  <owner>
    <email>Gob@bluth.com</email>
    <id>1</id>
    <name>Gob Bluth</name>
    <userName>gob</userName>
  </owner>
  <phase>
    <id>3</id>
    <name>Working</name>
  </phase>
  <priority>9</priority>
  <project>
    <id>1</id>
    <name>Sudden Valley</name>
  </project>
  <size>5</size>
  <status>started</status>
  <tasks>
    <task>
      <createTime>2011-02-18T17:12:30</createTime>
      <id>9</id>
      <status>incomplete</status>
      <text>this is a test 2</text>
    </task>
    <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>
  </tasks>
  <text>Build Spec house</text>
</story>