> ## 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.

# Investigations

> Investigation case files, signal feedback, and explainability endpoints for vessel risk intelligence — close the loop between analysts and risk models.

Build investigation dossiers on any vessel by pulling together all risk signals, dark events, STS transfers, destination deceptions, and PSC inspections into a single case file. Analysts can annotate signals with feedback, export case files for compliance, and see step-by-step explanations of how each detection was made.

## Case files

### `GET` `/api/v1/vessels/{imo}/case-files`

<Note>Requires API key with analyst access.</Note>

Returns investigation case files for a vessel. Each case file is anchored to a motif alert and contains a timeline of corroborating evidence drawn from dark events, spoofing alerts, STS encounters, destination deceptions, draft anomalies, PSC inspections, and lifecycle changes.

**Parameters**

| Name     | Type   | Required | Description                                 |
| -------- | ------ | -------- | ------------------------------------------- |
| `imo`    | string | ✓        | 7-digit IMO number (path param)             |
| `limit`  | number |          | Number of case files to return. Default 20. |
| `offset` | number |          | Pagination offset. Default 0.               |

**Response**

```json theme={null}
{
  "cases": [
    {
      "case_id": "case:9622629:motif_alert:abc123",
      "anchor": {
        "motifAlertId": "abc123",
        "entityId": "IMO:9622629",
        "entityType": "vessel",
        "motifName": "dark_sts_cluster",
        "detectedAt": "2026-04-15T08:00:00Z",
        "severity": "critical",
        "confidence": 0.92
      },
      "evidence": [
        {
          "id": "dark:42",
          "kind": "dark_event",
          "occurredAt": "2026-04-14T18:00:00Z",
          "title": "AIS gap (14.2h)",
          "narrative": "AIS coverage dropped for 14.2h. Last known position was 1.2345, 103.8765.",
          "confidence": 0.88,
          "severity": "high",
          "sourceRefs": [{ "table": "dark_events", "id": "42" }],
          "locationName": "1.2345, 103.8765"
        },
        {
          "id": "sts:99",
          "kind": "sts_transfer",
          "occurredAt": "2026-04-15T02:00:00Z",
          "title": "STS encounter with IMO 9800001",
          "narrative": "Draft transfer correlation was detected. Estimated transferred cargo: 32,000 t.",
          "confidence": 0.85,
          "severity": "high",
          "sourceRefs": [{ "table": "sts_events", "id": "99" }]
        }
      ],
      "annotations": {
        "analystNotes": "Reviewed — consistent with known sanctions evasion pattern.",
        "analystUpdatedAt": "2026-04-16T10:00:00Z"
      }
    }
  ],
  "total": 5,
  "tier": "pro"
}
```

**Evidence kinds**

| Kind                    | Source                        | Description                                     |
| ----------------------- | ----------------------------- | ----------------------------------------------- |
| `dark_event`            | AIS gap detections            | Unexpected loss of AIS signal                   |
| `spoofing`              | Kinematic analysis            | Position data inconsistent with vessel physics  |
| `sts_transfer`          | Proximity + draft correlation | Ship-to-ship cargo transfer                     |
| `destination_deception` | Route analysis                | Declared destination doesn't match actual route |
| `draft_anomaly`         | Draft mismatch detection      | Unexpected draft change at port                 |
| `lifecycle_change`      | Registry monitoring           | Flag, name, owner, or MMSI change               |
| `psc_inspection`        | Port State Control            | Inspection results and detentions               |

**Example**

```bash theme={null}
curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/vessels/9622629/case-files?limit=5
```

### `POST` `/api/v1/vessels/{imo}/case-files`

<Note>Requires API key with analyst access.</Note>

Add analyst annotations to a case file — notes, status updates, or internal tags.

**Parameters**

| Name             | Type      | Required | Description                       |
| ---------------- | --------- | -------- | --------------------------------- |
| `imo`            | string    | ✓        | 7-digit IMO number (path param)   |
| `motif_alert_id` | string    | ✓        | Motif alert ID anchoring the case |
| `notes`          | string    |          | Analyst notes                     |
| `tags`           | string\[] |          | Internal classification tags      |

**Example**

```bash theme={null}
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://axiomoverwatch.io/api/v1/vessels/9622629/case-files \
  -d '{"motif_alert_id": "abc123", "notes": "Escalated to compliance team."}'
```

### `GET` `/api/v1/vessels/{imo}/case-files/export`

<Note>Requires API key with analyst access.</Note>

Export a case file as a compliance-ready bundle. Returns a JSON archive containing the case narrative, evidence items with source references, a SHA-256 manifest for integrity verification, and metadata.

**Parameters**

| Name      | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `imo`     | string | ✓        | 7-digit IMO number (path param)                        |
| `case_id` | string |          | Specific case ID. If omitted, exports the latest case. |

**Example**

```bash theme={null}
curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/vessels/9622629/case-files/export
```

### `GET` `/api/v1/vessels/{imo}/case-files/reconciliation`

<Note>Requires API key with analyst access.</Note>

Cross-reference a vessel's investigation data against supply chain entity records, trade mirror discrepancies, and sanctions matches. Use this to reconcile risk signals with trade intelligence.

**Parameters**

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

**Example**

```bash theme={null}
curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/vessels/9622629/case-files/reconciliation
```

***

## Signal feedback

### `GET` `/api/v1/vessels/{imo}/signal-feedback`

<Note>Requires API key with analyst access.</Note>

List all risk signals for a vessel with their adjudication status. Analysts use this to review signals, confirm true positives, mark false positives, and suppress repeat alerts.

**Parameters**

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

**Response**

```json theme={null}
{
  "signals": [
    {
      "signalType": "dark_event",
      "signalId": "dark:42",
      "title": "AIS gap (14.2h)",
      "summary": "AIS coverage dropped for 14.2h near Strait of Malacca.",
      "detectedAt": "2026-04-14T18:00:00Z",
      "severity": "high",
      "adjudicationStatus": "confirmed",
      "adjudicationReasonCode": "sanctions_evasion",
      "analystNotes": "Consistent with dark fleet pattern.",
      "suppressionWindowHours": null,
      "suppressionUntil": null,
      "suppressedRepeatCount": 0
    }
  ],
  "calibration": {
    "totalSignals": 12,
    "confirmed": 8,
    "falsePositives": 2,
    "pending": 2,
    "falsePositiveRate": 0.167
  }
}
```

**Example**

```bash theme={null}
curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/vessels/9622629/signal-feedback
```

### `POST` `/api/v1/vessels/{imo}/signal-feedback`

<Note>Requires API key with analyst access.</Note>

Submit adjudication feedback on a signal. You can confirm, dismiss, or suppress repeat signals for a configurable time window.

**Parameters**

| Name                | Type   | Required | Description                                                                 |
| ------------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `imo`               | string | ✓        | 7-digit IMO number (path param)                                             |
| `signal_id`         | string | ✓        | Signal identifier (e.g. `dark:42`)                                          |
| `signal_type`       | string | ✓        | Signal type (e.g. `dark_event`, `spoofing`, `sts_transfer`)                 |
| `status`            | string | ✓        | `confirmed`, `false_positive`, or `pending`                                 |
| `reason_code`       | string |          | Reason code (e.g. `sanctions_evasion`, `known_maintenance`, `data_quality`) |
| `notes`             | string |          | Analyst notes                                                               |
| `suppression_hours` | number |          | Suppress repeat signals for this many hours (4, 12, 24, 48, 168)            |

**Example**

```bash theme={null}
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://axiomoverwatch.io/api/v1/vessels/9622629/signal-feedback \
  -d '{
    "signal_id": "dark:42",
    "signal_type": "dark_event",
    "status": "confirmed",
    "reason_code": "sanctions_evasion",
    "notes": "Part of known dark fleet pattern."
  }'
```

***

## Signal explainability

### `GET` `/api/v1/signals/explainability`

<Note>Requires API key.</Note>

Get a step-by-step explanation of how a cargo estimate, motif detection, or spoofing alert was produced. Each response includes the inference chain, input data sources, and confidence at each step.

**Parameters**

| Name        | Type   | Required | Description                              |
| ----------- | ------ | -------- | ---------------------------------------- |
| `imo`       | string | ✓        | 7-digit IMO number                       |
| `type`      | string | ✓        | `cargo_estimate`, `motif`, or `spoofing` |
| `signal_id` | string |          | Specific signal or estimate ID           |

**Response**

```json theme={null}
{
  "imo": "9622629",
  "type": "cargo_estimate",
  "steps": [
    {
      "step": 1,
      "label": "Vessel identification",
      "description": "IMO 9622629 identified as bulk carrier, DWT 82,000.",
      "confidence": 1.0,
      "sources": ["vessel_registry"]
    },
    {
      "step": 2,
      "label": "Draft observation",
      "description": "Arrival draft 12.4m, departure draft 6.8m. Delta: 5.6m.",
      "confidence": 0.95,
      "sources": ["ais_positions"]
    },
    {
      "step": 3,
      "label": "Hydrostatic conversion",
      "description": "Applied TPC curve for Panamax bulker. Estimated cargo: 58,200 tonnes.",
      "confidence": 0.88,
      "sources": ["hydrostatic_tables", "ais_positions"]
    }
  ]
}
```

**Example**

```bash theme={null}
curl -H "X-API-Key: YOUR_KEY" \
  "https://axiomoverwatch.io/api/v1/signals/explainability?imo=9622629&type=cargo_estimate"
```

***

## Risk methodology

### `GET` `/api/v1/vessels/{imo}/risk-methodology`

Returns the full 14-factor risk score breakdown for a vessel, showing each factor's raw value, weight, and weighted contribution to the overall score. Optionally returns a PDF report.

**Parameters**

| Name     | Type   | Required | Description                     |
| -------- | ------ | -------- | ------------------------------- |
| `imo`    | string | ✓        | 7-digit IMO number (path param) |
| `format` | string |          | `json` (default) or `pdf`       |

**Risk factors**

| Factor                  | Weight | Description                                            |
| ----------------------- | ------ | ------------------------------------------------------ |
| `gap_duration`          | 9%     | Duration of AIS coverage gaps                          |
| `gap_frequency`         | 9%     | Number of gaps in the last 90 days                     |
| `location_risk`         | 9%     | Whether gaps occur in high-risk zones                  |
| `flag_state`            | 9%     | Flag of convenience or sanctioned registry             |
| `vessel_age`            | 5%     | Years since build                                      |
| `vessel_type`           | 2.5%   | Risk profile by vessel category                        |
| `prior_history`         | 5%     | Historical risk events                                 |
| `sanctions_match`       | 9%     | Ownership-based sanctions screening                    |
| `sts_involvement`       | 7.5%   | Ship-to-ship transfer activity                         |
| `draft_anomaly`         | 7.5%   | Unexplained draft changes                              |
| `loitering`             | 7.5%   | Time spent stationary or slow-rolling in unusual zones |
| `identity_manipulation` | 7.5%   | Flag, name, or MMSI changes                            |
| `pi_coverage`           | 7.5%   | Whether the vessel has P\&I club coverage              |
| `obfuscation_risk`      | 5%     | Composite deceptive behavior score                     |

**Example**

```bash theme={null}
curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/vessels/9622629/risk-methodology
```

```bash theme={null}
# Download a PDF risk report
curl -H "X-API-Key: YOUR_KEY" \
  "https://axiomoverwatch.io/api/v1/vessels/9622629/risk-methodology?format=pdf" \
  -o risk-report.pdf
```