Some allowances limit how many things an organization keeps at once, not how much it uses: monitored targets, connected devices, active projects. An occupancy holds one slot of such an allowance for as long as the thing exists and gives it back when the thing goes away. Occupancies are not usage: they are not counted against the period, never reset and never billed.
What a slot is
The capability is of type COUNT, and its allowance in the organization's plan is the number of slots, rounded down. A slot is taken while its occupancy is CONFIRMED, or RESERVED and before its expires_at. When every slot is taken, the next reservation is refused.
Call the occupancy endpoints
The occupancy endpoints are in the Public API and take the end user's session token, so call them with the token of the end user who adds or removes the thing: from your page through your forwarded path, or from your backend with the token it received. The buyer organization and the application come from the token. Your SDK key cannot call them, and the Server SDK has no method for them.
| Call | Body | Answer |
|---|---|---|
POST /public/v1/occupancies/reserve | capability_key, and optionally ttl_seconds | 201 with a RESERVED occupancy. ttl_seconds is 1 to 3600, 300 by default |
POST /public/v1/occupancies/{occupancyId}/confirm | None | 200 with the occupancy CONFIRMED: the slot is held until it is released. Confirming again returns the same occupancy |
POST /public/v1/occupancies/{occupancyId}/release | None | 200 with the occupancy RELEASED: the slot is free again. Releasing again returns the same occupancy |
Each answer carries the occupancy in data: occupancy_id, capability_key, status, expires_at, confirmed_at, released_at and created_at.
Reserve, confirm, release
Reserve before you create the thing
POST /public/v1/occupancies/reserve with the capability key. If every slot is taken, or the organization's plan does not grant the capability, the answer is 409 OCCUPANCY_LIMIT_REACHED: refuse to create it, and offer a larger plan or removing another one.
Confirm once it exists
Confirm before expires_at. Keep the occupancy_id with the thing you created. An unconfirmed reservation stops holding its slot at expires_at, and confirming it afterwards is refused with 409 OCCUPANCY_NOT_RESERVED.
Release when it goes away
Release when the thing is deleted, and when creating it failed after the reservation.
What else sees the slots
- Rulings do not. A ruling of the Server SDK on the capability shows the allowance as
remaining, whatever is occupied. Decide with the reservation, not with a ruling. - The usage summary does.
GET /public/v1/usage/summaryshows the occupied slots asusedfor a capability held this way, soUsageMeterreads full exactly when the next reservation would be refused. - When the subscription ends, the allowance goes to 0: occupancies already held stay, and new reservations are refused. See When a subscription ends.