> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciamento de grupos

> Crie e gerencie grupos, associações, disponibilidade de modelos e limites de ACU dos grupos pela API de chave de serviço.

<Info>
  Esta documentação se aplica às implantações federais do Devin. [Voltar à documentação do Devin](/pt-BR/get-started/devin-intro)
</Info>

Gerencie [grupos](/pt-BR/federal/groups) programaticamente: crie, consulte, atualize e exclua grupos, gerencie suas associações e configure a [disponibilidade de modelos](/pt-BR/federal/model-provisioning) e os [limites de ACU](/pt-BR/federal/acu-limits). Esses endpoints estão disponíveis apenas em implantações federais multilocatárias.

Todos os endpoints usam requisições JSON `POST`. Todo corpo de requisição inclui `service_key`; consulte a [visão geral da API](/pt-BR/federal/api/overview) para informações sobre autenticação, escopo, paginação e erros. Os endpoints de leitura exigem **Teams Read-Only**; os endpoints de escrita exigem **Atualização de Teams**. Esses handlers exigem uma implantação auto-hospedada e multilocatária, mas não aplicam a verificação separada do nível de acesso a análises usada por `/Analytics`.

O objeto de grupo retornado pelos endpoints de leitura e escrita:

| Campo                        | Descrição                                                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `group_id`                   | O ID do grupo.                                                                                                                       |
| `name`                       | O nome do grupo.                                                                                                                     |
| `member_count`               | Número de membros atuais.                                                                                                            |
| `cascade_model_uids`         | UIDs dos modelos permitidos para o Cascade. Uma lista vazia significa que o grupo não impõe restrições ao Cascade.                   |
| `command_model_uids`         | UIDs dos modelos permitidos para o Command. Uma lista vazia significa que o grupo não impõe restrições ao Command.                   |
| `configured_cycle_acu_limit` | O limite de ACU por membro configurado para o grupo. Omitido quando nenhum limite está configurado. Sempre positivo quando presente. |
| `effective_cycle_acu_limit`  | O limite efetivamente aplicado ao grupo após a combinação com os limites da equipe. Omitido quando nenhum limite se aplica.          |

***

<div id="list-groups">
  ## Listar grupos
</div>

```
POST /api/v1/ListGroups
```

Lista os grupos visíveis para a chave de serviço. Chaves com escopo de equipe listam todos os grupos da equipe; chaves com escopo de grupo listam apenas o grupo atribuído a elas. Requer **Teams Read-Only**. Oferece suporte a `page_size` / `page_token`.

```bash theme={null}
curl -X POST https://<your-server>/api/v1/ListGroups \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key"}'
```

```json theme={null}
{
  "groups": [
    {"groupId": "group_a", "name": "Engineering", "memberCount": 24},
    {"groupId": "group_b", "name": "Data Science", "memberCount": 9}
  ],
  "nextPageToken": ""
}
```

<div id="get-group">
  ## Obter grupo
</div>

```
POST /api/v1/GetGroup
```

Lê um grupo, incluindo suas listas de permissões de modelos e os limites de ACU configurado e efetivo. Requer **Teams Read-Only**. Grupos inexistentes, de outras equipes ou fora do escopo retornam `not_found`.

```bash theme={null}
curl -X POST https://<your-server>/api/v1/GetGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'
```

```json theme={null}
{
  "group": {
    "groupId": "group_a",
    "name": "Engineering",
    "memberCount": 24,
    "cascadeModelUids": ["model-uid-1", "model-uid-2"],
    "commandModelUids": [],
    "configuredCycleAcuLimit": 50,
    "effectiveCycleAcuLimit": 50
  }
}
```

<div id="create-group">
  ## Criar grupo
</div>

```
POST /api/v1/CreateGroup
```

Cria um grupo com o `name` especificado na equipe efetiva. Requer **Atualização de Teams**. Chaves restritas a grupos não podem criar grupos.

```bash theme={null}
curl -X POST https://<your-server>/api/v1/CreateGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "name": "Engineering"}'
```

A resposta contém o objeto `group` criado.

<div id="update-group">
  ## Atualizar grupo
</div>

```
POST /api/v1/UpdateGroup
```

Atualiza um grupo de forma atômica. Apenas os campos presentes na requisição são alterados; os campos omitidos não são modificados. Uma requisição sem campos para atualização retorna `invalid_argument`. Requer **Atualização de Teams**.

<ParamField body="group_id" type="string" required>
  O grupo a ser atualizado.
</ParamField>

<ParamField body="name" type="string">
  Novo nome do grupo.
</ParamField>

<ParamField body="cascade_models" type="object">
  `{"model_uids": [...]}` — substitui a lista de permissões de modelos Cascade do grupo. Informar uma lista vazia remove a restrição de Cascade do grupo. Consulte [Provisionamento de modelos](/pt-BR/federal/model-provisioning) para saber como as listas de permissões dos grupos são combinadas.
</ParamField>

<ParamField body="command_models" type="object">
  `{"model_uids": [...]}` — substitui a lista de permissões de modelos Command do grupo. Informar uma lista vazia remove a restrição de Command do grupo.
</ParamField>

<ParamField body="set_cycle_acu_limit" type="number">
  Define o limite de ACU por membro do grupo em cada ciclo de faturamento. Deve ser positivo. É mutuamente exclusivo com `clear_cycle_acu_limit`.
</ParamField>

<ParamField body="clear_cycle_acu_limit" type="boolean">
  Remove o limite de ACU do grupo, restaurando o comportamento da equipe ou o padrão. Nesta API de chave de serviço, `set_cycle_acu_limit` deve ser finito e positivo; use esta operação explícita para remover o override do grupo. O controle de limite de ACU do grupo no portal aceita `cycle_acu_limit: 0` como uma requisição de remoção.
</ParamField>

```bash theme={null}
curl -X POST https://<your-server>/api/v1/UpdateGroup \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "group_id": "group_a",
    "cascade_models": {"model_uids": ["model-uid-1", "model-uid-2"]},
    "set_cycle_acu_limit": 50
  }'
```

A resposta contém o objeto `group` atualizado.

<div id="delete-group">
  ## Excluir grupo
</div>

```
POST /api/v1/DeleteGroup
```

Exclui um grupo pelo `group_id`. Excluir um grupo que já não está no escopo possível da chave é uma operação bem-sucedida sem efeito. Requer **Atualização de Teams**.

```bash theme={null}
curl -X POST https://<your-server>/api/v1/DeleteGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'
```

<div id="list-group-members">
  ## Listar membros do grupo
</div>

```
POST /api/v1/ListGroupMembers
```

Lista os membros atuais de um grupo. Requer **Teams Read-Only**. Aceita `page_size` / `page_token`.

```bash theme={null}
curl -X POST https://<your-server>/api/v1/ListGroupMembers \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'
```

```json theme={null}
{
  "members": [
    {"userId": "user_abc", "email": "dev@agency.gov"}
  ],
  "nextPageToken": ""
}
```

<div id="add-group-members">
  ## Adicionar membros ao grupo
</div>

```
POST /api/v1/AddGroupMembers
```

Adiciona usuários atuais da equipe a um grupo por e-mail (`user_emails`, de 1 a 1.000 entradas). Requer **Atualização de Teams**.

* Idempotente: adicionar um membro já existente é uma operação bem-sucedida sem efeito.
* Os e-mails têm os espaços em branco removidos e são desduplicados sem diferenciar maiúsculas de minúsculas.
* Tudo ou nada: se algum e-mail for desconhecido ou pertencer a outra equipe, toda a requisição será rejeitada e nada será gravado.

```bash theme={null}
curl -X POST https://<your-server>/api/v1/AddGroupMembers \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "group_id": "group_a",
    "user_emails": ["dev@agency.gov", "lead@agency.gov"]
  }'
```

<div id="remove-group-members">
  ## Remover membros do grupo
</div>

```
POST /api/v1/RemoveGroupMembers
```

Remove usuários de um grupo por e-mail (`user_emails`, de 1 a 1.000 entradas). Requer **Atualização de Teams**. A validação é tudo ou nada, como em Adicionar membros ao grupo; remover um usuário válido que não é membro é uma operação bem-sucedida sem alterações.

```bash theme={null}
curl -X POST https://<your-server>/api/v1/RemoveGroupMembers \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "group_id": "group_a",
    "user_emails": ["dev@agency.gov"]
  }'
```