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

# Gruppenverwaltung

> Gruppen, Mitgliedschaften, Modellverfügbarkeit und Gruppen-ACU-Obergrenzen über die Service-Key-API erstellen und verwalten.

<Info>
  Diese Dokumentation gilt für die Federal Deployments von Devin. [Zurück zur Devin-Dokumentation](/de/get-started/devin-intro)
</Info>

Verwalten Sie [Gruppen](/de/federal/groups) programmgesteuert: Erstellen, lesen, aktualisieren und löschen Sie Gruppen, verwalten Sie deren Mitgliedschaften und konfigurieren Sie deren [Modellverfügbarkeit](/de/federal/model-provisioning) sowie [ACU-Obergrenzen](/de/federal/acu-limits). Diese Endpunkte sind nur in mandantenfähigen Federal Deployments verfügbar.

Alle Endpunkte verwenden JSON-`POST`-Anfragen. Jeder Request-Body enthält `service_key`; Informationen zu Authentifizierung, Geltungsbereich, Paginierung und Fehlern finden Sie in der [API-Übersicht](/de/federal/api/overview). Leseendpunkte erfordern **Teams Read-Only**, Schreibendpunkte **Teams Update**. Diese Handler unterliegen der Bereitstellungsprüfung für self-hosted Multi-Tenant-Umgebungen, führen jedoch nicht die separate Prüfung der Analytics-Zugriffsebene durch, die für `/Analytics` verwendet wird.

Das von Lese- und Schreibendpunkten zurückgegebene Gruppenobjekt:

| Feld                         | Beschreibung                                                                                                                                   |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `group_id`                   | Die ID der Gruppe.                                                                                                                             |
| `name`                       | Der Name der Gruppe.                                                                                                                           |
| `member_count`               | Anzahl der aktuellen Member.                                                                                                                   |
| `cascade_model_uids`         | Für Cascade zulässige Modell-UIDs. Eine leere Liste bedeutet, dass die Gruppe keine Einschränkungen für Cascade festlegt.                      |
| `command_model_uids`         | Für Command zulässige Modell-UIDs. Eine leere Liste bedeutet, dass die Gruppe keine Einschränkungen für Command festlegt.                      |
| `configured_cycle_acu_limit` | Die konfigurierte ACU-Obergrenze pro Gruppen-Member. Wird weggelassen, wenn keine Obergrenze konfiguriert ist. Falls angegeben, immer positiv. |
| `effective_cycle_acu_limit`  | Die für die Gruppe tatsächlich geltende Obergrenze nach Berücksichtigung der Team-Limits. Wird weggelassen, wenn keine Obergrenze gilt.        |

***

<div id="list-groups">
  ## Gruppen auflisten
</div>

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

Listet die für den Service-Schlüssel sichtbaren Gruppen auf. Auf Teams beschränkte Schlüssel listen alle Gruppen im Team auf; auf Gruppen beschränkte Schlüssel listen nur die ihnen zugewiesene Gruppe auf. Erfordert **Teams Read-Only**. Unterstützt `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">
  ## Gruppe abrufen
</div>

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

Liest eine Gruppe einschließlich ihrer Modell-Allowlists sowie der konfigurierten und effektiven ACU-Obergrenze. Erfordert **Teams Read-Only**. Nicht vorhandene, teamübergreifende und außerhalb des Geltungsbereichs liegende Gruppen geben `not_found` zurück.

```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">
  ## Gruppe erstellen
</div>

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

Erstellt im effektiven Team eine Gruppe mit dem angegebenen `name`. Erfordert **Teams Update**. Schlüssel mit Gruppen-Geltungsbereich können keine Gruppen erstellen.

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

Die Antwort enthält das erstellte `group`-Objekt.

<div id="update-group">
  ## Gruppe aktualisieren
</div>

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

Aktualisiert eine Gruppe atomar. Nur die in der Anfrage enthaltenen Felder werden geändert; nicht angegebene Felder bleiben unverändert. Eine Anfrage ohne Patch-Felder gibt `invalid_argument` zurück. Erfordert **Teams Update**.

<ParamField body="group_id" type="string" required>
  Die zu aktualisierende Gruppe.
</ParamField>

<ParamField body="name" type="string">
  Neuer Gruppenname.
</ParamField>

<ParamField body="cascade_models" type="object">
  `{"model_uids": [...]}` — ersetzt die Cascade-Modell-Allowlist der Gruppe. Die Übergabe einer leeren Liste hebt die Cascade-Einschränkung der Gruppe auf. Informationen dazu, wie Gruppen-Allowlists kombiniert werden, finden Sie unter [Model Provisioning](/de/federal/model-provisioning).
</ParamField>

<ParamField body="command_models" type="object">
  `{"model_uids": [...]}` — ersetzt die Command-Modell-Allowlist der Gruppe. Die Übergabe einer leeren Liste hebt die Command-Einschränkung der Gruppe auf.
</ParamField>

<ParamField body="set_cycle_acu_limit" type="number">
  Legt die ACU-Obergrenze der Gruppe pro Member und Abrechnungszeitraum fest. Muss positiv sein. Kann nicht zusammen mit `clear_cycle_acu_limit` verwendet werden.
</ParamField>

<ParamField body="clear_cycle_acu_limit" type="boolean">
  Entfernt die ACU-Obergrenze der Gruppe und stellt das Verhalten des Teams oder den Standard wieder her. In dieser Service-Key-API muss `set_cycle_acu_limit` endlich und positiv sein; verwenden Sie diesen expliziten Löschvorgang, um die Gruppenüberschreibung zu entfernen. Das Steuerelement für die Gruppen-ACU-Obergrenze im Portal akzeptiert `cycle_acu_limit: 0` als Anfrage zum Entfernen.
</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
  }'
```

Die Antwort enthält das aktualisierte `group`-Objekt.

<div id="delete-group">
  ## Gruppe löschen
</div>

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

Löscht eine Gruppe anhand der `group_id`. Das Löschen einer Gruppe, die bereits nicht mehr im möglichen Geltungsbereich des Schlüssels enthalten ist, wird erfolgreich ohne Änderungen ausgeführt. Erfordert **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">
  ## Gruppen-Member auflisten
</div>

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

Listet die aktuellen Member einer Gruppe auf. Erfordert **Teams Read-Only**. Unterstützt `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">
  ## Gruppenmitglieder hinzufügen
</div>

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

Fügt Nutzer des aktuellen Teams anhand ihrer E-Mail-Adressen zu einer Gruppe hinzu (`user_emails`, 1–1.000 Einträge). Erfordert **Teams Update**.

* Idempotent: Das Hinzufügen eines bereits vorhandenen Members ist ein erfolgreicher Vorgang ohne Änderungen.
* E-Mail-Adressen werden gekürzt und ohne Berücksichtigung der Groß- und Kleinschreibung dedupliziert.
* Alles oder nichts: Wenn eine E-Mail-Adresse unbekannt ist oder zu einem anderen Team gehört, wird die gesamte Anfrage abgelehnt und es werden keine Änderungen vorgenommen.

```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">
  ## Gruppen-Member entfernen
</div>

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

Entfernt Nutzer anhand ihrer E-Mail-Adresse aus einer Gruppe (`user_emails`, 1–1.000 Einträge). Erfordert **Teams Update**. Die Validierung erfolgt wie beim Hinzufügen von Gruppen-Membern nach dem Alles-oder-nichts-Prinzip; das Entfernen eines gültigen Nutzers, der kein Member ist, wird erfolgreich ausgeführt, ohne Änderungen vorzunehmen.

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