> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Organisations

> Top-level grouping for teams, API key issuance, and prompt-override templates.

## Overview

An **organisation** is the top-level controller boundary that sits above workspaces and users. A user may belong to **many** organisations via `user_organisations`, but has exactly one **current org** on `users.organisation_id` (the switcher context).

1. **Team identity** — current org drives workspace/session listings, org settings, and new API keys.
2. **API key ownership** — keys are scoped to an `organisation_id` so a team's keys are listed and audited together.
3. **Prompt overrides** — each team organisation has its own summary prompt override; every personal organisation shares one. **Session-scoped jobs** (summarisation, etc.) resolve it from `session.workspace_id → workspaces.organisation_id`, not from the user's current org after a switch.

**Kinds:** a `team` organisation is shared. Every real account also has exactly one `personal` organisation, created at its first login: only its owner is a member, it holds any number of private workspaces, and it can't be joined, managed, renamed or rebranded (409 for everyone, platform admins included). It is hidden from admin lists and shown as "Personal" in the switcher. Workspace lists show only the current organisation's workspaces. See [User lifecycle](https://docs.kair.is/flows/user-lifecycle.md).

**Recording tenancy:** when a session starts, `session.workspace_id` (and therefore org) is stamped once and stays immutable. Switching current org does not move in-flight recordings, change `device.active_session_id`, or rewrite `device.default_workspace_id`.

***

## Data model

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Stable identifier |
| `name` | string | Human-readable name (e.g. `"Acme Corp"`) |
| `slug` | string | Lowercase, hyphenated (e.g. `"acme-corp"`); auto-derived from name. Personal organisations use `personal-<user id>` |
| `kind` | `team` \| `personal` | Postgres enum `organisation_kind`; `personal` organisations are never displayed by name |
| `public_subdomain` | string \| null | Optional label for publish/join links on `https://{public_subdomain}.kair.is` (unique; reserved names rejected) |
| `created_at` | timestamp | |
| `updated_at` | timestamp | |

***

## Endpoints

### List organisations (admin only)

```
GET /api/admin/organisations
```

Returns all organisations on the platform, ordered by name.

**Response:**

```json theme={null}
{
  "organisations": [
    { "id": "...", "name": "Acme Corp", "slug": "acme-corp" },
    { "id": "...", "name": "Bravno", "slug": "bravno" }
  ]
}
```

Requires `role = admin`. Returns `403 Forbidden` for all other roles.

***

### Create an organisation (admin only)

```
POST /api/admin/organisations
```

```json theme={null}
{ "name": "Acme Corp" }
```

The `slug` is derived automatically: lowercased, spaces replaced with `-`. Returns `409 Conflict` if the slug already exists.

**Response:**

```json theme={null}
{ "id": "...", "name": "Acme Corp", "slug": "acme-corp", "public_subdomain": null }
```

***

### Set public subdomain (admin only)

```
PATCH /api/admin/organisations/{organisation_id}/public-subdomain
```

```json theme={null}
{ "public_subdomain": "acme-lab" }
```

Use an empty string to clear. Validates lowercase `[a-z0-9-]+` and rejects reserved names (`default`, `staging`, `innover`, `10x100`, `pr{N}`, etc.). Returns `409 Conflict` if the subdomain is already assigned to another org.

When set, workspace publish/share links for bundles in that org copy `https://{public_subdomain}.kair.is/workspaces/{id}/join?code=…` instead of `kair.is`.

***

### List own organisation memberships

```
GET /api/organisations/mine
```

Returns every organisation the caller belongs to, Personal first and then team organisations by name, with `kind` and `is_current` marking `users.organisation_id`. Each entry also includes `has_icon` and `icon_revision` so the org switcher can load logos for **all** memberships, not only the current org.

```json theme={null}
{
  "organisations": [
    {
      "id": "...",
      "name": "10x100",
      "slug": "10x100",
      "kind": "team",
      "is_current": true,
      "has_icon": true,
      "icon_revision": 2
    },
    {
      "id": "...",
      "name": "KOMMA",
      "slug": "komma",
      "kind": "team",
      "is_current": false,
      "has_icon": true,
      "icon_revision": 1
    }
  ]
}
```

***

### Organisation icon

```
GET /api/organisations/me/icon
GET /api/organisations/mine/{organisation_id}/icon
```

Returns the uploaded appearance icon as binary (`Content-Type` from the stored MIME). `/me/icon` is the caller's **current** org. `/mine/{organisation_id}/icon` works for any org the caller belongs to (403 if not a member, 404 if none uploaded). Query `?v={icon_revision}` is a cache buster only.

***

### Switch current organisation

```
POST /api/organisations/switch
```

```json theme={null}
{ "organisation_id": "<uuid>" }
```

Must be a member (`user_organisations`). Sets `users.organisation_id`. Does **not** touch sessions, devices, or workspace membership. Switch events are recorded in `audit_trail` on `users` (and membership changes on `user_organisations`).

***

### Assign a user to an organisation (admin only)

```
PATCH /api/users/{user_id}/organisation
```

```json theme={null}
{ "organisation_id": "<uuid>", "set_as_current": true }
```

Adds membership if missing. When `set_as_current` is true (default), also updates `users.organisation_id`. When false, only adds membership without changing the user's current org. A personal organisation returns `404`.

```json theme={null}
GET /api/users/{user_id}/organisations
```

Lists all org memberships for a user (admin only).

**Response:**

```json theme={null}
{ "success": true, "message": "Organisation updated" }
```

***

### View own organisation

```
GET /api/organisations/me
```

Available to any authenticated user. Returns the caller's **current** organisation, including members of that org only.

**Response:**

```json theme={null}
{
  "id": "...",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "members": [
    { "id": "...", "email": "alice@acme.com", "name": "Alice", "role": "admin" },
    { "id": "...", "email": "bob@acme.com",   "name": "Bob",   "role": "moderator" }
  ]
}
```

Returns `404 Not Found` if the user has no organisation assigned yet.

***

## Relationship to API keys

Every API key has an `organisation_id`. When a moderator or admin creates a key:

1. The server validates that the supplied `organisation_id` matches the requesting user's own organisation — cross-org key creation is rejected with `400 Bad Request`.
2. The key appears in `GET /api/api-keys/org/{organisation_id}` for all moderators/admins in that org.

See [Authentication — User API keys](https://docs.kair.is/api/authentication.md#user-api-keys) for key creation details and workspace scoping.

***

## Relationship to prompt overrides

Overrides are stored in `customer_prompt_overrides` against `organisation_id`; `NULL` is the default shared by every personal organisation. Each save appends a row and the newest row wins, so a reset (a tombstone row) brings back the system prompt.

| Route | Does |
| - | - |
| `GET /admin/prompt-overrides` | The personal default (`target: "personal"`) and each team organisation (`target: <organisation id>`), with the active text |
| `GET /admin/prompt-overrides/{target}/history` | Every version, newest first |
| `PUT /admin/prompt-overrides/{target}` | Save a new version `{ "prompt_text": "…" }` |
| `DELETE /admin/prompt-overrides/{target}` | Reset to the system prompt |

Platform admins manage every target. Other moderators see and manage only their current team organisation's; the personal default and other organisations return `403`.

***

## Admin UI

Organisation management is available under **Admin → Users → Edit User**. The "Organisation" dropdown lists all organisations and includes an inline "Add new organisation" option that creates the org and selects it without leaving the modal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.