# AI teams

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



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## List AI teams [#list-ai-teams]

    <ApiEndpointHeader method="GET" path="/v1/teams" scope="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.

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [Team](#team) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of AI teams.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/teams \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/teams",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "team",
          "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
          "name": "Research",
          "description": "Market and competitor research.",
          "color": "#0E7C57",
          "icon": "flask-conical",
          "engine_mode": "claude",
          "engines": ["claude"],
          "session_count": 5,
          "running_session_count": 2,
          "ai_employee_count": 3,
          "skill_count": 12,
          "storage_bytes_used": 734003200,
          "template": null,
          "created_at": "2026-03-04T11:32:18.000Z",
          "created_by": {
            "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
            "name": "Maya Chen"
          }
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Create an AI team [#create-an-ai-team]

    <ApiEndpointHeader method="POST" path="/v1/teams" scope="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).

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="name" type="string" required="true" />

      <ApiParam name="description" type="string" />

      <ApiParam name="color" type="string">
        A hex color.
      </ApiParam>

      <ApiParam name="icon" type="string">
        An icon name.
      </ApiParam>

      <ApiParam name="engine" type="string">
        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`.
      </ApiParam>
    </ApiParams>

    **Returns** a [Team](#team) object.

    <ApiParams title="Responses">
      <ApiParam name="201">
        The new team.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/teams \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"name":"Research"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ name: 'Research' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/teams",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"name": "Research"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 201"
    {
      "object": "team",
      "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Research",
      "description": "Market and competitor research.",
      "color": "#0E7C57",
      "icon": "flask-conical",
      "engine_mode": "claude",
      "engines": ["claude"],
      "session_count": 5,
      "running_session_count": 2,
      "ai_employee_count": 3,
      "skill_count": 12,
      "storage_bytes_used": 734003200,
      "template": null,
      "created_at": "2026-03-04T11:32:18.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get an AI team [#get-an-ai-team]

    <ApiEndpointHeader method="GET" path="/v1/teams/{team_id}" scope="teams:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    **Returns** a [Team](#team) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The AI team.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "team",
      "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Research",
      "description": "Market and competitor research.",
      "color": "#0E7C57",
      "icon": "flask-conical",
      "engine_mode": "claude",
      "engines": ["claude"],
      "session_count": 5,
      "running_session_count": 2,
      "ai_employee_count": 3,
      "skill_count": 12,
      "storage_bytes_used": 734003200,
      "template": null,
      "created_at": "2026-03-04T11:32:18.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Update an AI team [#update-an-ai-team]

    <ApiEndpointHeader method="PATCH" path="/v1/teams/{team_id}" scope="teams:update" />

    Its name, description, color and icon. A team owner may change these.

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="name" type="string" />

      <ApiParam name="description" type="string or null" />

      <ApiParam name="color" type="string" />

      <ApiParam name="icon" type="string" />
    </ApiParams>

    **Returns** a [Team](#team) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The team.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PATCH https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"name":"Research desk","color":"#0E7C57"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd', {
          method: 'PATCH',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ name: 'Research desk', color: '#0E7C57' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.patch(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"name": "Research desk", "color": "#0E7C57"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "team",
      "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Research",
      "description": "Market and competitor research.",
      "color": "#0E7C57",
      "icon": "flask-conical",
      "engine_mode": "claude",
      "engines": ["claude"],
      "session_count": 5,
      "running_session_count": 2,
      "ai_employee_count": 3,
      "skill_count": 12,
      "storage_bytes_used": 734003200,
      "template": null,
      "created_at": "2026-03-04T11:32:18.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Delete an AI team [#delete-an-ai-team]

    <ApiEndpointHeader method="DELETE" path="/v1/teams/{team_id}" scope="teams:delete" />

    Stops its sessions and deletes it. Its disk is erased afterwards. Org owners and admins.

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Responses">
      <ApiParam name="204">
        Deleted.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd', {
          method: 'DELETE',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(res.status);
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Deleted.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## List who can reach an AI team [#list-who-can-reach-an-ai-team]

    <ApiEndpointHeader method="GET" path="/v1/teams/{team_id}/members" scope="teams:members.read" />

    The people granted access to the team and their team role.

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [TeamMember](#teammember) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of team members.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "team_member",
          "user": "user_82yssFqK4JG6pUfKfe95V3",
          "name": "Sam Okafor",
          "email": "sam.okafor@example.com",
          "role": "editor",
          "granted_at": "2026-03-10T09:00:00.000Z",
          "granted_by": {
            "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
            "name": "Maya Chen"
          }
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Give a member access to an AI team [#give-a-member-access-to-an-ai-team]

    <ApiEndpointHeader method="POST" path="/v1/teams/{team_id}/members" scope="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.

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="user" type="string" required="true">
        A member's user id.
      </ApiParam>

      <ApiParam name="role" type="string" required="true">
        One of `owner`, `editor`, `viewer`.
      </ApiParam>
    </ApiParams>

    **Returns** a [TeamMember](#teammember) object.

    <ApiParams title="Responses">
      <ApiParam name="201">
        The grant.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"user":"user_82yssFqK4JG6pUfKfe95V3","role":"editor"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ user: 'user_82yssFqK4JG6pUfKfe95V3', role: 'editor' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"user": "user_82yssFqK4JG6pUfKfe95V3", "role": "editor"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 201"
    {
      "object": "team_member",
      "user": "user_82yssFqK4JG6pUfKfe95V3",
      "name": "Sam Okafor",
      "email": "sam.okafor@example.com",
      "role": "editor",
      "granted_at": "2026-03-10T09:00:00.000Z",
      "granted_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## List an AI team's AI Employees [#list-an-ai-teams-ai-employees]

    <ApiEndpointHeader method="GET" path="/v1/teams/{team_id}/ai_employees" scope="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.

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [AiEmployee](#aiemployee) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The AI Employees.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/ai_employees \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/ai_employees', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/ai_employees",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "ai_employee",
          "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
          "name": "Market analyst"
        }
      ],
      "has_more": false,
      "skill_count": 12
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Remove a member's access to an AI team [#remove-a-members-access-to-an-ai-team]

    <ApiEndpointHeader method="DELETE" path="/v1/teams/{team_id}/members/{user_id}" scope="teams:members.manage" />

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>

      <ApiParam name="user_id" type="string" required="true">
        A member's user id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Responses">
      <ApiParam name="204">
        Removed.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members/user_82yssFqK4JG6pUfKfe95V3 \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members/user_82yssFqK4JG6pUfKfe95V3', {
          method: 'DELETE',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(res.status);
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members/user_82yssFqK4JG6pUfKfe95V3",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Removed.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Set who sees a team's sessions [#set-who-sees-a-teams-sessions]

    <ApiEndpointHeader method="PUT" path="/v1/teams/{team_id}/session_visibility" scope="teams:session_policy.write" />

    `all`: everyone on the team. `own`: each session's owner (and org owners and admins).

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="visibility" type="string" required="true">
        One of `all`, `own`.
      </ApiParam>
    </ApiParams>

    **Returns** a [SessionVisibility](#sessionvisibility) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The team's session visibility.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PUT https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/session_visibility \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"visibility":"all"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/session_visibility', {
          method: 'PUT',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ visibility: 'all' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.put(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/session_visibility",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"visibility": "all"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "session_visibility",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "visibility": "all"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### Team [#team]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="name" type="string" />

      <ApiParam name="description" type="string or null" />

      <ApiParam name="color" type="string" />

      <ApiParam name="icon" type="string" />

      <ApiParam name="engine_mode" type="string" />

      <ApiParam name="engines" type="array of string" />

      <ApiParam name="session_count" type="integer" />

      <ApiParam name="running_session_count" type="integer" />

      <ApiParam name="ai_employee_count" type="integer or null" />

      <ApiParam name="skill_count" type="integer or null" />

      <ApiParam name="storage_bytes_used" type="integer or null" />

      <ApiParam name="template" type="string or null" />

      <ApiParam name="created_at" type="string (date-time)" />

      <ApiParam name="created_by" type="UserRef" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Team object"
    {
      "object": "team",
      "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Research",
      "description": "Market and competitor research.",
      "color": "#0E7C57",
      "icon": "flask-conical",
      "engine_mode": "claude",
      "engines": ["claude"],
      "session_count": 5,
      "running_session_count": 2,
      "ai_employee_count": 3,
      "skill_count": 12,
      "storage_bytes_used": 734003200,
      "template": null,
      "created_at": "2026-03-04T11:32:18.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### TeamMember [#teammember]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="user" type="string" />

      <ApiParam name="name" type="string" />

      <ApiParam name="email" type="string">
        Present for an admin's key only.
      </ApiParam>

      <ApiParam name="role" type="string">
        One of `owner`, `editor`, `viewer`.
      </ApiParam>

      <ApiParam name="granted_at" type="string (date-time)" />

      <ApiParam name="granted_by" type="UserRef" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The TeamMember object"
    {
      "object": "team_member",
      "user": "user_82yssFqK4JG6pUfKfe95V3",
      "name": "Sam Okafor",
      "email": "sam.okafor@example.com",
      "role": "editor",
      "granted_at": "2026-03-10T09:00:00.000Z",
      "granted_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### AiEmployee [#aiemployee]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="team" type="string" />

      <ApiParam name="name" type="string" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The AiEmployee object"
    {
      "object": "ai_employee",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Market analyst"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### SessionVisibility [#sessionvisibility]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="team" type="string" />

      <ApiParam name="visibility" type="string" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The SessionVisibility object"
    {
      "object": "session_visibility",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "visibility": "all"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
