# Organisation et réglages

> Lire la vue d’ensemble et la liste « À faire », modifier l’identité et les réglages de l’organisation, la durée de conservation et l’annuaire des membres.

Toutes les routes sont sous `https://chat.realmoon.ai/api/v1/orgs/{org_id}`. Portées : `org:read` pour lire, `org:write` pour écrire, sauf pour l’annuaire (voir plus bas).

## Vue d’ensemble

`GET /overview` · `org:read`

```json
{
  "org": { "id": "8c1f2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b", "name": "Lycée Victor-Hugo", "slug": "lycee-victor-hugo", "description": null, "logo_url": null, "org_kind": "education", "managed": true, "created_at": 1751328000 },
  "members": { "active": 380, "suspended": 4 },
  "invitations_pending": 25,
  "groups": 42,
  "usage_scope": "workspace",
  "activity": {
    "active_30d": 295, "requests_30d": 18422, "active_7d": 241, "requests_7d": 5100,
    "month_pct_avg": 37.4,
    "top": [{ "user_id": "41ab2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "name": "Léa Dupont", "month_pct": 98.2 }]
  },
  "alerts": []
}
```

| Champ | Description |
| --- | --- |
| `members`, `invitations_pending`, `groups` | Compteurs ; `null` quand la clé n’a pas la portée qui les lit (`members:*`, `groups:*`). |
| `usage_scope` | `workspace` : l’utilisation des membres est comptée par l’organisation. `personal` : chaque membre utilise sa propre allocation, `activity` vaut `null`. |
| `activity` | Membres actifs et nombre de demandes sur 30 et 7 jours, moyenne de la limite du mois utilisée (en pourcentage), et les 5 membres les plus proches de leur limite. Demande `usage:read`. |
| `alerts` | La liste « À faire », comme `GET /alerts`. |

## Liste « À faire »

`GET /alerts` · `org:read`

Rend `{"items": [...], "total": n}`. Chaque élément : `code`, `severity` (`danger`, `warning` ou `info`), `title`, `detail`, `href` (page de l’administration), `count`, `params`. Une alerte n’est rendue que si la clé détient une des permissions qui la concernent.

| `code` | Sens | `params` |
| --- | --- | --- |
| `invitations_pending` | Invitations en attente. | `count` |
| `domain_unverified` | Domaines pas encore vérifiés. | `count` |
| `sso_not_configured` | Organisation gérée sans connexion unique. | `verified_domains` |
| `contract_ending` | Le contrat se termine dans 60 jours au plus, sans renouvellement. | `date`, `days` |
| `invoice_overdue` | Factures en retard de paiement. | `count` |
| `license_pool_full` | Un lot de licences est plein. | `pool_id`, `plan_name`, `seats`, `used` |
| `license_pool_nearly_full` | Un lot est rempli à 95 % ou plus. | les mêmes et `free` |
| `license_members_unlicensed` | Des membres actifs n’ont pas de licence. | `count` |
| `license_fallback_used` | Des membres sont dans le lot de repli. | `count` |
| `members_without_group` | Membres d’une organisation gérée qui ne sont dans aucun groupe. | `count` |
| `retention_will_delete` | Conversations que la conservation va supprimer. | `count`, `days` |
| `org_models_base_unavailable` | Modèles de l’organisation dont le modèle de base n’est plus proposé. | `count` |
| `org_models_not_shared` | Modèles de l’organisation partagés avec personne. | `count` |

Pour un traitement automatique, appuyez-vous sur `code` et `params` : `title` et `detail` sont écrits pour la console.

## Identité et réglages

### Lire

`GET /general` · `org:read`

```json
{
  "id": "8c1f2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
  "name": "Lycée Victor-Hugo",
  "slug": "lycee-victor-hugo",
  "description": "Établissement public",
  "logo_url": null,
  "created_at": 1751328000,
  "owner": { "id": "a11f3c5e-7b9d-4f1a-8c2e-4d6f8a0b2c4e", "name": "Claire Moreau", "email": "claire.moreau@ecole.fr" },
  "is_personal": false,
  "org_kind": "education",
  "org_kinds": ["team", "education", "company", "public_sector", "other"],
  "managed": true,
  "outside_access": true,
  "retention_days": 365,
  "retention_applied": true,
  "policy_version": 88,
  "members_active": 380,
  "retained_accounts": 0,
  "has_active_contract": true,
  "memory_policy": "allowed",
  "can": { "memory": false, "edit": true, "policies": true, "transfer": false, "delete": false, "platform": false }
}
```

| Champ | Description |
| --- | --- |
| `managed` | Les fonctions d’[organisation gérée](https://realmoon.ai/documentation/organisations/organisations-gerees/) sont actives : les règles s’appliquent. |
| `outside_access` | `true` : les membres peuvent aussi utiliser Moon AI hors de l’organisation. |
| `retention_days` | Durée de conservation des conversations, de 30 à 3 650 jours ; `null` : rien n’est supprimé. |
| `retained_accounts` | Membres retenus dans l’organisation (organisation gérée avec l’accès extérieur fermé). |
| `has_active_contract` | L’organisation a un contrat actif ; `null` s’il n’a pas pu être lu. |
| `can` | Ce que la clé peut changer ici. `transfer` et `delete` sont toujours faux avec une clé. |

### Modifier

`PATCH /general` · `org:write`

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `name` | chaîne | non | 1 à 128 caractères. |
| `slug` | chaîne | non | 2 à 50 caractères : lettres minuscules, chiffres et tirets, sans tiret au début ni à la fin. |
| `description` | chaîne | non | 2 048 caractères au plus ; vide ou `null` l’efface. |
| `logo_url` | chaîne | non | Adresse `http` ou `https` ; vide ou `null` l’efface. |
| `org_kind` | chaîne | non | `team`, `education`, `company`, `public_sector` ou `other`. Il change le nom des rôles fournis. |
| `managed` | booléen | non | Activer les fonctions d’organisation gérée (contrat actif exigé). |
| `outside_access` | booléen | non | `false` ferme l’accès hors de l’organisation (contrat actif exigé). |
| `retention_days` | entier | non | 30 à 3 650 ; `null` retire la conservation. |

Seuls les champs envoyés sont traités. `managed`, `outside_access` et `retention_days` demandent en plus la portée `rules:read` ou `rules:write`. La réponse a la forme de la lecture.

```bash title="cURL"
curl -X PATCH https://chat.realmoon.ai/api/v1/orgs/$ORG_ID/general \
  -H "Authorization: Bearer $MOONAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lycée Victor-Hugo", "retention_days": 365}'
```

```python title="Python"
import os
import requests

r = requests.patch(
    f"https://chat.realmoon.ai/api/v1/orgs/{os.environ['ORG_ID']}/general",
    headers={"Authorization": f"Bearer {os.environ['MOONAI_ADMIN_KEY']}"},
    json={"name": "Lycée Victor-Hugo", "retention_days": 365},
    timeout=30,
)
r.raise_for_status()
print(r.json()["retention_days"])
```

```javascript title="JavaScript"
const r = await fetch(`https://chat.realmoon.ai/api/v1/orgs/${process.env.ORG_ID}/general`, {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${process.env.MOONAI_ADMIN_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Lycée Victor-Hugo', retention_days: 365 }),
});
if (!r.ok) throw new Error(await r.text());
console.log((await r.json()).retention_days);
```

| Statut | `code` | Cause |
| --- | --- | --- |
| 400 | `invalid_request` | Rien à modifier, champ invalide (`fields`), `null` pour `org_kind`, `managed` ou `outside_access`, règles invalides après le changement (`errors`). |
| 403 | `managed_needs_contract` | Activer `managed` ou fermer `outside_access` sans contrat actif. |
| 409 | `slug_taken` | L’identifiant est déjà pris par une autre organisation. |

Avec une organisation gérée et une durée de conservation, la suppression des conversations inactives depuis plus longtemps a lieu chaque nuit.

### Aperçu de la conservation

`GET /general/retention-preview?days=365` · `org:read`

Rend `{"days": 365, "count": 1204, "applied": true}` : le nombre de conversations du workspace qui n’ont pas été modifiées depuis `days` jours. `days` est obligatoire, de 30 à 3 650.

### Réglages seuls

`GET /settings` (`org:read`) et `PATCH /settings` (`org:write`) lisent et modifient `org_kind`, `managed`, `outside_access` et `retention_days`, avec les mêmes règles que `/general`, sans l’identité de l’organisation.

## Annuaire des membres

L’annuaire règle ce qu’un membre voit des autres membres.

`GET /directory` · `members:read`

```json
{ "value": null, "default": "groups", "effective": "groups", "options": ["all", "groups", "admins"] }
```

| Valeur | Ce qu’un membre voit |
| --- | --- |
| `all` | Tous les membres. |
| `groups` | Les personnes de ses groupes et des groupes qu’il gère, et les administrateurs. |
| `admins` | Les administrateurs seulement. |

`value` vaut `null` quand l’organisation suit le défaut : `groups` pour une organisation gérée ou d’enseignement, `all` sinon.

`PUT /directory` · `org:write`

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `value` | chaîne | non | `all`, `groups` ou `admins` ; `null` ou absent revient au défaut. |

## Voir aussi

- [Règles](https://realmoon.ai/documentation/api-organisations/regles/)
- [Licences et contrat](https://realmoon.ai/documentation/api-organisations/licences/)
- [Utilisation et journal](https://realmoon.ai/documentation/api-organisations/utilisation-et-journal/)

---

Documentation Moon AI › API des organisations › Organisation et réglages. Page : https://realmoon.ai/documentation/api-organisations/organisation/. 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.