> ## 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.

# Gestión de grupos

> Cree y gestione grupos, membresías, disponibilidad de modelos y límites de ACU de grupo mediante la API de clave de servicio.

<Info>
  Esta documentación corresponde a los despliegues federales de Devin. [Volver a la documentación de Devin](/es/get-started/devin-intro)
</Info>

Gestione [grupos](/es/federal/groups) mediante programación: cree, consulte, actualice y elimine grupos, gestione sus membresías y configure su [disponibilidad de modelos](/es/federal/model-provisioning) y sus [límites de ACU](/es/federal/acu-limits). Estos endpoints solo están disponibles en despliegues federales con múltiples tenants.

Todos los endpoints son solicitudes `POST` JSON. Cada cuerpo de solicitud incluye `service_key`; consulte la [descripción general de la API](/es/federal/api/overview) para obtener información sobre autenticación, ámbito, paginación y errores. Los endpoints de lectura requieren **Teams Read-Only**; los de escritura requieren **Teams Update**. Estos controladores tienen la restricción de despliegue autohospedado con múltiples tenants, pero no aplican la comprobación independiente del nivel de acceso a analytics utilizada por `/Analytics`.

El objeto de grupo que devuelven los endpoints de lectura y escritura:

| Campo                        | Descripción                                                                                                                                     |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `group_id`                   | El ID del grupo.                                                                                                                                |
| `name`                       | El nombre del grupo.                                                                                                                            |
| `member_count`               | Número de miembros actuales.                                                                                                                    |
| `cascade_model_uids`         | UID de los modelos permitidos para Cascade. Una lista vacía significa que el grupo no impone restricciones para Cascade.                        |
| `command_model_uids`         | UID de los modelos permitidos para Command. Una lista vacía significa que el grupo no impone restricciones para Command.                        |
| `configured_cycle_acu_limit` | El límite de ACU por miembro configurado para el grupo. Se omite si no hay ningún límite configurado. Siempre es positivo cuando está presente. |
| `effective_cycle_acu_limit`  | El límite que se aplica realmente al grupo tras combinarlo con los límites del equipo. Se omite si no se aplica ningún límite.                  |

***

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

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

Lista los grupos visibles para la clave de servicio. Las claves con ámbito de equipo muestran todos los grupos del equipo; las claves con ámbito de grupo muestran únicamente el grupo asignado. Requiere **Teams Read-Only**. Admite `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">
  ## Obtener un grupo
</div>

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

Obtiene un grupo, incluidas sus listas de permitidos de modelos y el límite de ACU configurado y efectivo. Requiere **Teams Read-Only**. Los grupos inexistentes, de otros equipos o fuera del ámbito devuelven `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">
  ## Crear grupo
</div>

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

Crea un grupo con el `name` indicado en el equipo efectivo. Requiere **Teams Update**. Las claves con ámbito de grupo no pueden crear 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"}'
```

La respuesta incluye el objeto `group` creado.

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

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

Actualiza parcialmente un grupo de forma atómica. Solo se modifican los campos presentes en la solicitud; los campos omitidos no se modifican. Una solicitud sin campos que actualizar devuelve `invalid_argument`. Requiere **Teams Update**.

<ParamField body="group_id" type="string" required>
  El grupo que se va a actualizar.
</ParamField>

<ParamField body="name" type="string">
  El nuevo nombre del grupo.
</ParamField>

<ParamField body="cascade_models" type="object">
  `{"model_uids": [...]}` — reemplaza la lista de permitidos de modelos Cascade del grupo. Pasar una lista vacía elimina la restricción de Cascade del grupo. Consulta [Model Provisioning](/es/federal/model-provisioning) para saber cómo se combinan las listas de permitidos de los grupos.
</ParamField>

<ParamField body="command_models" type="object">
  `{"model_uids": [...]}` — reemplaza la lista de permitidos de modelos Command del grupo. Pasar una lista vacía elimina la restricción de Command del grupo.
</ParamField>

<ParamField body="set_cycle_acu_limit" type="number">
  Establece el límite de ACU por miembro del grupo para cada ciclo de facturación. Debe ser positivo. Es mutuamente excluyente con `clear_cycle_acu_limit`.
</ParamField>

<ParamField body="clear_cycle_acu_limit" type="boolean">
  Elimina el límite de ACU del grupo y restaura el comportamiento del equipo o el comportamiento predeterminado. En esta API de clave de servicio, `set_cycle_acu_limit` debe ser finito y positivo; usa esta operación explícita para eliminar la anulación del grupo. El control del portal para el límite de ACU del grupo acepta `cycle_acu_limit: 0` como solicitud para eliminarlo.
</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
  }'
```

La respuesta contiene el objeto `group` actualizado.

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

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

Elimina un grupo mediante `group_id`. Eliminar un grupo que ya no se encuentra dentro del ámbito posible de la clave se considera una operación sin efectos correcta. Requiere **Teams Update**.

```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 los miembros del grupo
</div>

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

Lista los miembros actuales de un grupo. Requiere **Teams Read-Only**. Admite `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">
  ## Agregar miembros al grupo
</div>

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

Agrega usuarios del equipo actual a un grupo mediante correo electrónico (`user_emails`, entre 1 y 1.000 entradas). Requiere **Teams Update**.

* Idempotente: agregar un miembro existente se considera correctamente una operación sin efectos.
* Los correos electrónicos se recortan y se eliminan los duplicados sin distinguir entre mayúsculas y minúsculas.
* Todo o nada: si algún correo electrónico es desconocido o pertenece a otro equipo, se rechaza toda la solicitud y no se realiza ninguna modificación.

```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">
  ## Eliminar miembros del grupo
</div>

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

Elimina usuarios de un grupo por correo electrónico (`user_emails`, entre 1 y 1.000 entradas). Requiere **Teams Update**. La validación es de todo o nada, como en Agregar miembros al grupo; eliminar un usuario válido que no es miembro se completa correctamente como una operación sin efectos.

```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"]
  }'
```