Labels

A label is a key = value pair, for example site = Lyon or classe = 3A. A member label describes a person: it adds them to dynamic groups and can give them roles. A sensitivity label goes on a resource (knowledge base, agent, MCP server, file) to restrict access to it.

All routes are under https://chat.realmoon.ai/api/v1/orgs/{org_id}. Scopes: labels:read to read, labels:write to write.

The label object#Link to the The label object section

{
  "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
}

Two labels cannot have the same key and the same value (case-insensitive). In lists, each label also carries member_count and assignment_count.

List labels#Link to the List labels section

GET /labels · labels:read

The response also includes colors, the list of allowed colors.

Create a label#Link to the Create a label section

POST /labels · labels:write

An organization can have up to 5,000 labels. A label that already exists returns 409 invalid_request with the message Cette étiquette existe déjà. (this label already exists).

Update a label#Link to the Update a label section

PATCH /labels/{label_id} · labels:write

Optional fields key, value, color and kind. Labeled members and resources follow the new key or value. A label named in a dynamic group’s rule cannot change its key or value: 409 label_in_use, with groups, the names of the groups involved. Change their rule first.

Delete a label#Link to the Delete a label section

DELETE /labels/{label_id} · labels:write

Removes the label from every member, group and resource, and removes the roles it gave. Response: {"success": true}. Refused (409 label_in_use) as long as a dynamic group names it.

Assign a label#Link to the Assign a label section

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

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": ["<member id>", "<member id>"]}'

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": ["<member id>", "<member id>"]},
    timeout=30,
)
r.raise_for_status()
print(r.json()["added"])

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: ['<member id>', '<member id>'] }),
});
if (!r.ok) throw new Error(await r.text());
console.log((await r.json()).added);

Response: {"success": true, "added": 2}. Subjects that already have the label are skipped. Putting a label on members can add them to dynamic groups and give them roles, right away.

Putting a label on a group or a resource requires the permission to manage labels; on members, the permission to assign them.

Remove a label#Link to the Remove a label section

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

Same body as assigning (resource_type is ignored). Response: {"success": true, "removed": 2}. Subjects without the label are skipped. Members can leave dynamic groups and lose roles.

See also#Link to the See also section

• Groups
• Resources, for the sensitivity label of an MCP server or a share