Plans and exceptions¶

This page shows how to look at an organisation's service, and how, for an organisation below yours, you give and remove plans, set exceptions, set up a trial and decide a demo's end date. What the service, plans, exceptions and demos are is in Your organisation's service.

The service has no screen in OS yet: you manage it through the API. The examples use $OS, $TOKEN and $ORG as in Manage groups, and also $CUSTOMER, the id of the organisation below yours whose service you set up.

Who may do what¶

So you always change an organisation's service from the organisation above it, never in the organisation itself. A partner sets up its customers' services this way, and a customer with departments those of its departments. What you give lies inside your own organisation's service: OS refuses a plan or an added item that reaches beyond it. An exception that takes something away is always allowed, because it only makes the service smaller.

What Artific set on one of your customers you cannot remove as a partner: only someone acting from the organisation that set it, or one above it, can. Ask Artific instead.

Artific puts the plans themselves together. If a plan lacks something your customers need, ask your contact at Artific.

Look at the service¶

curl -s "$OS/api/v1/organisations/$CUSTOMER/service" -H "Authorization: Bearer $TOKEN"

{"organisation_id": "org_...",
 "items": [{"kind": "agent", "actions": ["see", "use"]},
           {"kind": "knowledge_collection", "actions": null},
           {"kind": "thread", "actions": null}],
 "demo_ends_at": null,
 "allowed_actions": ["see", "write"],
 "parent_allowed_actions": ["see", "write"]}

• items is what the service holds now: its plans and exceptions in force, inside the service of the organisation above it. actions: null is every action the kind takes. What every service holds (always in the service) is not listed.
• demo_ends_at is a demo's end date, and null for every other organisation.
• allowed_actions says what you may do with the service in the organisation itself: see is reading it.
• parent_allowed_actions says what you may do with the service in the organisation above it. When it holds write, you may give and remove plans and exceptions and set a demo's end date.

With your own $ORG you read your own organisation's service the same way.

Which plans you can give¶

curl -s "$OS/api/v1/organisations/$ORG/assignable-plans" -H "Authorization: Bearer $TOKEN"

These are Artific's plans that lie inside your own organisation's service: what you can give the organisations below yours. Each plan has an id (pln_...), a name and its items. The list comes in pages; a page may hold fewer rows than limit while next_cursor still continues.

Give a plan¶

curl -s -X POST "$OS/api/v1/organisations/$CUSTOMER/service/plans" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"plan_id": "pln_..."}'

OS answers 201 with the plan given:

{"id": "opl_...", "plan_id": "pln_...", "plan_name": "Assistants",
 "starts_at": "2026-11-01T00:00:00Z", "ends_at": null, "in_force": true,
 "set_by": "...", "created_at": "2026-11-01T00:00:00Z",
 "allowed_actions": ["see", "write"]}

• starts_at is optional: when the plan comes into force. Without it, that is now.
• ends_at is optional: when the plan ends. With an end date it is a trial.
• in_force says whether the plan applies now.
• id (opl_...) is the id of this plan at this organisation; you use it to remove it again.
• set_by is who gave the plan. The organisation's own administrators see null here.

An organisation has at most 20 plans, lapsed plans included.

Look at an organisation's plans¶

curl -s "$OS/api/v1/organisations/$CUSTOMER/service/plans" -H "Authorization: Bearer $TOKEN"

The list also shows lapsed plans and plans still to come into force; in_force says which apply now. You read one plan with GET .../service/plans/opl_....

Remove a plan¶

curl -s -X DELETE "$OS/api/v1/organisations/$CUSTOMER/service/plans/opl_..." \
    -H "Authorization: Bearer $TOKEN"

OS answers 204. The organisation's service shrinks at once. When you remove its last plan, it has the service of the organisation above it again (why).

Set an exception¶

An exception adds one item (add) or takes one away (remove):

curl -s -X POST "$OS/api/v1/organisations/$CUSTOMER/service/exceptions" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"effect": "add", "kind": "toolbox",
         "reason": "Pilot of the AI Toolbox for the legal team"}'

OS answers 201 with the exception, with an id (svx_...), in_force, set_by and reason. The organisation's own administrators see null in set_by and reason. An exception that takes something away wins over what the plans give. An organisation has at most 100 exceptions, lapsed ones included.

You list an organisation's exceptions with GET .../service/exceptions, and read one with GET .../service/exceptions/svx_.... You remove one with DELETE on that address; OS answers 204.

Set up a trial¶

A trial is a plan or an added exception with ends_at:

curl -s -X POST "$OS/api/v1/organisations/$CUSTOMER/service/plans" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"plan_id": "pln_...", "ends_at": "2026-12-01T00:00:00Z"}'

The end date lies after the start date, or after now when you give no start date. On the end date the trial ends by itself; you do not have to do anything. The AI features follow within a few minutes, and the organisation's audit trail records the end. The lapsed plan stays in the list, with in_force: false. If the customer wants to continue, give the plan again without an end date and remove the lapsed one.

A demo's end date¶

curl -s -X PUT "$OS/api/v1/organisations/$CUSTOMER/service/demo-end" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"ends_at": "2026-12-01T00:00:00Z"}'

This makes the organisation a demo: on the end date it is suspended, and thirty days later erased, unless organisations below it still exist (Demos). The date lies in the future. You move it by setting it again. OS answers with the service, as in Look at the service.

You convert a demo into an ordinary organisation by removing the end date, with {"ends_at": null}, and giving it an ordinary plan. Anyone who may change its service may do so. Removing the end date does not resume a suspended demo: resume it as well, as any other organisation.

When OS refuses¶