AgileZen API Documentation

Tags

A tag is a simple marker that can be applied to stories to categorize them.

Tag Endpoints

List tags within a project

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

Retrieves the list of tags from the specified project.

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

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

Create a new tag

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

Creates a new tag 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
namestringyesn/aThe text of the tag

On success, returns the created tag.

{
  "id": 1,
  "name": "come on"
}
<?xml version="1.0" encoding="utf-8"?>
<tag>
  <id>1</id>
  <name>come on</name>
</tag>

Get a tag

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

Returns a single tag.

Requires Read access on the project.
Supports: Enrichments

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

{
  "id": 1,
  "name": "come on"
}
<?xml version="1.0" encoding="utf-8"?>
<tag>
  <id>1</id>
  <name>come on</name>
</tag>

Update a tag

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

Updates the properties on a certain tag.

Requires ReadWrite access on the project.
Supports: Enrichments

The tag segment in the URI can be either the tag’s numeric identifier or its textual name. This endpoint can be used to rename a tag (change its textual representation) without having to remove it from all stories and re-apply it.

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 text of the tag

On success, returns the updated tag.

{
  "id": 1,
  "name": "come on"
}
<?xml version="1.0" encoding="utf-8"?>
<tag>
  <id>1</id>
  <name>come on</name>
</tag>

Delete a tag

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

Deletes the specified tag.

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.

Tag Stories Endpoints

Several endpoints are available to manipulate the relationship between tags and the stories to which they’ve been applied. You can also accomplish some of the same functionality by using the story tag endpoints as well.

List stories on a tag

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

Retrieves the list of stories to which the specified tag has been applied.

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

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

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 2,
  "items": [
    {
      "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"
      }
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<stories>
  <items>
    <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>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>2</totalItems>
  <totalPages>1</totalPages>
</stories>

Add a tag to a story

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

Adds the specified tag to a story.

Requires ReadWrite access on the project.
Supports: Enrichments

The tag segment in the URI can be either the tag’s numeric identifier or its textual name. The request data should use the reference syntax for stories.

On success, returns the updated list of stories.

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 2,
  "items": [
    {
      "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"
      }
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<stories>
  <items>
    <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>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>2</totalItems>
  <totalPages>1</totalPages>
</stories>

Set the stories for a tag

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

Removes the specified tag from all stories and sets it on the specified stories instead.

Requires ReadWrite access on the project.
Supports: Enrichments

The tag segment in the URI can be either the tag’s numeric identifier or its textual name. The request data should be an array using the reference syntax for stories.

On success, returns the updated list of stories.

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 2,
  "items": [
    {
      "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"
      }
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<stories>
  <items>
    <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>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>2</totalItems>
  <totalPages>1</totalPages>
</stories>

Remove a tag from a story

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

Removes the tag from the specified 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 tags in one of three ways:

  1. You can specify the tag’s numeric identifier.
  2. You can specify the tag’s textual name.
  3. You can specify an object representation of the tag. The object that you send must have either an id property with the tag’s numeric identifier, or a name property with its textual name.

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

Enrichments

This resource supports the following enrichments.

Stories

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

Returns the tag or tags with the list of stories on which each has been applied.

{
  "id": 1,
  "name": "come on",
  "stories": [
    {
      "id": 3,
      "text": "Buy boat \"The Sea Word\""
    },
    {
      "id": 4,
      "text": "Find Dad, win his approval"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<tag>
  <id>1</id>
  <name>come on</name>
  <stories>
    <story>
      <id>3</id>
      <text>Buy boat "The Sea Word"</text>
    </story>
    <story>
      <id>4</id>
      <text>Find Dad, win his approval</text>
    </story>
  </stories>
</tag>