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

# Gestione dei gruppi

> Crea e gestisci gruppi, appartenenze, disponibilità dei modelli e limiti ACU dei gruppi tramite l'API con chiave di servizio.

<Info>
  Questa documentazione riguarda le distribuzioni federali di Devin. [Torna alla documentazione di Devin](/it/get-started/devin-intro)
</Info>

Gestisci i [gruppi](/it/federal/groups) a livello programmatico: crea, leggi, aggiorna ed elimina gruppi, gestiscine l'appartenenza e configura la relativa [disponibilità dei modelli](/it/federal/model-provisioning) e i [limiti ACU](/it/federal/acu-limits). Questi endpoint sono disponibili solo nelle distribuzioni federali multi-tenant.

Tutti gli endpoint utilizzano richieste JSON `POST`. Ogni corpo della richiesta include `service_key`; consulta la [panoramica dell'API](/it/federal/api/overview) per informazioni su autenticazione, definizione dell'ambito, paginazione ed errori. Gli endpoint di lettura richiedono **Teams Read-Only**; quelli di scrittura richiedono **Teams Update**. Questi handler prevedono il controllo per distribuzioni self-hosted multi-tenant, ma non applicano il controllo separato del livello di accesso all'analisi utilizzato da `/Analytics`.

L'oggetto gruppo restituito dagli endpoint di lettura e scrittura:

| Campo                        | Descrizione                                                                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `group_id`                   | L'ID del gruppo.                                                                                                                |
| `name`                       | Il nome del gruppo.                                                                                                             |
| `member_count`               | Numero di membri attuali.                                                                                                       |
| `cascade_model_uids`         | UID dei modelli consentiti per Cascade. Un elenco vuoto indica che il gruppo non impone alcuna restrizione per Cascade.         |
| `command_model_uids`         | UID dei modelli consentiti per Command. Un elenco vuoto indica che il gruppo non impone alcuna restrizione per Command.         |
| `configured_cycle_acu_limit` | Il limite ACU configurato per membro del gruppo. Omesso se non è configurato alcun limite. È sempre positivo quando presente.   |
| `effective_cycle_acu_limit`  | Il limite effettivamente applicato al gruppo dopo la combinazione con i limiti del team. Omesso se non si applica alcun limite. |

***

<div id="list-groups">
  ## Elencare i gruppi
</div>

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

Elenca i gruppi visibili alla chiave di servizio. Le chiavi con ambito team elencano tutti i gruppi del team; quelle con ambito gruppo elencano solo il gruppo a cui sono assegnate. Richiede **Teams Read-Only**. Supporta `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">
  ## Ottieni un gruppo
</div>

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

Recupera un gruppo, incluse le allowlist dei modelli associate e il limite ACU configurato ed effettivo. Richiede **Teams Read-Only**. Per i gruppi inesistenti, di altri team o esterni all'ambito viene restituito `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">
  ## Crea un gruppo
</div>

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

Crea un gruppo con il `name` specificato nel team effettivo. Richiede **Teams Update**. Le chiavi con ambito gruppo non possono creare gruppi.

```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 risposta contiene l'oggetto `group` creato.

<div id="update-group">
  ## Aggiorna gruppo
</div>

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

Applica una patch atomica a un gruppo. Vengono modificati solo i campi presenti nella richiesta; quelli omessi rimangono invariati. Una richiesta senza campi da aggiornare restituisce `invalid_argument`. Richiede **Teams Update**.

<ParamField body="group_id" type="string" required>
  Il gruppo da aggiornare.
</ParamField>

<ParamField body="name" type="string">
  Il nuovo nome del gruppo.
</ParamField>

<ParamField body="cascade_models" type="object">
  `{"model_uids": [...]}` — sostituisce l'allowlist dei modelli Cascade del gruppo. Il passaggio di un elenco vuoto rimuove la restrizione Cascade del gruppo. Per informazioni su come vengono combinate le allowlist dei gruppi, consulta [Provisioning dei modelli](/it/federal/model-provisioning).
</ParamField>

<ParamField body="command_models" type="object">
  `{"model_uids": [...]}` — sostituisce l'allowlist dei modelli Command del gruppo. Il passaggio di un elenco vuoto rimuove la restrizione Command del gruppo.
</ParamField>

<ParamField body="set_cycle_acu_limit" type="number">
  Imposta il limite di ACU per membro del gruppo per ciclo di fatturazione. Deve essere positivo. Non può essere usato insieme a `clear_cycle_acu_limit`.
</ParamField>

<ParamField body="clear_cycle_acu_limit" type="boolean">
  Rimuove il limite di ACU del gruppo, ripristinando il comportamento del team o predefinito. In questa API basata su chiave di servizio, `set_cycle_acu_limit` deve essere finito e positivo; usa questa operazione di rimozione esplicita per eliminare l'override del gruppo. Il controllo del limite ACU del gruppo nel portale accetta `cycle_acu_limit: 0` come richiesta di rimozione.
</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 risposta contiene l'oggetto `group` aggiornato.

<div id="delete-group">
  ## Elimina gruppo
</div>

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

Elimina un gruppo tramite `group_id`. L'eliminazione di un gruppo già assente dall'ambito possibile della key viene considerata un'operazione riuscita senza effetti. Richiede **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">
  ## Elencare i membri di un gruppo
</div>

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

Elenca i membri attuali di un gruppo. Richiede l'autorizzazione **Teams Read-Only**. Supporta `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">
  ## Aggiungi membri al gruppo
</div>

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

Aggiunge al gruppo gli utenti del team corrente tramite email (`user_emails`, 1–1.000 voci). Richiede **Teams Update**.

* Idempotente: l'aggiunta di un membro già esistente è un'operazione riuscita senza effetti.
* Gli indirizzi email vengono privati degli spazi iniziali e finali e deduplicati senza distinzione tra maiuscole e minuscole.
* Tutto o niente: se un indirizzo email è sconosciuto o appartiene a un altro team, l'intera richiesta viene rifiutata e non viene effettuata alcuna scrittura.

```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">
  ## Rimuovi i membri del gruppo
</div>

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

Rimuove utenti da un gruppo tramite email (`user_emails`, da 1 a 1.000 voci). Richiede **Teams Update**. La convalida è tutto o niente, come per Aggiungi membri al gruppo; la rimozione di un utente valido che non appartiene al gruppo è un'operazione riuscita senza effetti.

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