Create a team

POST/workspaces/{workspace}/teams

Any member may create one, unless the workspace’s team_creation is owners (then only owners may: see update_workspace), and becomes its first maintainer; members adds more people by username, each a member of the workspace. slug is made from the name unless you give one: lowercase letters, digits and single hyphens. visibility is visible (the default: every member sees it) or secret (only its people and the owners). A team under a parent inherits the parent’s roles on repositories, and a mention or review request for the parent reaches it too; giving it a parent needs an owner, or a maintainer of the parent. Secret teams cannot be nested. People only, signed in or with a personal access token. Returns the team.

You become the team’s maintainer. Refused with 403 for a member when the workspace’s team_creation is owners. slug is made from name when left out (Web & Mobile becomes web-mobile), and 409 says one is taken. A workspace has at most 500 teams, nested at most 8 deep; name is at most 80 characters and description 280. A secret team cannot have a parent or child teams. Refused with 403 for an agent’s or a workspace’s token. See Teams.

• Authentication: Required. Send an access token as Authorization: Bearer.
• MCP tool: team with action create, and the same inputs
• Scope: An access token needs workspace:admin.

Path parameters

Name	Type	Required	Description
workspace	string	Yes	The workspace’s slug, e.g. “flagon-io”.

Body parameters

Send a JSON object. Names are snake_case, as in responses; the camelCase spelling is accepted too.

Name	Type	Required	Description
name	string	Yes	Its display name, at most 80 characters.
slug	string	No	Its name in mentions and URLs: lowercase letters, digits and single hyphens. Made from the name if left out.
description	string	No	What it is for, at most 280 characters.
visibility	string	No	visible: every member of the workspace sees it. secret: only its own people and the workspace’s owners. One of visible, secret.
parent	string	No	The slug of the team to nest it under.
notify	boolean	No	Whether its people are notified when it is mentioned. On unless you say.
members	array of strings	No	Usernames of members of the workspace to add, besides you.

Example request

curl -X POST https://api.g1t.sh/workspaces/flagon-io/teams \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend",
    "description": "The API and the services behind it.",
    "visibility": "visible",
    "parent": "engineering",
    "members": [
      "ana"
    ]
  }'

Example response

A successful request answers 200 with:

{
  "id": "team_01m52k8d3f7h1k5n9r3v7z1c5g",
  "workspace": "flagon-io",
  "slug": "backend",
  "name": "Backend",
  "description": "The API and the services behind it.",
  "visibility": "visible",
  "parent": {
    "slug": "engineering",
    "name": "Engineering"
  },
  "notify": true,
  "review_assignment": {
    "enabled": false,
    "algorithm": "round_robin",
    "count": 1,
    "skip_busy": false,
    "busy_at": 5,
    "include_child_teams": false,
    "excluded": [],
    "notify_team": false
  },
  "members_count": 2,
  "repos_count": 0,
  "child_teams_count": 0,
  "viewer_role": "maintainer",
  "can_manage": true,
  "created_at": "2026-10-06T15:02:11.480Z",
  "updated_at": "2026-10-06T15:02:11.480Z"
}

Errors

A failed request answers with one of these statuses and a body like {"error": {"code": "not_found", "message": "Repository not found."}}. See errors.

Status	Code	When
401	unauthenticated	A token is required, or the one sent is not valid.
403	forbidden	The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository.
404	not_found	It does not exist, or you cannot see it.
409	conflict	The request conflicts with the current state.
422	invalid	The input is not valid. message says which field and why.