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

# Risk Intelligence

> Thirteen-factor vessel risk scoring with dark fleet detection, STS transfers, loitering, identity changes, draft anomalies, and PSC inspection signals.

13-factor risk scoring, dark fleet detection, STS transfers, loitering, identity changes, and draft anomalies.

## Risk tiers

Every dark event is scored 0–100 across 13 weighted factors (gap duration, gap frequency, location proximity to STS hotspots, flag state, vessel age, vessel type, prior history, sanctions match, STS involvement, draft anomaly, loitering, identity manipulation, P\&I coverage, and obfuscation). The numeric score is then bucketed into a `risk_tier` for filtering and alerting.

| Tier       | Score range | Approximate population share   |
| ---------- | ----------- | ------------------------------ |
| `low`      | 0 – 15      | \~p65 — most isolated AIS gaps |
| `medium`   | 16 – 25     | \~p65–p93                      |
| `high`     | 26 – 35     | \~p93–p99.5                    |
| `critical` | 36 – 100    | top \~0.5%                     |

These thresholds are calibrated against the real production score distribution, where most dark events are isolated AIS gaps with zero contribution from compounding factors like sanctions matches or STS involvement. Use `risk_tier=high,critical` to focus on the small subset of events that warrant active investigation, and use `risk_score` directly when you need finer-grained filtering than the tier boundaries provide.

The tier value is stamped on every event returned by `/api/v1/risk/events`, `/api/v1/risk/vessels`, and the `dark_event` webhook payload — see the [Webhooks API](/overwatch/api/webhooks) for the webhook envelope and [Watchlist API](/overwatch/api/watchlist) for tier-aware notification rules.

## `GET` `/api/v1/risk/vessels`

All risk-scored vessels. Filter by tier, type, or flag.

**Parameters**

| Name    | Type   | Required | Description                               |
| ------- | ------ | -------- | ----------------------------------------- |
| `tier`  | string |          | 'critical' \| 'high' \| 'medium' \| 'low' |
| `type`  | string |          | Vessel type                               |
| `flag`  | string |          | Flag state code                           |
| `limit` | number |          | Default 500                               |

**Response**

```json theme={null}
{ "vessels": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/vessels?tier=VALUE&type=VALUE
```

## `GET` `/api/v1/risk/vessel/{imo}`

Full risk profile for a single vessel including dark events.

**Parameters**

| Name  | Type   | Required | Description                     |
| ----- | ------ | -------- | ------------------------------- |
| `imo` | string | ✓        | 7-digit IMO number (path param) |

**Response**

```json theme={null}
{ "vessel": {...}, "dark_events": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/vessel/{imo}?imo=VALUE
```

## `GET` `/api/v1/risk/events`

Dark fleet AIS gap events. Filter by tier or vessel.

**Parameters**

| Name      | Type   | Required | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `tier`    | string |          | Risk tier filter            |
| `vessel`  | string |          | IMO number                  |
| `ongoing` | string |          | 'true' for active gaps only |
| `limit`   | number |          | Default 100, max 500        |

**Response**

```json theme={null}
{ "events": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/events?tier=VALUE&vessel=VALUE
```

## `GET` `/api/v1/risk/stats`

Aggregate risk statistics: active gaps, critical vessels, hotspots, events by tier.

**Response**

```json theme={null}
{ "active_gaps", "critical_vessels", "active_hotspots", "new_events_24h", "events_by_tier" }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/stats
```

## `GET` `/api/v1/risk/sts`

Ship-to-ship transfer events with confidence and draft transfer data.

**Parameters**

| Name         | Type   | Required | Description                      |
| ------------ | ------ | -------- | -------------------------------- |
| `confidence` | string |          | Confidence level filter          |
| `vessel`     | string |          | IMO number (checks both vessels) |
| `method`     | string |          | Detection method                 |
| `limit`      | number |          | Default 100, max 500             |

**Response**

```json theme={null}
{ "events": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/sts?confidence=VALUE&vessel=VALUE
```

## `GET` `/api/v1/risk/sts/stats`

STS aggregate statistics: total events, by confidence, tonnage, active encounters.

**Response**

```json theme={null}
{ "total_events", "by_confidence", "total_tonnage", "active_encounters" }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/sts/stats
```

## `GET` `/api/v1/risk/loitering`

Loitering events (stationary or slow-roll) with context zones.

**Parameters**

| Name      | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| `type`    | string |          | 'stationary' \| 'slow\_roll' |
| `vessel`  | string |          | IMO number                   |
| `context` | string |          | Context zone                 |
| `limit`   | number |          | Default 100, max 500         |

**Response**

```json theme={null}
{ "events": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/loitering?type=VALUE&vessel=VALUE
```

## `GET` `/api/v1/risk/identity`

Vessel identity change events (flag, name, MMSI).

**Parameters**

| Name     | Type   | Required | Description                |
| -------- | ------ | -------- | -------------------------- |
| `field`  | string |          | 'flag' \| 'name' \| 'mmsi' |
| `vessel` | string |          | IMO number                 |
| `limit`  | number |          | Default 100, max 500       |

**Response**

```json theme={null}
{ "events": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/identity?field=VALUE&vessel=VALUE
```

## `GET` `/api/v1/risk/identity/history`

Full identity history for a vessel.

**Parameters**

| Name     | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `vessel` | string | ✓        | IMO number  |

**Response**

```json theme={null}
{ "history": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/identity/history?vessel=VALUE
```

## `GET` `/api/v1/risk/mismatches`

Draft mismatch events: directional, magnitude, or zero-change anomalies.

**Parameters**

| Name     | Type   | Required | Description                                    |
| -------- | ------ | -------- | ---------------------------------------------- |
| `type`   | string |          | 'directional' \| 'magnitude' \| 'zero\_change' |
| `vessel` | string |          | IMO number                                     |
| `port`   | string |          | Port ID (UUID)                                 |
| `limit`  | number |          | Default 100, max 500                           |

**Response**

```json theme={null}
{ "events": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/mismatches?type=VALUE&vessel=VALUE
```

## `GET` `/api/v1/risk/hotspots`

STS hotspot zones (seeded and auto-discovered).

**Parameters**

| Name     | Type   | Required | Description                           |
| -------- | ------ | -------- | ------------------------------------- |
| `active` | string |          | Default 'true'. Pass 'false' for all. |
| `limit`  | number |          | Default 200, max 500                  |

**Response**

```json theme={null}
{ "hotspots": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/hotspots?active=VALUE&limit=VALUE
```

## `GET` `/api/v1/risk/baselines`

Port-level draft baselines used for anomaly detection.

**Response**

```json theme={null}
{ "baselines": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/risk/baselines
```