One identifier, three forms

The {id} segment on every user route takes any of three forms, resolved in this order:

This applies to reads, writes and deletes on the user itself and to every route beneath it, including settings, claim, organization, bookable, booking, code, location, asset, timeslot, search, available and audit. Responses keep carrying the canonical user_id, so a call made with an external reference still returns the stable id to store. An identifier that matches no user answers 404 on the routes beneath the user. See the access concept for how user access is resolved.

One booking list contract

GET /api/booking, /api/me/booking, /api/user/{id}/booking, /api/organization/{id}/booking, /api/location/{id}/booking, /api/bookable/{id}/booking and /api/bookable_type/{id}/booking share one parameter set:

The format values pick the row shape:

breaking A call without format now always answers schedule, one row per booking. Callers that relied on another default row shape pass format explicitly.

On row shaped responses count reports the rows in that response, and the pagination block carries the total match count across pages. The docs panel shows a captured example body per format on every one of these endpoints.

A person's own bookings

GET /api/user/{id}/booking answers with the bookings that person is attached to, rather than everything they are allowed to see. A booking counts when they created it, when they are a member of it, or when a grant names that booking directly.

Booking on someone's behalf through POST /api/user/{id}/booking now records them on the booking, so it shows up on their list the way a booking they made themselves does.

Add inherit=true to widen the answer to every booking that person can read, including the ones reaching them through an organization or location. The default is the narrower, direct view.

The caller still only ever sees what their own access allows, in both modes.

Everyone's real calendar

When POST /api/bookable/{id}/available projects members, each person's availability weighs both their own opening rules and the bookings they already hold. A member whose rules leave an afternoon open but who is booked inside it comes back unavailable for that afternoon.

The effect shows up in the aggregate answer and in the conflict list: an occurrence where one member is already committed lands in conflicts with that member named in unavailable_member_ids, and the overall available reads false.

Scheduling a booking across several people now converges on times the whole group can keep.

Ask for the range you want

start_date and end_date on POST /api/bookable/{id}/available narrow or widen the window independently of the schedule in the body. Omit either one and the range is taken from the candidate schedule instead.

An open ended recurrence has no latest end, so a call that projects one supplies end_date to say how far ahead to look. Both values are RFC3339.

This makes a single call serve two shapes: checking one proposed booking, and asking what a resource looks like across a month you name yourself.

One value to gate on

availability.available comes back on the bookable's block and on every projected member's block from POST /api/bookable/{id}/available. What it answers depends on what you asked:

The detailed windows stay exactly where they are, so a picker that renders individual slots keeps reading them while a simpler screen gates on the single value.

A slot for every day

vector_days on POST /api/bookable/{id}/available returns one entry per day between start_at and end_at. A day with nothing open comes back as an empty list rather than being left out, so the position of an entry in the array is the day it describes.

A client that renders a month view indexes into the array by day offset and gets the right cell every time, including for a resource that is closed for a stretch of the window.

Try the booking first

POST /api/bookable/{id}/available accepts a candidate booking in the body. schedule takes one schedule or an array of them and is required. members carries the people to project alongside it and defaults to empty. The signed in caller is always projected, whether or not they appear in members.

Every occurrence the schedule produces inside the date range is checked against the bookable and against each projected member.

Reading the verdict

The response carries an aggregate answer plus the detail behind it.

Each conflict names the occurrence and who it fails for:

{
  "occurrence_id": "c034d0f9-6f31-4af8-bf31-30da808c0418",
  "starts_at": "2030-06-03T10:00:00Z",
  "ends_at": "2030-06-03T11:00:00Z",
  "bookable": false,
  "unavailable_member_ids": []
}

bookable is true when the resource itself is free for the whole occurrence, and unavailable_member_ids lists the projected members who are not. A recurring proposal that works on most dates comes back with the handful of dates that do not, so a client can offer to drop them or shift them rather than failing the whole request.

Free means bookable

POST /api/bookable/{id}/available resolves the complete rule set on the bookable, including the rules it draws from its parent, its location, its owner and its type, and only reports a window free when all of them agree. A window that any one rule closes is reported closed.

The result is that the windows a picker renders and the windows POST /api/booking accepts are the same set.

The window travels with the answer

POST /api/bookable/{id}/available returns start_at and end_at on every availability block, filled from the range the request resolved to. A client that renders a calendar strip reads the bounds off the payload instead of holding on to the values it sent.

The same bounds appear on the bookable's own block and on each projected member's block, so every lane on a timeline lines up against one shared axis.

Who holds each place

Every membership row carries the identity resolved from the linked user, and keeps the invite details for a place that nobody has accepted yet.

The fields arrive on POST /api/booking/{id}/member, PUT /api/booking/{id}/member, DELETE /api/booking/{id}/member, DELETE /api/booking/{id}/member/{member_id} and on any booking list asked for with with=member.

One call for a guest list

An invited place that no one has accepted still answers with the address and reference it was invited under, so a pending seat and a filled seat read the same shape. Asking for with=user alongside with=member still embeds the full user record when you need more than the name.

Attendees on a room schedule

GET /api/bookable/{id}/booking honours with=member and returns the membership of every booking in the list. Combine it with with=user to embed the full user record alongside each place.

The behaviour matches the other booking listings, so the same client code reads a schedule whether it starts from a bookable, an organization, a location or a user.

Graph windowing

The graph endpoints /api/graph/owner, /api/graph/claim and /api/graph/relation now bound how much of the graph one call returns, so a large tree loads one window at a time instead of all at once.

When width is set the objects half of the response shrinks to the nodes that survived the window, so responses stay small end to end. A child cut by width takes its whole subtree with it, keeping every returned link connected. Fetch the first window with start_id and width, then pass the last received child as next_id to page through the rest.

Usage aware ordering

The platform now counts how often each signed in user opens an organization, location, bookable, bookable type, timeslot, claim, capability, action, code or asset. With sort=usage the graph fills each window with the objects that user opens most, falling back to alphabetical order for objects opened equally often.

Report documents

Add /report to any activity to render it. GET /api/activity/{function}/report returns one report and GET /api/activity/report returns a combined one built from several activities. The format parameter picks the output and defaults to pdf. A single activity renders as html, pdf or md and also returns its raw rows as csv or json; the combined report carries no single table, so it renders only as html, pdf or md. Pass timezone as an IANA name such as Europe/Oslo and every date and time in the document reads in that zone instead of UTC. See the reporting concept and the render activity reports example.

Branded templates

An organization brands its reports with its own templates, picked over the built in ones. Upload the template as an asset and set its id on the organization settings through PATCH /api/organization/{id}/settings, for a single function or for the combined report, and override it per request with the template parameter. The asset type marks the role a template plays:

See the asset concept.

Template functions

The template format and the functions below are highly likely to change. Treat custom templates as experimental and expect to revisit them.

A template embeds other assets by id, so logos and images live in the asset system and still print, and it runs activities and shapes tables through a small set of functions:

Concurrent bookings invoice

The concurrent_bookings report renders as a billing invoice. It takes the peak concurrent bookings in the window, matches it to its pricing tier, and lays out a NOK invoice with the billing period, the monthly charge, MVA, and the annual and discounted totals, followed by a per period breakdown. Ask for pdf for the printable invoice, html to read it inline, or json for the raw concurrency figures.

Name filter

Pass q (or query) to a listing to keep only the records whose name contains the value, case insensitive. It pairs with limit and paging, so a targeted lookup stays one request.

The filter is available on /api/organization, /api/location, /api/bookable, /api/bookable_type, /api/timeslot, /api/claim, /api/capability, /api/action, and /api/code, on the caller scoped /api/me/organization, /api/me/location, /api/me/bookable, /api/me/timeslot, /api/me/code, and /api/me/asset listings, and on their /api/user/{id}/... counterparts.

Activity on time

GET /api/activity reflects lifecycle events as they happen: the booking_ended event lands within seconds of the booking's end, and the checkin_started, checkin_failed, checkout_started, and checkout_failed events land as their windows open and close.

Recorded once

Each event is recorded exactly once, so activity reports and utilization figures never double count a booking that ends or a check in that opens.

Search filtering and scoping

GET /api/search applies every scope and exclusion in a single pass and returns a correct total_count for paging. Scope with org_ids, loc_ids, claim_id, type_ids, parent_id, or parent_type, and pare results with exclude_object_types, exclude_org_ids, exclude_loc_ids, exclude_query, usr_ids, and exclude_usr_ids. Results carry a stable order, so successive pages tile without dropping or repeating a row at the boundary.

Faster access changes

Creating or granting a claim that cascades across a large ownership or location structure returns much faster.

Claim object tree

GET /api/claim/{id}/object lists the objects a claim is bound to. Pass inherit=true to also include the objects the claim reaches through cascade, each row carrying inherited and its depth in the tree. Reading the list requires read access to the claim.

Claim graph access

GET /api/graph/claim now requires read access to the claim named by start_id, answering 404 for an unknown claim and 403 for one you cannot read.

User access across every endpoint

The access you hold on a user resolves identically on single reads, listings, and bulk checks, and applies the same regardless of how the user was added. Updating a user through PUT /api/user/{id} or PATCH /api/user/{id} checks the access you hold on that user, and the access filter on GET /api/user and GET /api/user/{id} (access=read, access=write, access=execute) returns exactly the users you hold that level on.

The three ways to add a user behave the same for access: created directly with POST /api/user, bridged from a sign in token with POST /api/user/token, or provisioned from an external system with POST /api/user/external.

Capability type labels

Capabilities now carry a free form type label. Set it on POST /api/capability, PUT /api/capability/{id}, or PATCH /api/capability/{id}, and it is returned on every capability response.

Organization updates

You can update an organization without restating its type. A PUT /api/organization/{id} that leaves out type keeps the current value, so an organization stays editable through the API.

Leaner search

Full text search was corrected and optimized with a faster access lookup, so results resolve consistently with your access and return faster.

Scoping a report to an object

The usage reports under GET /api/activity/{func} accept an object parameter written as object_type:object_id. Each anchor resolves through ownership, location, and parenthood, so a single organization or location pulls in every bookable beneath it.

Pass more than one object to combine anchors, for example object=organization:...&object=location:....

Reports default to everything you can see

When you leave object off, a report covers every object your access lets you read. The concurrent_bookings report no longer requires an anchor; without one it spans all the bookables you can read, matching the other reports.

Leaner activity reports

The activity reporting functions were streamlined and optimized further, so usage and booking popularity reports return faster and reflect every booking across the objects you can reach.

See the activity concept and the activity reports example.

Asset attachments

You can attach an asset to an object, list those attachments, reorder them, and detach them.

Attaching needs read access on the asset and write access on the object you attach it to. Attaching the same asset to the same object twice answers 409. See the asset concept.

Reading your assets

Creating an asset now grants you access to it straight away. Right after POST /api/asset you can call GET /api/asset/{id} for its record and GET /api/asset/{id}/data for the binary, and both answer 200. You can also reach an asset through any object you already have access to: if you can read the object an asset is attached to, you can read the asset and its data.

Image references on assets

banner_id and icon are validated when you send them.

• banner_id must point to an asset you can read whose content is an image, otherwise the request answers 400, or 404 when the referenced asset does not exist.
• icon accepts an icon name, a url, or the id of a readable image asset, and may not be empty.
• type sets the asset role: profile, banner or logo for images, activity_template or notification_template for templates, and null for a regular asset. The image roles require an image content type.

Activity reports

New reports are available under GET /api/activity/{func}.

The concurrent_bookings report now accepts one or more object anchors written as object_type:object_id, each resolved down to every bookable beneath it, together with a frequency of hour, day, week, month or year and a start_date and end_date window. The total_bookings_by_period report fills quiet buckets with zeros so every period in the range is returned, including the empty ones.

Breaking: the most_popular_hour report is no longer available. Use most_popular_booking for popularity buckets.

See the activity concept and the activity reports example.

Faster activity updates

Activity that depends on a booking finishing now updates promptly.

• A booking's booking_ended entry and the usage and popularity reports built on it appear right after the booking ends, instead of on a periodic catch up.
• Adding a booking that ends sooner than the next one already due moves that update forward automatically.
• After a restart the service restores its schedule from the next upcoming booking, so no booking end is missed or delayed.

Pagination with embedded relations

Paging through a list while embedding relations with with now works. The cursor no longer fails when a join shares the id column.

Sending access

Send access in whichever shape fits your client when you create or update a claim or a claim object binding. All four forms describe the same permission set.

On a claim, granting WRITE also grants READ and EXECUTE, so the stored permission can be wider than the literal value you send. A claim object binding keeps the exact value. The access levels guide lists every level name and the bit it maps to.

Reading access back

Responses always include access as an integer. Add format=slice for an access_slice array of level names, format=string for a pipe joined access_string, or pass both. Without format, only the integer access field is present.

GET /api/claim/{id}?format=slice&format=string

{
  "data": {
    "access": 14,
    "access_slice": ["EXECUTE", "READ", "WRITE"],
    "access_string": "EXECUTE|READ|WRITE"
  }
}

Where it applies

format works on every response that carries a claim, a claim object binding, or a user grant, including the create and delete responses and the list routes under /api/claim, /api/me/claim, and /api/user/{id}/claim. When you embed bindings or grants with with=claim_object or with=user_claim, the nested rows carry the readable fields too. A user grant renders the access of the claim it binds. The grant access example walks through creating a claim, binding it to a resource, and granting it to a user.