# Étiquettes

> Créer des étiquettes clé et valeur, les poser sur des membres, des groupes ou des ressources, et marquer une ressource sensible par l’API d’administration.

Une étiquette est une paire `clé = valeur`, par exemple `site = Lyon` ou `classe = 3A`. Une étiquette de **membre** décrit une personne : elle fait entrer dans les [groupes dynamiques](https://realmoon.ai/documentation/api-organisations/groupes/#regle) et peut donner des [rôles](https://realmoon.ai/documentation/api-organisations/roles/#attribuer). Une étiquette de **sensibilité** se pose sur une ressource (base de connaissances, agent, serveur MCP, fichier) pour en limiter l’accès.

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

## L’objet étiquette

```json
{
  "id": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "org_id": "8c1f2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
  "key": "classe",
  "value": "3A",
  "color": "blue",
  "kind": "member",
  "source": "manual",
  "created_at": 1793836800
}
```

| Champ | Description |
| --- | --- |
| `key` | Mise en minuscules, espaces réduits ; lettres, chiffres, espaces, `_`, `.` et `-`, 64 caractères au plus. |
| `value` | Espaces réduits, casse gardée, 128 caractères au plus, sans `\|`. |
| `color` | `gray`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink` ou `rose`. |
| `kind` | `member` ou `sensitivity`. |
| `source` | `manual`, ou `directory` pour une étiquette venue de l’annuaire. |

Deux étiquettes ne peuvent pas avoir la même clé et la même valeur (sans tenir compte de la casse). Dans les listes, chaque étiquette porte aussi `member_count` et `assignment_count`.

## Lister les étiquettes

`GET /labels` · `labels:read`

| Paramètre | Type | Description |
| --- | --- | --- |
| `q` | chaîne | Recherche dans la clé ou la valeur. |
| `kind` | chaîne | `member` ou `sensitivity`. |
| `key` | chaîne | Seulement cette clé. |
| `page`, `limit` | entier | Pagination. Tri par clé puis valeur. |

La réponse ajoute `colors`, la liste des couleurs permises.

## Créer une étiquette

`POST /labels` · `labels:write`

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `key` | chaîne | oui | 1 à 64 caractères. |
| `value` | chaîne | oui | 1 à 128 caractères. |
| `color` | chaîne | non | `gray` par défaut. |
| `kind` | chaîne | non | `member` (par défaut) ou `sensitivity`. |

Une organisation a 5 000 étiquettes au plus. Une étiquette qui existe déjà répond `409 invalid_request` (« Cette étiquette existe déjà. »).

## Modifier une étiquette

`PATCH /labels/{label_id}` · `labels:write`

Champs facultatifs `key`, `value`, `color` et `kind`. Les membres et ressources étiquetés suivent la nouvelle clé ou valeur. Une étiquette nommée par la règle d’un groupe dynamique ne change ni de clé ni de valeur : `409 label_in_use`, avec `groups`, les noms des groupes concernés. Changez d’abord leur règle.

## Supprimer une étiquette

`DELETE /labels/{label_id}` · `labels:write`

Retire l’étiquette de tous les membres, groupes et ressources, et supprime les rôles qu’elle donnait. Réponse : `{"success": true}`. Refusé (`409 label_in_use`) tant qu’un groupe dynamique la nomme.

## Poser une étiquette

`POST /labels/{label_id}/assignments` · `labels:write`

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `subject_type` | chaîne | oui | `user` (membres), `group` ou `resource`. |
| `subject_ids` | liste | oui | 1 à 1 000 identifiants. |
| `resource_type` | chaîne | pour `resource` | `knowledge`, `agent`, `mcp_server` ou `library` (un fichier de la bibliothèque du workspace). |

```bash title="cURL"
curl https://chat.realmoon.ai/api/v1/orgs/$ORG_ID/labels/$LABEL_ID/assignments \
  -H "Authorization: Bearer $MOONAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject_type": "user", "subject_ids": ["<id de membre>", "<id de membre>"]}'
```

```python title="Python"
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']}"}

r = requests.post(
    f"{BASE}/labels/{os.environ['LABEL_ID']}/assignments",
    headers=HEADERS,
    json={"subject_type": "user", "subject_ids": ["<id de membre>", "<id de membre>"]},
    timeout=30,
)
r.raise_for_status()
print(r.json()["added"])
```

```javascript title="JavaScript"
const BASE = `https://chat.realmoon.ai/api/v1/orgs/${process.env.ORG_ID}`;
const r = await fetch(`${BASE}/labels/${process.env.LABEL_ID}/assignments`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.MOONAI_ADMIN_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ subject_type: 'user', subject_ids: ['<id de membre>', '<id de membre>'] }),
});
if (!r.ok) throw new Error(await r.text());
console.log((await r.json()).added);
```

Réponse : `{"success": true, "added": 2}`. Les sujets déjà étiquetés sont ignorés. Poser une étiquette sur des membres peut les faire entrer dans des groupes dynamiques et leur donner des rôles, tout de suite.

| Statut | `code` | Cause |
| --- | --- | --- |
| 400 | `invalid_request` | Étiquette de sensibilité sur des membres ; `resource_type` absent pour une ressource ou présent pour un membre ou un groupe. |
| 403 | `forbidden` | Poser une étiquette sur le créateur de la clé sans la permission de régler les groupes ; étiquette qui place des membres dans des groupes soumis à des règles ou qui attribue une licence, quand la clé n’agit que sur des groupes gérés. |
| 403 | `role_escalation` | L’étiquette donnerait des rôles que la clé n’a pas. |
| 403 | `license_change_forbidden` | Le changement ferait changer de lot de licences des membres ; il faut `licenses:write`. |
| 404 | `not_found` | Membres, groupe ou ressource introuvables. |

Poser une étiquette sur un groupe ou une ressource demande la permission de gérer les étiquettes ; sur des membres, celle de les poser.

## Retirer une étiquette

`DELETE /labels/{label_id}/assignments` · `labels:write`

Même corps que la pose (`resource_type` n’est pas lu). Réponse : `{"success": true, "removed": 2}`. Les sujets non étiquetés sont ignorés. Les membres peuvent sortir de groupes dynamiques et perdre des rôles.

## Voir aussi

- [Groupes](https://realmoon.ai/documentation/api-organisations/groupes/)
- [Ressources](https://realmoon.ai/documentation/api-organisations/ressources/#partage), pour l’étiquette de sensibilité d’un serveur MCP ou d’un partage

---

Documentation Moon AI › API des organisations › Étiquettes. Page : https://realmoon.ai/documentation/api-organisations/etiquettes/. Modifiée le 5 novembre 2026.

© 2026 Stellarr Studio SAS. Tous droits réservés. Moon AI, Moon Blur et Stellarr Studio sont des marques déposées à l’INPI.