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

# Units and crew

> How units, crew membership and unit status work, and who is allowed to change each.

## Units

A unit is a callsign that can be dispatched: `MO12`, `TP 21`, `LA301`.

| Field | Notes |
| - | - |
| `callsign` | Unique. Letters, digits, spaces and hyphens, up to 24 characters, stored in capitals. |
| `agencyCode` | A short code such as `MET`, `LAS` or `LFB`. Free text for now; it is not yet tied to a department record. |
| `type` | `RESPONSE`, `PATROL`, `TRAFFIC`, `FIRE`, `AMBULANCE`, `SUPERVISOR` or `SPECIALIST` |
| `status` | See below |
| `incidentId` | The one incident the unit is assigned to, or null |
| `version` | Advances on every change. See [Optimistic concurrency](/concepts/optimistic-concurrency). |
| `crew` | The active crew members |

Units are never deleted. A unit with no crew is `OFF_DUTY`, and its callsign can be brought back into service later.

## Crew

A unit's crew is a list of Argus users, not names typed into a box.

* A crew member is an **active staff member on an active account**.
* A user can crew **one unit at a time**. The database enforces this.
* A unit carries **at most eight** crew.
* Each membership records when it began and ended. `identifier` is a snapshot of the person's display name when they joined.
* `GET /api/cad/units/{id}/crew` returns the full membership history, including people who have left.

One unit does not mean one person. Any client showing a unit should list every member of `crew`.

### Ways onto a unit

| Route | Who | Endpoint |
| - | - | - |
| Book on | The crew member | `POST /api/cad/me/unit/book-on` starts a unit with the caller as its first member |
| Join | The crew member | `POST /api/cad/me/unit/join` adds the caller to a unit that is on duty |
| Control | A dispatcher | `POST /api/cad/units` and `/units/{id}/edit` set the crew list by user ID |

Booking on with the callsign of an off-duty, empty unit reuses that unit, provided the agency and type match. If the callsign is already operational, the answer is 409: join it instead.

### Ways off a unit

* **Book off**, `POST /api/cad/me/unit/book-off`, ends the caller's own membership. It needs no permission beyond being signed in and being on the unit, so someone whose role has been removed can still leave.
* **Control** can remove a member by editing the crew list, or end every membership by setting the unit `OFF_DUTY`.

When the **last** member leaves, the unit goes `OFF_DUTY` and is withdrawn from any incident it was assigned to.

## Status

| Status | Meaning | On an incident? |
| - | - | - |
| `AVAILABLE` | Ready to be sent | No |
| `BUSY` | Committed, but not to an Argus incident | No |
| `UNAVAILABLE` | Not to be sent | No |
| `ASSIGNED` | Dispatched, not yet moving | Yes |
| `EN_ROUTE` | Travelling to the incident | Yes |
| `ON_SCENE` | Arrived | Yes |
| `OFF_DUTY` | No crew | No |

Status and assignment always agree. A unit is on an incident exactly when its status is `ASSIGNED`, `EN_ROUTE` or `ON_SCENE`. The database enforces this, so no request can leave a unit "available" while still attached to an incident.

### Who may set what

| Change | Control | Crew |
| - | - | - |
| `AVAILABLE`, `BUSY`, `UNAVAILABLE` while not on an incident | Yes | Yes |
| `EN_ROUTE`, `ON_SCENE` while on an incident | Yes | Yes |
| `ASSIGNED` | By assigning the unit to an incident | No |
| Leaving an incident | By releasing the unit, or closing the incident | No |
| `OFF_DUTY` | Yes, which ends every membership | Only by the last member booking off |

So, for a crew:

* **Control assigns incidents.** There is no way to self-assign.
* **A crew cannot clear its own incident.** Asking for `AVAILABLE` while assigned returns `409 CAD_CONFLICT`.
* **While assigned, a crew moves between `EN_ROUTE` and `ON_SCENE`.** While unassigned, between `AVAILABLE`, `BUSY` and `UNAVAILABLE`.
* A status applies to the whole unit, not to one member.

Only an `AVAILABLE`, crewed, unassigned unit can be dispatched.

## What a crew's client needs

`GET /api/cad/me/unit` returns everything an MDT shows: the unit, its crew, its status, and the full incident it is assigned to, including Control's notes. It returns `null` when the caller is not booked on.

Keep the unit's latest `version`. Every self-service change sends it back.


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