Teams API

The Teams API allows users with access to the account's API token to manage teams and access to them. By using these endpoints you will be able to list teams along with their members and projects they can access, invite new or existing users, and give individual teams access to individual projects.

Each of these endpoints expects that the account's API token will be passed through the Account-Token HTTP header.

/cli/teams

This endpoint allows you to see all teams within the account. Note that each account has two special teams - Owners or Admins that cannot be removed or modified. Users with access to the Admins team can access and modify all projects as well as create new ones. Owners can do all of that, as well as modify billing settings and access the API token.

An example response from this endpoint will look like this:

[
  {
    "id": 1,
    "name": "Owners",
    "type": "owner",
    "projects": [
      {
        "uuid": "5d4e8b26-b5ee-45c3-a530-4c5fa0c7ceba",
        "url": "[email protected]:codebeat/analyser.git",
        "branch": "master"
      },
      {
        "uuid": "b96fc20a-a19d-4360-a4d0-1e14d8c7a1ef",
        "url": "[email protected]:codebeat/frontend.git",
        "branch": "master"
      }
    ],
    "members": [
      {
        "id": 1,
        "email": "[email protected]",
        "full_name": "Howard Cthulu",
        "status": "confirmed"
      }
  	]
  },
  {
    "id": 2,
    "name": "Admins",
    "type": "admin",
    "projects": [
      {
        "uuid": "5d4e8b26-b5ee-45c3-a530-4c5fa0c7ceba",
        "url": "[email protected]:codebeat/analyser.git",
        "branch": "master"
      },
      {
        "uuid": "b96fc20a-a19d-4360-a4d0-1e14d8c7a1ef",
        "url": "[email protected]:codebeat/frontend.git",
        "branch": "master"
      }
    ],
    "members": []
  },
  {
    "id": 3,
    "name": "Regular Users",
    "type": "regular",
    "projects": [
      {
        "uuid": "b96fc20a-a19d-4360-a4d0-1e14d8c7a1ef",
        "url": "[email protected]:codebeat/frontend.git",
        "branch": "master"
      }
    ],
    "members": [
      {
        "id": 2,
        "email": "[email protected]",
        "full_name": "Chuck Norris",
        "status": "confirmed"
      }
  	]
  }
]

📘

About those projects

What you could have noticed in the above example is that only private projects were listed through the /cli/teams endpoint. This is no coincidence - open source projects can be accessed by everyone in the account, if only by virtue by being accessible to everyone in the world. It would make no sense to clutter the output of this endpoint with redundant information.

What the above shows is an account with two projects - analyser and frontend and two users [email protected] and [email protected]. [email protected] is in the Owners team so he can access all projects by default. [email protected] on the other is in the Regular Users team - one of may non-special teams an account can have. Not having Owner or Admin superpowers this user relies on being a member of individual teams, with explicit access to individual projects. In this case the Regular Users team only has access to the frontend project, which means that [email protected] will be able to see frontend, but not analyser.

📘

Again about those projects

You can see that lists of projects in the Owners and Admins team is exactly the same and simply equals the list of all project in the account. It is not a coincidence - and you will see that in every single case. The information contained therein can be viewed as redundant, but it also provides a convenient way of listing all projects without the need to ever leave the scope of the Teams API.

/cli/teams/:id

This is a relatively boring endpoint, showing you just a subset of the info accessible via the /cli/teams call. An example output for team with ID=1 could look like this:

{
  "id": 1,
  "name": "Owners",
  "type": "owner",
  "projects": [
    {
      "uuid": "5d4e8b26-b5ee-45c3-a530-4c5fa0c7ceba",
      "url": "[email protected]:codebeat/analyser.git",
      "branch": "master"
    },
    {
      "uuid": "b96fc20a-a19d-4360-a4d0-1e14d8c7a1ef",
      "url": "[email protected]:codebeat/frontend.git",
      "branch": "master"
    }
  ],
  "members": [
    {
      "id": 1,
      "email": "[email protected]",
      "full_name": "Howard Cthulu",
      "status": "confirmed"
    }
  ]
}

/cli/teams

This endpoint allow us to create new teams. It accepts just one parameter - name. Note that the name must be unique within the scope of an account, including special Owners and Admins teams. An attempt to violate this constraint will result in a failing HTTP status and an accompanying JSON-encoded response with human-readable error messages.

Upon successful completion the endpoint will return a JSON representation of the new team. It will have no members, and no projects. Take note of the new team's id field and you will be able to set up both team members and projects using API endpoints described below.

This is an example response with name set to Homeboys:

{
  "id": 4,
  "name": "Homeboys",
  "type": "regular",
  "projects": [],
  "members": []
}

/cli/teams/:id

This endpoint allows you to edit a name of any non-special teams by sending a PATCH request with one parameter - name. Note that the above constraints equally apply - the new name has to be unique within the scope of the account, including special teams. Should you violate this constraint, or try to change the name of one of the special teams, the endpoint will return a failing HTTP status accompanied by a JSON-encoded body with human-readable description of the problem. Otherwise you will be presented with a successful response whose body will represent the newly updated team.

This is an example response when changing the name of the existing team (ID=3) to Homeboys:

{
  "id": 3,
  "name": "Homeboys",
  "type": "regular",
  "projects": [
    {
      "uuid": "b96fc20a-a19d-4360-a4d0-1e14d8c7a1ef",
      "url": "[email protected]:codebeat/frontend.git",
      "branch": "master"
    }
  ],
  "members": [
    {
      "id": 2,
      "email": "[email protected]",
      "full_name": "Chuck Norris",
      "status": "confirmed"
    }
  ]
}

/cli/teams/:id

This endpoint allows deleting any non-special team within the account. If successful, the request will simply return a happy 200 HTTP status and an empty body - the team is guaranteed to be deleted. If the request fails you can check the JSON-encoded response body which provides a human-readable explanation of the failure. The only reason why a team deletion request can fail under normal circumstances is the user attempting to delete one of the special teams.

🚧

There will be consequences

When you delete a team, all pending invitations to that team become invalid. It is also possible that for some users in that team this is the only link with your account. Next time those users log in to codebeat they will be greeted with a prompt to create an account, unless they already have access to other codebeat accounts.

If deleting a user decreases a number of users in your account we will reduce the cost of your monthly subscription, if applicable.

/cli/teams/:team_id/members

This endpoint allows you to invite a new member to any team in the account, including special teams. The only parameter accepted by this endpoint is email. Note that users in codebeat are uniquely identified by email so when you're adding a user to the team we first try to find an existing user with that email and if one exists, we grant access immediately. Otherwise, we send an invitation to the email address you provided.

A successful call will yield a 200 HTTP status and the body of the response will be a JSON-encoded membership object:

{
  "id": 4,
  "email": "[email protected]",
  "full_name": "Super Mario",
  "status": "invited"
}

By looking at the status field of the returned object you can determine whether you gave access to an existing user, or invited a new one.

Note that the id field represents a unique identifier of a user's membership in that particular team. It can be used to remove access for this user using the endpoint below.

📘

Inviting users and subscription cost

Unless you have a negotiated invoicing plan with custom rules, codebeat has a uniform per-seat pricing policy which means that every user within your account will cost the same whether they have access to all projects or just one. If you give team access to an existing (confirmed) user and we figure out this is a new user for this account, we will recalculate your subscription price immediately. On the other hand, if you invite a new user (invited), your subscription price will only change when the invitation is accepted, and the user status is changed to confirmed.

📘

About those invitations

When you invite a new user by email you essentially send a magic link to that email, allowing a new user to sign up to codebeat and immediately access the resources you gave them access to. However, a user may already have a profile account with a different email. We will allow that user to accept your invitation with their existing codebeat profile instead of creating a new one.

What it effectively means for you as a team manager is that you can not assume that the user who is

/cli/teams/:team_id/members/:id

This endpoint allows removing members from individual teams by using their membership id field, as reported by /cli/teams/ and /cli/teams/:id endpoints. If the request is successful, the endpoint will respond with a 200 HTTP status and an up-to-date JSON representation of the team.

The request will fail (along with a 422 HTTP status and a descriptive error message) if you try to remove the last owner. This is to prevent getting locked out of the account.

/cli/teams/:team_id/accesses

This endpoint allows giving a team access to an individual project. Projects are uniquely identified by the uuid field and these are reported by the /cli/teams/ and /cli/teams/:id endpoints. This endpoint expects only one parameter - uuid.

If the request is successful a 200 HTTP status will be reported, and the response body will contain an up-to-date JSON representation of the team, like this:

{
  "id": 3,
  "name": "Homeboys",
  "type": "regular",
  "projects": [
    {
      "uuid": "b96fc20a-a19d-4360-a4d0-1e14d8c7a1ef",
      "url": "[email protected]:codebeat/frontend.git",
      "branch": "master"
    }
  ],
  "members": [
    {
      "id": 2,
      "email": "[email protected]",
      "full_name": "Chuck Norris",
      "status": "confirmed"
    }
  ]
}

The request can fail with a descriptive error message if you attempt to give access to a project to one of the special (Owners or Admins) teams. Members of those teams have access to all projects either way so giving those teams explicit access to individual project would be a logically redundant operation.

/cli/teams/:team_id/accesses/:uuid

This endpoint allows removing team access to an individual project. Project uuid can be found by looking at /cli/teams/ and /cli/teams/:id endpoints. If the request is successful, the endpoint will respond with a 200 HTTP status and an up-to-date JSON representation of the team.

The request can fail with a descriptive error message if you attempt to remove access to a project by one of the special (Owners or Admins) teams. Members of those teams have access to all projects either way so removing access to individual project would be a logically invalid operation.