AgileZen API Documentation

Roles

The roles endpoint provides the ability to read and manipulate the roles for a project.

Role Endpoints

List roles

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

Returns a list of roles in the project.

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

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 2,
  "items": [
    {
      "id": 3,
      "name": "Administrators",
      "access": "read",
      "members": [
        {
          "id": 1,
          "name": "Gob Bluth",
          "userName": "gob",
          "email": "Gob@bluth.com"
        },
        {
          "id": 2,
          "name": "Michael Bluth",
          "userName": "Michael",
          "email": "Michael@bluth.com"
        },
        {
          "id": 3,
          "name": "Lucille Bluth",
          "userName": "lucille",
          "email": "Lucille@bluth.com"
        }
      ]
    },
    {
      "id": 4,
      "name": "Members",
      "access": "read",
      "members": [
        {
          "id": 4,
          "name": "Lindsay Funke",
          "userName": "lindsay",
          "email": "Lindsay@funke.com"
        },
        {
          "id": 5,
          "name": "Tobias Funke",
          "userName": "tobias",
          "email": "Tobias@funke.com"
        },
        {
          "id": 6,
          "name": "George Michael Bluth",
          "userName": "georgemichael",
          "email": "georgemichael@bluth.com"
        },
        {
          "id": 7,
          "name": "Maeby Funke",
          "userName": "maeby",
          "email": "maeby@funke.com"
        },
        {
          "id": 8,
          "name": "Buster Bluth",
          "userName": "buster",
          "email": "Buster@bluth.com"
        }
      ]
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<roles>
  <items>
    <role>
      <access>read</access>
      <id>3</id>
      <members>
        <user>
          <email>Gob@bluth.com</email>
          <id>1</id>
          <name>Gob Bluth</name>
          <userName>gob</userName>
        </user>
        <user>
          <email>Michael@bluth.com</email>
          <id>2</id>
          <name>Michael Bluth</name>
          <userName>Michael</userName>
        </user>
        <user>
          <email>Lucille@bluth.com</email>
          <id>3</id>
          <name>Lucille Bluth</name>
          <userName>lucille</userName>
        </user>
      </members>
      <name>Administrators</name>
    </role>
    <role>
      <access>read</access>
      <id>4</id>
      <members>
        <user>
          <email>Lindsay@funke.com</email>
          <id>4</id>
          <name>Lindsay Funke</name>
          <userName>lindsay</userName>
        </user>
        <user>
          <email>Tobias@funke.com</email>
          <id>5</id>
          <name>Tobias Funke</name>
          <userName>tobias</userName>
        </user>
        <user>
          <email>georgemichael@bluth.com</email>
          <id>6</id>
          <name>George Michael Bluth</name>
          <userName>georgemichael</userName>
        </user>
        <user>
          <email>maeby@funke.com</email>
          <id>7</id>
          <name>Maeby Funke</name>
          <userName>maeby</userName>
        </user>
        <user>
          <email>Buster@bluth.com</email>
          <id>8</id>
          <name>Buster Bluth</name>
          <userName>buster</userName>
        </user>
      </members>
      <name>Members</name>
    </role>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>2</totalItems>
  <totalPages>1</totalPages>
</roles>

Create a new role

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

Creates a new role 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 role
accessaccessnononeThe level of API access (“none”, “read”, “readwrite”, or “admin”) that the role has

On success, returns the created role.

{
  "id": 3,
  "name": "Administrators",
  "access": "read",
  "members": [
    {
      "id": 1,
      "name": "Gob Bluth",
      "userName": "gob",
      "email": "Gob@bluth.com"
    },
    {
      "id": 2,
      "name": "Michael Bluth",
      "userName": "Michael",
      "email": "Michael@bluth.com"
    },
    {
      "id": 3,
      "name": "Lucille Bluth",
      "userName": "lucille",
      "email": "Lucille@bluth.com"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<role>
  <access>read</access>
  <id>3</id>
  <members>
    <user>
      <email>Gob@bluth.com</email>
      <id>1</id>
      <name>Gob Bluth</name>
      <userName>gob</userName>
    </user>
    <user>
      <email>Michael@bluth.com</email>
      <id>2</id>
      <name>Michael Bluth</name>
      <userName>Michael</userName>
    </user>
    <user>
      <email>Lucille@bluth.com</email>
      <id>3</id>
      <name>Lucille Bluth</name>
      <userName>lucille</userName>
    </user>
  </members>
  <name>Administrators</name>
</role>

Get a single role

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

Gets a single role with the specified id.

Requires Read access on the project.
Supports: Enrichments

{
  "id": 3,
  "name": "Administrators",
  "access": "read",
  "members": [
    {
      "id": 1,
      "name": "Gob Bluth",
      "userName": "gob",
      "email": "Gob@bluth.com"
    },
    {
      "id": 2,
      "name": "Michael Bluth",
      "userName": "Michael",
      "email": "Michael@bluth.com"
    },
    {
      "id": 3,
      "name": "Lucille Bluth",
      "userName": "lucille",
      "email": "Lucille@bluth.com"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<role>
  <access>read</access>
  <id>3</id>
  <members>
    <user>
      <email>Gob@bluth.com</email>
      <id>1</id>
      <name>Gob Bluth</name>
      <userName>gob</userName>
    </user>
    <user>
      <email>Michael@bluth.com</email>
      <id>2</id>
      <name>Michael Bluth</name>
      <userName>Michael</userName>
    </user>
    <user>
      <email>Lucille@bluth.com</email>
      <id>3</id>
      <name>Lucille Bluth</name>
      <userName>lucille</userName>
    </user>
  </members>
  <name>Administrators</name>
</role>

Update a role

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

Set the specified properties on the specified role.

Requires Admin 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
namestringThe name of the role
accessaccessThe level of API access (“none”, “read”, “readwrite”, or “admin”) that the role has

On success, returns the updated role.

{
  "id": 3,
  "name": "Administrators",
  "access": "read",
  "members": [
    {
      "id": 1,
      "name": "Gob Bluth",
      "userName": "gob",
      "email": "Gob@bluth.com"
    },
    {
      "id": 2,
      "name": "Michael Bluth",
      "userName": "Michael",
      "email": "Michael@bluth.com"
    },
    {
      "id": 3,
      "name": "Lucille Bluth",
      "userName": "lucille",
      "email": "Lucille@bluth.com"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<role>
  <access>read</access>
  <id>3</id>
  <members>
    <user>
      <email>Gob@bluth.com</email>
      <id>1</id>
      <name>Gob Bluth</name>
      <userName>gob</userName>
    </user>
    <user>
      <email>Michael@bluth.com</email>
      <id>2</id>
      <name>Michael Bluth</name>
      <userName>Michael</userName>
    </user>
    <user>
      <email>Lucille@bluth.com</email>
      <id>3</id>
      <name>Lucille Bluth</name>
      <userName>lucille</userName>
    </user>
  </members>
  <name>Administrators</name>
</role>

Delete a role

DELETE https://agilezen.com/api/v1/projects/{projectid}/roles/{roleid}

Deletes the role with the specified id.

Requires Admin access on the project.

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

Role Membership Endpoints

List the users in a role

GET https://agilezen.com/api/v1/projects/{projectid}/roles/{roleid}/members

Returns a list of the members of the specified role.

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

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 3,
  "items": [
    {
      "id": 1,
      "name": "Gob Bluth",
      "userName": "gob",
      "email": "Gob@bluth.com"
    },
    {
      "id": 2,
      "name": "Michael Bluth",
      "userName": "Michael",
      "email": "Michael@bluth.com"
    },
    {
      "id": 3,
      "name": "Lucille Bluth",
      "userName": "lucille",
      "email": "Lucille@bluth.com"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<users>
  <items>
    <user>
      <bio />
      <createTime />
      <email>Gob@bluth.com</email>
      <id>1</id>
      <name>Gob Bluth</name>
      <userName>gob</userName>
    </user>
    <user>
      <bio />
      <createTime />
      <email>Michael@bluth.com</email>
      <id>2</id>
      <name>Michael Bluth</name>
      <userName>Michael</userName>
    </user>
    <user>
      <bio />
      <createTime />
      <email>Lucille@bluth.com</email>
      <id>3</id>
      <name>Lucille Bluth</name>
      <userName>lucille</userName>
    </user>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>3</totalItems>
  <totalPages>1</totalPages>
</users>

Add a user to the specified role

POST https://agilezen.com/api/v1/projects/{projectid}/roles/{roleid}/members

Adds a user to the specified role.

Requires Admin access on the project.
Supports: Enrichments

The request data should use the reference syntax for users.

On success, returns the new list of members for the role.

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 3,
  "items": [
    {
      "id": 1,
      "name": "Gob Bluth",
      "userName": "gob",
      "email": "Gob@bluth.com"
    },
    {
      "id": 2,
      "name": "Michael Bluth",
      "userName": "Michael",
      "email": "Michael@bluth.com"
    },
    {
      "id": 3,
      "name": "Lucille Bluth",
      "userName": "lucille",
      "email": "Lucille@bluth.com"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<users>
  <items>
    <user>
      <bio />
      <createTime />
      <email>Gob@bluth.com</email>
      <id>1</id>
      <name>Gob Bluth</name>
      <userName>gob</userName>
    </user>
    <user>
      <bio />
      <createTime />
      <email>Michael@bluth.com</email>
      <id>2</id>
      <name>Michael Bluth</name>
      <userName>Michael</userName>
    </user>
    <user>
      <bio />
      <createTime />
      <email>Lucille@bluth.com</email>
      <id>3</id>
      <name>Lucille Bluth</name>
      <userName>lucille</userName>
    </user>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>3</totalItems>
  <totalPages>1</totalPages>
</users>

Set the members of a role

PUT https://agilezen.com/api/v1/projects/{projectid}/roles/{roleid}/members

Removes all members from the role and adds the specified members instead.

Requires Admin access on the project.
Supports: Enrichments

The request data should be an array using the reference syntax for users.

On success, returns the new list of members for the role.

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 3,
  "items": [
    {
      "id": 1,
      "name": "Gob Bluth",
      "userName": "gob",
      "email": "Gob@bluth.com"
    },
    {
      "id": 2,
      "name": "Michael Bluth",
      "userName": "Michael",
      "email": "Michael@bluth.com"
    },
    {
      "id": 3,
      "name": "Lucille Bluth",
      "userName": "lucille",
      "email": "Lucille@bluth.com"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<users>
  <items>
    <user>
      <bio />
      <createTime />
      <email>Gob@bluth.com</email>
      <id>1</id>
      <name>Gob Bluth</name>
      <userName>gob</userName>
    </user>
    <user>
      <bio />
      <createTime />
      <email>Michael@bluth.com</email>
      <id>2</id>
      <name>Michael Bluth</name>
      <userName>Michael</userName>
    </user>
    <user>
      <bio />
      <createTime />
      <email>Lucille@bluth.com</email>
      <id>3</id>
      <name>Lucille Bluth</name>
      <userName>lucille</userName>
    </user>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>3</totalItems>
  <totalPages>1</totalPages>
</users>

Remove a user from the specified role

DELETE https://agilezen.com/api/v1/projects/{projectid}/roles/{roleid}/members/{userid}

Removes the specified user from the specified role.

Requires Admin access on the project.
Supports: Filters

On success, returns the new list of members for the role.

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 3,
  "items": [
    {
      "id": 1,
      "name": "Gob Bluth",
      "userName": "gob",
      "email": "Gob@bluth.com"
    },
    {
      "id": 2,
      "name": "Michael Bluth",
      "userName": "Michael",
      "email": "Michael@bluth.com"
    },
    {
      "id": 3,
      "name": "Lucille Bluth",
      "userName": "lucille",
      "email": "Lucille@bluth.com"
    }
  ]
}
<?xml version="1.0" encoding="utf-8"?>
<users>
  <items>
    <user>
      <bio />
      <createTime />
      <email>Gob@bluth.com</email>
      <id>1</id>
      <name>Gob Bluth</name>
      <userName>gob</userName>
    </user>
    <user>
      <bio />
      <createTime />
      <email>Michael@bluth.com</email>
      <id>2</id>
      <name>Michael Bluth</name>
      <userName>Michael</userName>
    </user>
    <user>
      <bio />
      <createTime />
      <email>Lucille@bluth.com</email>
      <id>3</id>
      <name>Lucille Bluth</name>
      <userName>lucille</userName>
    </user>
  </items>
  <page>1</page>
  <pageSize>100</pageSize>
  <totalItems>3</totalItems>
  <totalPages>1</totalPages>
</users>

Filters

This resource supports the following filters.

PropertyTypeMatches
namestringThe name of the role

Enrichments

There are currently no enrichments available for roles.