AI Workforce OneHQDocs

AI teams

AI teams, who can reach them, and their AI Employees.

List AI teams

GET/v1/teams
Permission teams: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.

Returns a list of Team objects.

Responses
200

A page of AI teams.

Other

An RFC 9457 problem.

Create an AI team

POST/v1/teams
Permission teams:create

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.

Returns a Team object.

Responses
201

The new team.

Other

An RFC 9457 problem.

Get an AI team

GET/v1/teams/{team_id}
Permission teams:read
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.

Returns a Team object.

Responses
200

The AI team.

Other

An RFC 9457 problem.

Update an AI team

PATCH/v1/teams/{team_id}
Permission teams:update

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.

Body parameters
namestring
descriptionstring or null
colorstring
iconstring

Returns a Team object.

Responses
200

The team.

Other

An RFC 9457 problem.

Delete an AI team

DELETE/v1/teams/{team_id}
Permission teams:delete

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
Permission teams: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.

Returns a list of TeamMember objects.

Responses
200

A page of team members.

Other

An RFC 9457 problem.

Give a member access to an AI team

POST/v1/teams/{team_id}/members
Permission teams:members.manage

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.

Body parameters
userstringrequired

A member's user id.

rolestringrequired

One of owner, editor, viewer.

Returns a TeamMember object.

Responses
201

The grant.

Other

An RFC 9457 problem.

List an AI team's AI Employees

GET/v1/teams/{team_id}/ai_employees
Permission teams:read

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.

Returns a list of AiEmployee objects.

Responses
200

The AI Employees.

Other

An RFC 9457 problem.

Remove a member's access to an AI team

DELETE/v1/teams/{team_id}/members/{user_id}
Permission teams:members.manage
Path parameters
team_idstringrequired

An AI team id.

user_idstringrequired

A member's user 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

Removed.

Other

An RFC 9457 problem.

Set who sees a team's sessions

PUT/v1/teams/{team_id}/session_visibility
Permission teams: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.

Body parameters
visibilitystringrequired

One of all, own.

Returns a SessionVisibility object.

Responses
200

The team's session visibility.

Other

An RFC 9457 problem.

Objects

Team

Attributes
objectstring
idstring
namestring
descriptionstring or null
colorstring
iconstring
engine_modestring
enginesarray of string
session_countinteger
running_session_countinteger
ai_employee_countinteger or null
skill_countinteger or null
storage_bytes_usedinteger or null
templatestring or null
created_atstring (date-time)
created_byUserRef

TeamMember

Attributes
objectstring
userstring
namestring
emailstring

Present for an admin's key only.

rolestring

One of owner, editor, viewer.

granted_atstring (date-time)
granted_byUserRef

AiEmployee

Attributes
objectstring
teamstring
namestring

SessionVisibility

Attributes
objectstring
teamstring
visibilitystring