Licenses and contract

An organization under contract can have several license pools: each pool has one plan and a number of licenses. Rules place each member in a pool based on their roles, groups or labels; a fallback pool takes the members whose pool is full. An organization without pools has a single implicit pool, workspace, that covers everyone.

All routes live under https://chat.realmoon.ai/api/v1/orgs/{org_id}. Scopes: licenses:read to read, licenses:write to write. What each plan includes is on the Pricing page.

Read licenses#Link to the Read licenses section

GET /licenses · licenses:read

{
  "licensed": true,
  "pools": [
    { "id": "8f2c1a3e-5b7d-4c9f-a1e3-5b7d9f1a3c5e", "plan_id": "<plan id>", "plan_name": "Lune", "plan_slug": "lune", "seats": 3600, "used": 3412, "source": "contract", "contract_id": "<contract id>", "contract_line_id": "<line id>", "name": null, "period_start": 1756684800, "period_end": 1788220800, "is_fallback": true, "virtual": false },
    { "id": "41bd6e8f-0a2c-4e4a-8c6e-0a2c4e6a8c0e", "plan_id": "<plan id>", "plan_name": "Galaxie", "plan_slug": "galaxie", "seats": 400, "used": 398, "source": "contract", "contract_id": "<contract id>", "contract_line_id": "<line id>", "name": null, "period_start": 1756684800, "period_end": 1788220800, "is_fallback": false, "virtual": false }
  ],
  "rules": [
    { "id": "<rule id>", "pool_id": "41bd6e8f-0a2c-4e4a-8c6e-0a2c4e6a8c0e", "subject_type": "group", "subject_id": "<group id>", "subject_name": "Professeurs", "priority": 0 },
    { "id": "<rule id>", "pool_id": "8f2c1a3e-5b7d-4c9f-a1e3-5b7d9f1a3c5e", "subject_type": "default", "subject_id": null, "subject_name": null, "priority": 1000 }
  ],
  "fallback_pool_id": "8f2c1a3e-5b7d-4c9f-a1e3-5b7d9f1a3c5e",
  "members": 3810,
  "unlicensed": 0,
  "pending": 0,
  "reconciling": false,
  "license_version": 57,
  "can_manage": true,
  "manage_permission": "licenses.manage"
}

GET /licenses/mine (licenses:read) returns the license of the person who created the key: licensed, managed, org_name, pool_id, source, has_license, plan_id, plan_name, plan_slug. source says where the license comes from: manual, import, scim, invite, rule, default, fallback or unplaced. Another member’s license is shown in the member list.

Assignment rules#Link to the Assignment rules section

PUT /licenses/rules · licenses:write

Replaces the whole list of rules, then recalculates the pool of every member whose license comes from the rules.

The first rule that matches a member decides; the default rule (only one) always applies last. A group rule only covers the members of the group, not its managers. Licenses chosen by hand, by import, by the directory or by an invitation do not move.

curl -X PUT https://chat.realmoon.ai/api/v1/orgs/$ORG_ID/licenses/rules \
  -H "Authorization: Bearer $MOONAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rules": [
        {"pool_id": "<Galaxie pool>", "subject_type": "group", "subject_id": "<Professeurs group id>"},
        {"pool_id": "<Lune pool>", "subject_type": "default"}
      ]}'

import os
import requests

r = requests.put(
    f"https://chat.realmoon.ai/api/v1/orgs/{os.environ['ORG_ID']}/licenses/rules",
    headers={"Authorization": f"Bearer {os.environ['MOONAI_ADMIN_KEY']}"},
    json={"rules": [
        {"pool_id": os.environ["POOL_TEACHERS"], "subject_type": "group", "subject_id": os.environ["GROUP_TEACHERS"]},
        {"pool_id": os.environ["POOL_DEFAULT"], "subject_type": "default"},
    ]},
    timeout=60,
)
r.raise_for_status()
print(r.json()["changed"], "members changed license")

const r = await fetch(`https://chat.realmoon.ai/api/v1/orgs/${process.env.ORG_ID}/licenses/rules`, {
  method: 'PUT',
  headers: { Authorization: `Bearer ${process.env.MOONAI_ADMIN_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    rules: [
      { pool_id: process.env.POOL_TEACHERS, subject_type: 'group', subject_id: process.env.GROUP_TEACHERS },
      { pool_id: process.env.POOL_DEFAULT, subject_type: 'default' },
    ],
  }),
});
if (!r.ok) throw new Error(await r.text());
console.log((await r.json()).changed);

The response has the same shape as the read, with changed: the number of members whose license changed.

Fallback pool#Link to the Fallback pool section

PUT /licenses/fallback · licenses:write

Send at least {}. The response has the same shape as the read, with changed.

Assign by hand#Link to the Assign by hand section

POST /licenses/assign · licenses:write

{ "filter": { "group_id": "<group id>", "license": "none" }, "pool_id": "41bd6e8f-0a2c-4e4a-8c6e-0a2c4e6a8c0e" }

Response: {"changed": 12, "skipped": ["<id>"], "matched": 13, "fallback": 0, "unplaced": 0}. skipped lists the IDs that are not active members; fallback and unplaced count the members sent to the fallback pool or left without a license when they go back to the rules.

A member’s plan (features, limits, models) follows their license within seconds. When a pool becomes full, the license.pool_full webhook event is sent, at most once per day and per pool.

Contract and invoices#Link to the Contract and invoices section

GET /contract · licenses:read

Returns the organization’s contract and its invoices. The key must also have the right to read billing (or its creator must be the organization’s billing contact); otherwise the route returns 404.

contract is null when there is no active or ended contract. Its fields:

invoices lists the last 100 invoices, most recent first:

See also#Link to the See also section

• Licenses, in the admin console
• Members
• Organization and settings