Investigations

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`

Requires API key with analyst access.

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

{
  "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

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`

Requires API key with analyst access.

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

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`

Requires API key with analyst access.

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

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`

Requires API key with analyst access.

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

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`

Requires API key with analyst access.

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

{
  "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

curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/vessels/9622629/signal-feedback

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

Requires API key with analyst access.

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

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`

Requires API key.

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

{
  "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

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

curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/vessels/9622629/risk-methodology

# 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

Overview

Vessels & ports

Risk & anomaly

Operations & throughput

Sustainability & fleet

Satellite & geo

Commodities

Insurance

Trade & market

Platform

Case files

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

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

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

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

Signal feedback

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

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

Signal explainability

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

Risk methodology

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

​Case files

​GET /api/v1/vessels/{imo}/case-files

​POST /api/v1/vessels/{imo}/case-files

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

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

​Signal feedback

​GET /api/v1/vessels/{imo}/signal-feedback

​POST /api/v1/vessels/{imo}/signal-feedback

​Signal explainability

​GET /api/v1/signals/explainability

​Risk methodology

​GET /api/v1/vessels/{imo}/risk-methodology

Case files

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

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

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

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

Signal feedback

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

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

Signal explainability

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

Risk methodology

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