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

# WorkspaceGroup

> A WorkspaceGroup is a named collection that groups multiple workspaces together, enabling cross-workspace access management and shared membership

A WorkspaceGroup is a named collection that groups multiple workspaces together, enabling cross-workspace access management and shared membership. Groups are created by a specific person (the creator) and can contain any number of workspace slots via the WorkspaceGroupWorkspace join entity, and any number of members via WorkspaceGroupMembership. The entity carries its own lifecycle (created\_at, updated\_at, soft-deleted via deleted\_at) and is identified externally by a UUID while relying on an internal serial primary key for joins.

| Naming                          | Value                             |
| ------------------------------- | --------------------------------- |
| Object                          | WorkspaceGroup                    |
| Resource type (JSON:API `type`) | `workspace_group`                 |
| Collection / records root       | — <sub>(not a records root)</sub> |
| REST base                       | `/v1/workspace-groups`            |
| Entity class                    | `WorkspaceGroup`                  |

<Note>
  **Internal object.** Not currently exposed on the public REST API. The operations below describe the intended contract.
</Note>

## API operations

| Operation | Method & path                      | Status     |
| --------- | ---------------------------------- | ---------- |
| List      | `GET /v1/workspace-groups`         | 🟡 Planned |
| Retrieve  | `GET /v1/workspace-groups/{id}`    | 🟡 Planned |
| Create    | `POST /v1/workspace-groups`        | 🟡 Planned |
| Update    | `PATCH /v1/workspace-groups/{id}`  | 🟡 Planned |
| Delete    | `DELETE /v1/workspace-groups/{id}` | 🟡 Planned |

## Data model

### Attributes

| Field                | Type                                   | Required | Constraints                  | Allowed values | Description                                                                                                                                                                                          |
| -------------------- | -------------------------------------- | -------- | ---------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspace\_group\_id | string (UUID)                          | ✅ Yes    | unique                       | —              | Public-facing stable identifier for the group. Generated server-side via gen\_random\_uuid(); never supplied by the caller. Unique constraint enforced at the database level.                        |
| name                 | string (varchar 255)                   | ✅ Yes    | NOT NULL, max length 255     | —              | Human-readable label for the workspace group. Set at creation time. NOT NULL in the database; max 255 characters (MikroORM default varchar length).                                                  |
| created\_at          | 🔒 system — Date (timestamptz)         | ✅ Yes    | NOT NULL, set once on insert | —              | Timestamp of record creation. Set automatically by the MikroORM onCreate lifecycle hook; never supplied by the caller.                                                                               |
| updated\_at          | 🔒 system — Date (timestamptz)         | ⚪ No     | nullable                     | —              | Timestamp of the last update. Set by MikroORM onCreate and onUpdate lifecycle hooks; null until the first update after creation.                                                                     |
| deleted\_at          | 🔒 system — Date (timestamptz) \| null | ⚪ No     | nullable                     | —              | Soft-delete timestamp. Null means the record is active. Set to the deletion timestamp when the group is removed; the row is never physically deleted. All active queries filter deleted\_at IS NULL. |

### Relationships

| Name        | Type               | Required | Description                                                                                                                                                                             |
| ----------- | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| created\_by | to-one (ManyToOne) | ✅ Yes    | The People record of the person who created this workspace group. Foreign key created\_by\_pk references core\_api.peoples(pk). NOT NULL — every group must have an identified creator. |

### System-computed

* workspace\_group\_id — generated server-side via gen\_random\_uuid() default and randomUUID() application-side default; unique constraint enforced in DB
* created\_at — set automatically by MikroORM onCreate: () => new Date()
* updated\_at — set automatically by MikroORM onCreate and onUpdate: () => new Date()
* deleted\_at — managed by the soft-delete pattern; set by the service layer on logical deletion, never by the user directly

## Example

```json theme={null}
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "workspace_group",
    "attributes": {
      "workspace_group_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "EMEA Finance Team",
      "created_at": "2026-05-28T08:15:00.000Z",
      "updated_at": "2026-05-28T08:15:00.000Z",
      "deleted_at": null
    },
    "relationships": {
      "created_by": {
        "data": { "id": "d7e8f9a0-b1c2-3456-def0-123456789abc", "type": "person" }
      }
    }
  }
}
```

<sub>Source: `apps/api/src/database/entities/WorkspaceGroup.ts` · domain: workspace · tier: Platform</sub>