Samna

Appearance

Register Resources ​

Before any user can act on the platform, the resources they will see have to exist. This example walks through the minimum set of writes a client makes once: an organization, a location and a bookable. Every later call hangs off the ids returned here.

All requests in this example are authenticated as the client with HTTP Basic on the Authorization header (the OAuth 2.1 client credentials grant). No user token yet.

1. Create an Organization ​

POST /organization

json
{
  "name": "Acme NYC",
  "type": "company",
  "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response:

json
{
  "data": {
    "id": "2cc61227-7c11-465f-beb4-76e58f311f1e",
    "name": "Acme NYC",
    "type": "company",
    "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "root_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "level": 0,
    "created_at": "2026-05-11T23:11:28.399408Z",
    "updated_at": "2026-05-11T23:11:28.399408Z"
  },
  "request_id": "18e11c61-b0e4-4334-959c-eeab6dc969a9",
  "count": 1
}

owner_id points at the parent organization. The first organization for a tenant is a root org and references itself; child orgs reference the parent.

2. Create a Location ​

POST /location

json
{
  "name": "Oslo HQ",
  "type": "location",
  "owner_id": "2cc61227-7c11-465f-beb4-76e58f311f1e"
}

owner_id is the organization that owns the location. Omit parent_id for a top level site. To nest deeper locations (floor, wing, room), set parent_id to the id of the parent location.

3. Create a Bookable ​

POST /bookable

json
{
  "name": "Conference Room A",
  "description": "12 person meeting room with projector",
  "type_id": "ccd5ee31-c122-4182-b46a-dea38b2c373a",
  "location_id": "<location id from step 2>",
  "owner_id": "2cc61227-7c11-465f-beb4-76e58f311f1e"
}

type_id is optional. If you are categorizing resources, create the Bookable Type first through POST /bookable_type and reference it here. location_id is also optional, but most resources do live somewhere.

What This Sets Up ​

After these three writes, the client owns:

  • An organization that anchors ownership for everything beneath it.
  • A location that scopes the physical placement of resources.
  • One bookable that can hold bookings.

The next step is access. Continue with Token User to expose these resources to an end user.

Going Further ​

The same shape applies to the rest of the model:

  • Timeslot controls when the bookable is open.
  • Capability carries dynamic properties on any of the resources above.
  • Code makes a bookable reachable through a shareable link or QR.

Each has its own create endpoint listed under its tag in the Bookable API.