Groupes

Un groupe réunit des membres. Un groupe statique contient les membres qu’on y ajoute ; un groupe dynamique contient aussi tous les membres qui portent les étiquettes de sa règle. Un groupe reçoit des rôles, des règles et des instructions ; ses gestionnaires agissent sur ses membres.

Toutes les routes sont sous https://chat.realmoon.ai/api/v1/orgs/{org_id}. Portées : groups:read pour lire, groups:write pour écrire.

L’objet groupe#Lien vers la section L’objet groupe

{
  "id": "3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b",
  "org_id": "8c1f2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
  "name": "Classe de 3A",
  "description": "Élèves de 3A, année 2026-2027.",
  "kind": "dynamic",
  "label_rule": { "all": [{ "key": "classe", "value": "3A" }] },
  "position": 10,
  "source": "manual",
  "created_by": "1f2e3d4c-5b6a-4987-8a6b-5c4d3e2f1a0b",
  "created_at": 1793836800,
  "updated_at": 1793836800
}

Dans les listes et GET /groups/{group_id}, chaque groupe porte aussi member_count (membres actifs, gestionnaires non comptés), manager_count, has_policy (il a des règles ou des instructions) et is_managed_by_me. GET /groups/{group_id} ajoute roles, les rôles attribués au groupe.

La règle d’étiquettes#Lien vers la section La règle d’étiquettes

{
  "all": [{ "key": "site", "value": "Lyon" }],
  "any": [{ "key": "service", "value": "Ventes" }, { "key": "service", "value": "Support" }]
}

• all : le membre porte toutes ces étiquettes. any : au moins une. Les deux ensemble : les deux conditions.
• Chaque condition est exactement {"key", "value"} ; la clé est mise en minuscules, la valeur se compare sans tenir compte de la casse.
• 20 conditions au plus. Chaque étiquette nommée doit exister (sinon 400, « Étiquettes inconnues : … »).
• {"all": []} est accepté à la création : le groupe ne retient alors personne.

Lister les groupes#Lien vers la section Lister les groupes

GET /groups · groups:read

Si le créateur de la clé ne gère que certains groupes, seuls ceux-là sont listés.

Créer un groupe#Lien vers la section Créer un groupe

POST /groups · groups:write

curl https://chat.realmoon.ai/api/v1/orgs/$ORG_ID/groups \
  -H "Authorization: Bearer $MOONAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Site de Lyon",
    "kind": "dynamic",
    "label_rule": {"all": [{"key": "site", "value": "Lyon"}]}
  }'

import os
import requests

BASE = f"https://chat.realmoon.ai/api/v1/orgs/{os.environ['ORG_ID']}"
HEADERS = {"Authorization": f"Bearer {os.environ['MOONAI_ADMIN_KEY']}"}

group = requests.post(
    f"{BASE}/groups",
    headers=HEADERS,
    json={"name": "Site de Lyon", "kind": "dynamic", "label_rule": {"all": [{"key": "site", "value": "Lyon"}]}},
    timeout=30,
)
group.raise_for_status()
print(group.json()["id"])

const BASE = `https://chat.realmoon.ai/api/v1/orgs/${process.env.ORG_ID}`;
const r = await fetch(`${BASE}/groups`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.MOONAI_ADMIN_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Site de Lyon', kind: 'dynamic', label_rule: { all: [{ key: 'site', value: 'Lyon' }] } }),
});
if (!r.ok) throw new Error(await r.text());
console.log((await r.json()).id);

Une organisation a 1 000 groupes au plus.

Lire un groupe#Lien vers la section Lire un groupe

GET /groups/{group_id} · groups:read

Rend le groupe avec ses compteurs et roles. 404 pour un groupe inconnu ou hors des groupes que la clé peut lire.

Modifier un groupe#Lien vers la section Modifier un groupe

PATCH /groups/{group_id} · groups:write

Changer la règle demande la permission de régler les groupes : la clé doit aussi avoir une portée rules:read ou rules:write. La nouvelle règle s’applique tout de suite : des membres entrent dans le groupe ou en sortent, avec ses rôles et ses règles. Si elle fait changer de lot de licences des membres, il faut aussi licenses:write (403 license_change_forbidden).

Supprimer un groupe#Lien vers la section Supprimer un groupe

DELETE /groups/{group_id} · groups:write

Supprime le groupe, ses membres, ses règles, ses instructions, ses rôles et ses étiquettes. Les membres restent dans l’organisation. Réponse : {"success": true}. 409 scim_managed pour un groupe venu de l’annuaire.

Membres d’un groupe#Lien vers la section Membres d’un groupe

Lister les membres#Lien vers la section Lister les membres

GET /groups/{group_id}/members · groups:read

Paramètres : q (nom, et adresse si la clé voit les adresses), page, limit. Liste les membres actifs et suspendus, ajoutés ou retenus par la règle. La réponse ajoute emails_visible.

{
  "items": [
    {
      "user_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "role": "member",
      "status": "active",
      "joined_at": 1793836800,
      "name": "Camille Durand",
      "email": "camille.durand@ecole.fr",
      "last_active_at": 1793923200,
      "never_active": false,
      "is_manager": false,
      "membership_source": "label",
      "dynamic": true
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50,
  "emails_visible": true
}

membership_source vaut manual, scim, sso, import, ou label pour un membre retenu par la règle seulement (dynamic: true). Chaque membre porte aussi ses groups, labels, roles, effective_roles et role_sources.

Chercher des membres à ajouter#Lien vers la section Chercher des membres à ajouter

GET /groups/{group_id}/candidates · groups:write

Paramètres : q (nom ; une adresse exacte si elle contient « @ » et que la clé voit les adresses), limit (1 à 50, 20 par défaut). Rend items (user_id, name, profile_image_url), total et limit, sans adresse. Exclus : les membres inactifs, le propriétaire, ceux déjà dans le groupe et ceux sur qui la clé ne peut pas agir.

Ajouter des membres#Lien vers la section Ajouter des membres

POST /groups/{group_id}/members · groups:write

Réponse : {"success": true, "added": 2, "updated": 0}. Les membres déjà présents sont ignorés (updated compte ceux dont is_manager a changé). 404 (« Membres introuvables : … ») si un identifiant n’est pas un membre actif.

Retirer des membres#Lien vers la section Retirer des membres

DELETE /groups/{group_id}/members · groups:write

Un membre par ?user_id=<id>, ou plusieurs par un corps {"user_ids": [...]} (500 au plus). Réponse : {"success": true, "removed": 1}. Un membre retenu par la règle d’un groupe dynamique y reste : retirez-lui l’étiquette.

Aperçu d’une règle#Lien vers la section Aperçu d’une règle

GET /groups/{group_id}/preview · groups:read

Liste les membres actifs que retiendrait une règle, sans rien enregistrer. Paramètre rule : la règle en JSON encodé dans l’adresse (8 192 caractères au plus, au moins une condition) ; sans rule, la règle du groupe. Rend items (user_id, name, email), la pagination et rule, la règle telle qu’elle a été lue.

curl -G "https://chat.realmoon.ai/api/v1/orgs/$ORG_ID/groups/$GROUP_ID/preview" \
  -H "Authorization: Bearer $MOONAI_ADMIN_KEY" \
  --data-urlencode 'rule={"all":[{"key":"site","value":"Lyon"}]}'

Voir aussi#Lien vers la section Voir aussi

• Étiquettes
• Rôles, pour donner un rôle à un groupe
• Règles, pour les règles et les instructions d’un groupe