Teams API

The teams API reads and manages the teams the key's owner belongs to, and the invitations of a team. Roles work as in the app: members can read, administrators can change (see Teams, members and roles). Calls need an API key (see the API overview).

Unlike the other APIs, the team list lives outside any team's address (/teams/api/…), because it spans all your teams. A team's invitations live under the team (/a/<team_slug>/team/api/…). These endpoints have no version in the path.

Teams#

Lists the teams you belong to, sorted by name, paged. Each team has id, name, slug (the Team ID used in URLs), members (each with role), pending invitations, dashboard_url, is_admin (whether you are an administrator of it) and its subscription details.

Creates a team with you as its administrator. Send name; slug is optional and made from the name when left out. A slug that is already taken answers 400.

Only administrators can rename a team, change its slug or delete it; members get 403. Changing the slug changes every URL of the team, including its API base paths. Deleting a team deletes everything in it and can't be undone.

Invitations#

To invite someone, an administrator sends the team's id, an email and a role (admin or member, the default):

curl -sS -X POST -H "Authorization: Api-Key $API_KEY" -H "Content-Type: application/json" \
  "https://app.example.com/a/acme/team/api/invitations/" \
  -d '{"team": 42, "email": "new.person@example.com", "role": "member"}'

The app emails the invitation straight away. The team must be the team in the URL, and an address that already has a pending invitation to the team answers 400. Members can list and read invitations; only administrators can create, change or cancel them.

An invitation includes id, team, email, role, invited_by (the sender's display name), is_accepted, sent_at (the last sending time) and is_expired. The ID, sender, sending time and expiry flag are read-only. Links expire 14 days after sending. Expired invitations remain visible to team administrators, but cannot be accepted until renewed.

An administrator can POST to an invitation's resend/ endpoint without a request body. This renews the sending time and emails the link again, including for an expired invitation. The response contains the updated invitation.

Deleting an invitation cancels it: its link stops working.

Your own invitations#

Lists the open invitations addressed to the key's owner, across all teams: id, team_name, email and whether that email address is verified. Expired invitations are excluded. They are accepted in the app, from the link in the email.

Every teams endpoint#