Team Resource

Admin privileges required for these API methods.

Team is a resource that belongs to an Account and allows you to group users and permissions to repositories into a single entity.

Readable attributes

id	integer	Unique ID of the team.
color_label	string	Name of the specified color label. See a list of available labels below.
updated_at	datetime	Time when the integration was last updated.
created_at	datetime	Time when the integration was first added to the system.

Writable attributes

name	string	Name of your team.
color_label	string	Color label used for your team.
users	array	An array of user ID’s.
permissions	hash	Hash of repositories ID’s mapped to permissions. Format is specified below.

Find All Teams

json http-request

GET /api/teams.json

Click to expand…

json http-response

[
  {
    "team": {
      "id": 1,
      "name": "Beanstalk",
      "color_label": "green",
      "created_at": "2013/10/28 09:55:56 -0500",
      "updated_at": "2014/02/01 11:30:07 -0500"
    }
  },
  {
    "team": {
      "id": 2,
      "name": "Postmark",
      "color_label": "yellow",
      "created_at": "2013/10/28 06:54:32 -0500",
      "updated_at": "2014/01/31 01:01:23 -0500"
    }
  },
  {
    "team": {
      "id": 3,
      "name": "dploy.io",
      "color_label": "purple",
      "created_at": "2013/12/12 03:45:43 -0500",
      "updated_at": "2014/01/31 01:01:02 -0500"
    }
  }
]

Find Team

json http-request

GET /api/teams/{TEAM_ID}.json

Click to expand…

json http-response

{
  "team": {
    "id": 1,
    "name": "Beanstalk",
    "color_label": "green",
    "created_at": "2013/10/28 09:55:56 -0500",
    "updated_at": "2014/02/01 11:30:07 -0500"
  }
}

Create a Team (with permissions)

Create a new team. Specify users and permissions to repositories in a single call.

name (string) — name of your team
color_label (string) — color label used for your team on the UI
users (array) — An array of User ID’s
permissions (hash) — Hash of repository ID’s mapped to permissions
1. repository_id (string) — unique ID of a repository
  1. write (boolean) — true for write and read access, false for read-only
  2. deploy (boolean) — true when user can deploy, false means user can’t deploy
  3. configure_deployments (boolean) — true when user configure deployment environments, false when users can’t configure deployment environments.

json http-request

POST /api/teams.json
{
  "name": "Designers",
  "color_label": "red",
  "users": [3],
  "permissions":{
    "1": {
      "write": true,
      "deploy": true,
      "configure_deployments": false
    },
    "2": {
      "write": true,
      "deploy": true,
      "configure_deployments": false
    }
  }
}

Click to expand…

json http-response

{
  "team": {
    "id": 1,
    "name": "Designers",
    "color_label": "red",
    "created_at": "2014/02/12 12:30:21 -0500",
    "updated_at": "2014/02/12 12:30:21 -0500",
    "users": [
      {
        "id": 3,
        "name": "Eugene Fedorenko",
        "first_name": "Eugene",
        "last_name": "Fedorenko",
        "username": "eugene",
        "email": "eugene@wildbit.com",
        "account_id": 1,
        "admin": true,
        "owner": false,
        "timezone": "Pacific Time (US & Canada)",
        "created_at": "2010/03/01 10:13:17 -0700",
        "updated_at": "2014/02/19 01:23:45 -0700"
      }
    ],
    "permissions" : [
      {
        "repository_id": 1,
        "repository_title": "Beanstalk",
        "write": true,
        "deploy": true,
        "configure_deployments": false
      },
      {
        "repository_id": 2,
        "repository_title": "Postmark",
        "write": true,
        "deploy": true,
        "configure_deployments": false
      }
    ]
  }
}

Update a Team (with permissions)

This operation is considered a bulk update. All previous permissions and users for the team will be replaced with the new permissions and users provided in this call.

name (string) — name of your team
color_label (string) — color label used for your team
users (array) — An array of user ID’s
permissions (hash) — Hash of repository ID’s mapped to permissions
1. repository_id (string) — unique ID of a repository
  1. write (boolean) — true for write and read access, false for read-only
  2. deploy (boolean) — true when user can deploy, false means user can’t deploy
  3. configure_deployments (boolean) — true when user configure deployment environments, false when users can’t configure deployment environments.

json http-request

PUT /api/teams/{TEAM_ID}.json
{
  "color_label": "green",
  "users": [3, 4],
  "permissions":{
    "1": {
      "write": true,
      "deploy": true,
      "configure_deployments": false
    },
    "2": {
      "write": true,
      "deploy": true,
      "configure_deployments": false
    },
    "3": {
       "write": true,
       "deploy": true,
       "configure_deployments": false
    }
  }
}

Click to expand…

json http-response

{
  "team": {
    "id": 1,
    "name": "Designers",
    "color_label": "green",
    "created_at": "2014/02/12 12:30:21 -0500",
    "updated_at": "2014/02/12 12:30:21 -0500",
    "users": [
      {
        "id": 3,
        "name": "Eugene Fedorenko",
        "first_name": "Eugene",
        "last_name": "Fedorenko",
        "username": "eugene",
        "email": "eugene@wildbit.com",
        "account_id": 1,
        "admin": true,
        "owner": false,
        "timezone": "Pacific Time (US & Canada)",
        "created_at": "2010/03/01 10:13:17 -0700",
        "updated_at": "2014/02/19 01:23:45 -0700"
      },
      {
        "id": 4,
        "name": "Eugene Fedorenko Jr.",
        "first_name": "Eugene",
        "last_name": "Fedorenko Jr.",
        "username": "eugenejr",
        "email": "eugene.jr@wildbit.com",
        "account_id": 1,
        "admin": false,
        "owner": false,
        "timezone": "Pacific Time (US & Canada)",
        "created_at": "2011/03/01 10:13:17 -0700",
        "updated_at": "2014/02/19 01:23:45 -0700"
      }
    ],
    "permissions" : [
      {
        "repository_id": 1,
        "repository_title": "Beanstalk",
        "write": true,
        "deploy": true,
        "configure_deployments": false
      },
      {
        "repository_id": 2,
        "repository_title": "Postmark",
        "write": true,
        "deploy": true,
        "configure_deployments": false
      },
      {
        "repository_id": 3,
        "repository_title": "dploy.io",
        "write": true,
        "deploy": true,
        "configure_deployments": false
      }
    ]
  }
}

Delete a Team

This action permanently deletes the team and its assoicated permissions.

id (integer) — unique ID of the team

json http-request

DELETE /api/teams/{ID}.json

Click to expand…

json http-response

HEAD 200 OK

Find All Users on a Team

Retrieve all users on the team.

id (integer) — unique ID of the team

json http-request

GET /api/teams/{ID}/users.json

Click to expand…

json http-response

[
  {
    "user": {
      "id": 2,
      "login": "chris",
      "last_name": "Ledet",
      "first_name": "Chris",
      "name": "Chris Ledet",
      "email": "chris.ledet@wildbit.com",
      "owner": true,
      "admin": false,
      "account_id": 2,
      "timezone": "Eastern",
      "created_at": "2013/03/01 08:35:00 +[0800",
      "updated_at": "2014/02/05 14:14:58 +0800"
    }
  }
]

Add a User to Team

Use this end-point when you only want to add a user to a team.

id (integer) — unique ID of the team
user_id (integer) — unique ID of the user

json http-request

PUT /api/teams/{ID}/users.json
{
  "user_id": 4
}

Click to expand…

json http-response

HEAD 200 OK

Remove a User from Team

Use this end-point when you only want to remove a user from a team.

id (integer) — unique ID of the team
user_id (integer) — unique ID of the user

json http-request

DELETE /api/teams/{ID}/users/{USER_ID}.json

Click to expand…

json http-response

HEAD 200 OK