AI teams, who can reach them, and their AI Employees.
List AI teams
GET/v1/teams
Permissionteams:read
The AI teams the key's holder can read, narrowed by the key's team restriction.
On an AI team that turned on Protected files, a key that lacks files:protected.read (or whose person lacks it) gets ai_employee_count and skill_count as null for that team.
Query parameters
limitinteger
How many objects to return, 1 to 100. Default 20.
starting_afterstring
Return objects older than this id (the next page).
ending_beforestring
Return objects newer than this id (the previous page).
Headers
HQ-Versionstring (date)
A dated API version. Defaults to the version the key was created with.
HQ-Accountstring
Agency keys only: the slug of the client organization this request acts for. Required with
an agency key, refused with 400 invalid_request on any other credential. A slug that is
not one of your agency's current clients is 404 not_found. An agency key is limited to
600 requests a minute per key on EACH API server (the cap is per replica), plus its own
budget per client (limit_scope: agency_client), separate from the client's own keys.
An empty AI team. The plan's team limit applies. Creating a team from a template stays in HQ
in this version (it asks you to consent to what the template runs).
A key restricted to some AI teams cannot do this (403 team_restricted).
Headers
Idempotency-Keystring
Makes a retry safe: the same key and body within 24 hours returns the first response again
(Idempotent-Replayed: true); the same key with another body is 422.
HQ-Versionstring (date)
A dated API version. Defaults to the version the key was created with.
HQ-Accountstring
Agency keys only: the slug of the client organization this request acts for. Required with
an agency key, refused with 400 invalid_request on any other credential. A slug that is
not one of your agency's current clients is 404 not_found. An agency key is limited to
600 requests a minute per key on EACH API server (the cap is per replica), plus its own
budget per client (limit_scope: agency_client), separate from the client's own keys.
Body parameters
namestringrequired
descriptionstring
colorstring
A hex color.
iconstring
An icon name.
enginestring
The engine the team runs, default claude. The field is engine, not provider: any other field is 400 invalid_request. One of claude, codex, both.
A dated API version. Defaults to the version the key was created with.
HQ-Accountstring
Agency keys only: the slug of the client organization this request acts for. Required with
an agency key, refused with 400 invalid_request on any other credential. A slug that is
not one of your agency's current clients is 404 not_found. An agency key is limited to
600 requests a minute per key on EACH API server (the cap is per replica), plus its own
budget per client (limit_scope: agency_client), separate from the client's own keys.
Its name, description, color and icon. A team owner may change these.
Path parameters
team_idstringrequired
An AI team id.
Headers
Idempotency-Keystring
Makes a retry safe: the same key and body within 24 hours returns the first response again
(Idempotent-Replayed: true); the same key with another body is 422.
HQ-Versionstring (date)
A dated API version. Defaults to the version the key was created with.
HQ-Accountstring
Agency keys only: the slug of the client organization this request acts for. Required with
an agency key, refused with 400 invalid_request on any other credential. A slug that is
not one of your agency's current clients is 404 not_found. An agency key is limited to
600 requests a minute per key on EACH API server (the cap is per replica), plus its own
budget per client (limit_scope: agency_client), separate from the client's own keys.
Stops its sessions and deletes it. Its disk is erased afterwards. Org owners and admins.
Path parameters
team_idstringrequired
An AI team id.
Headers
Idempotency-Keystring
Makes a retry safe: the same key and body within 24 hours returns the first response again
(Idempotent-Replayed: true); the same key with another body is 422.
HQ-Versionstring (date)
A dated API version. Defaults to the version the key was created with.
HQ-Accountstring
Agency keys only: the slug of the client organization this request acts for. Required with
an agency key, refused with 400 invalid_request on any other credential. A slug that is
not one of your agency's current clients is 404 not_found. An agency key is limited to
600 requests a minute per key on EACH API server (the cap is per replica), plus its own
budget per client (limit_scope: agency_client), separate from the client's own keys.
Responses
204
Deleted.
Other
An RFC 9457 problem.
List who can reach an AI team
GET/v1/teams/{team_id}/members
Permissionteams:members.read
The people granted access to the team and their team role.
Path parameters
team_idstringrequired
An AI team id.
Query parameters
limitinteger
How many objects to return, 1 to 100. Default 20.
starting_afterstring
Return objects older than this id (the next page).
ending_beforestring
Return objects newer than this id (the previous page).
Headers
HQ-Versionstring (date)
A dated API version. Defaults to the version the key was created with.
HQ-Accountstring
Agency keys only: the slug of the client organization this request acts for. Required with
an agency key, refused with 400 invalid_request on any other credential. A slug that is
not one of your agency's current clients is 404 not_found. An agency key is limited to
600 requests a minute per key on EACH API server (the cap is per replica), plus its own
budget per client (limit_scope: agency_client), separate from the client's own keys.
Grants (or changes) a member's role on the team. A team owner who is not an org owner or
admin cannot change an org owner's or admin's access, nor demote the last team owner.
Path parameters
team_idstringrequired
An AI team id.
Headers
Idempotency-Keystring
Makes a retry safe: the same key and body within 24 hours returns the first response again
(Idempotent-Replayed: true); the same key with another body is 422.
HQ-Versionstring (date)
A dated API version. Defaults to the version the key was created with.
HQ-Accountstring
Agency keys only: the slug of the client organization this request acts for. Required with
an agency key, refused with 400 invalid_request on any other credential. A slug that is
not one of your agency's current clients is 404 not_found. An agency key is limited to
600 requests a minute per key on EACH API server (the cap is per replica), plus its own
budget per client (limit_scope: agency_client), separate from the client's own keys.
The AI Employees defined on the team's machine, by name. Never wakes the machine.
On an AI team that turned on Protected files, a key that lacks files:protected.read (or whose person lacks it) gets 403 protected_path: their names are protected files.
Path parameters
team_idstringrequired
An AI team id.
Headers
HQ-Versionstring (date)
A dated API version. Defaults to the version the key was created with.
HQ-Accountstring
Agency keys only: the slug of the client organization this request acts for. Required with
an agency key, refused with 400 invalid_request on any other credential. A slug that is
not one of your agency's current clients is 404 not_found. An agency key is limited to
600 requests a minute per key on EACH API server (the cap is per replica), plus its own
budget per client (limit_scope: agency_client), separate from the client's own keys.
Makes a retry safe: the same key and body within 24 hours returns the first response again
(Idempotent-Replayed: true); the same key with another body is 422.
HQ-Versionstring (date)
A dated API version. Defaults to the version the key was created with.
HQ-Accountstring
Agency keys only: the slug of the client organization this request acts for. Required with
an agency key, refused with 400 invalid_request on any other credential. A slug that is
not one of your agency's current clients is 404 not_found. An agency key is limited to
600 requests a minute per key on EACH API server (the cap is per replica), plus its own
budget per client (limit_scope: agency_client), separate from the client's own keys.
Responses
204
Removed.
Other
An RFC 9457 problem.
Set who sees a team's sessions
PUT/v1/teams/{team_id}/session_visibility
Permissionteams:session_policy.write
all: everyone on the team. own: each session's owner (and org owners and admins).
Path parameters
team_idstringrequired
An AI team id.
Headers
Idempotency-Keystring
Makes a retry safe: the same key and body within 24 hours returns the first response again
(Idempotent-Replayed: true); the same key with another body is 422.
HQ-Versionstring (date)
A dated API version. Defaults to the version the key was created with.
HQ-Accountstring
Agency keys only: the slug of the client organization this request acts for. Required with
an agency key, refused with 400 invalid_request on any other credential. A slug that is
not one of your agency's current clients is 404 not_found. An agency key is limited to
600 requests a minute per key on EACH API server (the cap is per replica), plus its own
budget per client (limit_scope: agency_client), separate from the client's own keys.