Skip to main content
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
NameTypeRequiredDescription
imostring✓7-digit IMO number (path param)
limitnumberNumber of case files to return. Default 20.
offsetnumberPagination 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
KindSourceDescription
dark_eventAIS gap detectionsUnexpected loss of AIS signal
spoofingKinematic analysisPosition data inconsistent with vessel physics
sts_transferProximity + draft correlationShip-to-ship cargo transfer
destination_deceptionRoute analysisDeclared destination doesn’t match actual route
draft_anomalyDraft mismatch detectionUnexpected draft change at port
lifecycle_changeRegistry monitoringFlag, name, owner, or MMSI change
psc_inspectionPort State ControlInspection 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
NameTypeRequiredDescription
imostring✓7-digit IMO number (path param)
motif_alert_idstring✓Motif alert ID anchoring the case
notesstringAnalyst notes
tagsstring[]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
NameTypeRequiredDescription
imostring✓7-digit IMO number (path param)
case_idstringSpecific 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
NameTypeRequiredDescription
imostring✓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
NameTypeRequiredDescription
imostring✓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
NameTypeRequiredDescription
imostring✓7-digit IMO number (path param)
signal_idstring✓Signal identifier (e.g. dark:42)
signal_typestring✓Signal type (e.g. dark_event, spoofing, sts_transfer)
statusstring✓confirmed, false_positive, or pending
reason_codestringReason code (e.g. sanctions_evasion, known_maintenance, data_quality)
notesstringAnalyst notes
suppression_hoursnumberSuppress 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
NameTypeRequiredDescription
imostring✓7-digit IMO number
typestring✓cargo_estimate, motif, or spoofing
signal_idstringSpecific 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
NameTypeRequiredDescription
imostring✓7-digit IMO number (path param)
formatstringjson (default) or pdf
Risk factors
FactorWeightDescription
gap_duration9%Duration of AIS coverage gaps
gap_frequency9%Number of gaps in the last 90 days
location_risk9%Whether gaps occur in high-risk zones
flag_state9%Flag of convenience or sanctioned registry
vessel_age5%Years since build
vessel_type2.5%Risk profile by vessel category
prior_history5%Historical risk events
sanctions_match9%Ownership-based sanctions screening
sts_involvement7.5%Ship-to-ship transfer activity
draft_anomaly7.5%Unexplained draft changes
loitering7.5%Time spent stationary or slow-rolling in unusual zones
identity_manipulation7.5%Flag, name, or MMSI changes
pi_coverage7.5%Whether the vessel has P&I club coverage
obfuscation_risk5%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