# Equipment Usage & Maintenance API

REST endpoints for QM systems (e.g. Audittrails) that need to read equipment usage and maintenance data.

## Auth

`Authorization: Bearer <api_key>` — create per-org API keys with `read` scope in **Settings → API**.

## Endpoints

### `GET /v1/equipment`
List equipment in the active org. Standard list params: `limit`, `offset`, `order_by`, `order=asc|desc`, plus filters on allowlisted columns.

### `GET /v1/equipment/{id}`
Single equipment record including stammdaten, last/next maintenance, and `current_session_id`.

### `GET /v1/equipment/{id}/usage`
Paginated usage sessions, newest first.

Query params:
- `from` — ISO timestamp (inclusive, filters `started_at`)
- `to` — ISO timestamp (inclusive, filters `started_at`)
- `limit` (default 100, max 500), `offset`

Response: `{ data: UsageSession[], pagination: { limit, offset, total } }`

`UsageSession`:
```json
{
  "id": "uuid",
  "equipment_id": "uuid",
  "user_id": "uuid",
  "started_at": "2026-05-19T14:32:00Z",
  "ended_at": "2026-05-19T15:08:00Z",
  "duration_minutes": 36,
  "purpose": "Plasmid prep",
  "project_id": "uuid|null",
  "entry_id": "uuid|null",
  "settings": { "rpm": 4000, "duration_min": 10 },
  "notes": "string|null",
  "auto_closed": false,
  "used_with_overdue_maintenance": false
}
```

### `GET /v1/equipment/{id}/maintenance`
Paginated maintenance logs, newest completed first.

Same query params as `/usage` but filters on `completed_date`.

### `GET|POST|PATCH|DELETE /v1/equipment/{id}/remote`
Remote-access endpoint of the device. `POST` upserts (one endpoint per device) and
requires the `write` scope; `GET` requires `read`.

As soon as this endpoint is fed, a **Remote access** entry appears in LabNote under
*Equipment detail → Operation* with a button that opens `url` in a new tab.

```json
{
  "url": "https://hplc-07.lab.example.com",
  "label": "HPLC-07 web UI",
  "protocol": "https",
  "status": "online",
  "requires_vpn": true,
  "notes": "Login via lab SSO",
  "metadata": { "firmware": "3.4.1" }
}
```

`status` is one of `online | offline | maintenance | unknown`. Each write refreshes
`last_seen_at`, which the app shows as "last reported". `DELETE` removes the entry
and hides the button again.

## Webhooks

Configure endpoints in **Settings → Webhooks**. Each endpoint subscribes to a list of `event_type` names. Available events for equipment:

| Event | When |
|---|---|
| `equipment.usage.started` | A user starts a usage session (e.g. via QR scan). |
| `equipment.usage.completed` | A session ends — manually or auto-closed after the configured timeout. |
| `equipment.maintenance.completed` | A maintenance log is recorded with a `completed_date`. |

Deliveries are signed with `X-LabNote-Signature` (HMAC-SHA256 of the raw body using the endpoint's `signing_secret`). Retries with exponential backoff up to 5 attempts.

Example payload (`equipment.usage.completed`):
```json
{
  "event": "equipment.usage.completed",
  "data": {
    "session_id": "uuid",
    "equipment_id": "uuid",
    "user_id": "uuid",
    "started_at": "2026-05-19T14:32:00Z",
    "ended_at": "2026-05-19T15:08:00Z",
    "duration_minutes": 36,
    "purpose": "Plasmid prep",
    "project_id": null,
    "entry_id": "uuid",
    "settings": { "rpm": 4000 },
    "auto_closed": false
  }
}
```