M MarinaPSC
App Landing Swagger ReDoc OpenAPI
MarinaPSC API Reference

PSC screening endpoints, Readiness Packs, and fleet ranking

MarinaPSC exposes a thin FastAPI surface around the same readiness engine used by the CLI and batch tools. Use it to screen a single port call, rank a fleet schedule, inspect model artifacts, and generate case-scoped Readiness Packs from uploaded vessel evidence.

Quick Links

Swagger UI/docs ReDoc/redoc OpenAPI viewer/openapi Raw schema JSON/openapi.json Endpoint referenceLive schema

What This API Covers

  • Readiness screening: single-vessel IMO plus destination risk and action plan.
  • Fleet ranking: up to 100 port calls per request, sorted by detention probability.
  • Artifact telemetry: model hashes, metrics, and deployed source-manifest visibility.
  • Readiness Packs: case evidence becomes a crew briefing, evidence matrix, source trace, and recommendation-only worklist.

Authentication

All guarded MarinaPSC API routes live under /v1/. When MARINAPSC_API_TOKEN is configured, send it as a bearer token:

curl \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"imo":"9379478","destinationPort":"Rotterdam","destinationState":"Netherlands"}' \
  http://localhost:8000/v1/port-call-readiness
Demo mode: if MARINAPSC_API_TOKEN is not set, the API accepts requests without auth. That is useful for local demos and should not be treated as a production security posture.

Rate Limits

MarinaPSC applies in-memory sliding-window rate limiting per client IP, using proxy-forwarded identity when the app is behind a local reverse proxy.

Setting Default What it controls
MARINAPSC_RATE_LIMIT_PER_MINUTE 120 Allowed guarded requests per client inside one sliding window.
MARINAPSC_RATE_LIMIT_WINDOW_SECONDS 60 Window length used by the in-memory limiter.
MARINAPSC_MAX_REQUEST_BYTES 512000 Cap for guarded JSON request bodies.
MARINAPSC_DEMO_UPLOAD_MAX_REQUEST_BYTES 30000000 Cap for multipart demo upload requests.

Interactive Docs

The FastAPI schema surface is available alongside this guide:

  • Swagger UI: /docs
  • ReDoc: /redoc
  • OpenAPI viewer: /openapi
  • Raw schema JSON: /openapi.json

This page is the operator-facing summary. Swagger and ReDoc are the machine-backed views of the same request and response schema.

Endpoint Reference

GET /health

Service liveness probe. Returns {"status":"ok"}.

GET /v1/artifacts

Returns model and data artifact hashes plus metrics for deployment telemetry.

{
  "deficiencyModel": { "sha256": "...", "metrics": {} },
  "portCallRiskModel": { "sha256": "...", "metrics": {} },
  "tokyoRecon": { "manifest": {} },
  "hybridAi": { "enabled": false },
  "vesselParticulars": { "records": 33220 }
}
POST /v1/port-call-readiness

Builds one PSC readiness report for an IMO and destination pair.

{
  "imo": "9379478",
  "destinationPort": "Rotterdam",
  "destinationState": "Netherlands",
  "eta": "2026-05-15",
  "vesselName": "",
  "shipType": "",
  "flag": ""
}
Fallback behavior: if no structured vessel history is found, MarinaPSC still returns a limited or enriched-limited report using destination context, regulatory context, and any fallback particulars supplied in the request.
POST /v1/fleet-readiness

Scores and ranks a set of upcoming port calls by predicted detention probability.

{
  "persistQueue": true,
  "email": "ops@example.com",
  "companyName": "Example Ship Management",
  "consent": true,
  "portCalls": [
    {
      "imo": "9379478",
      "destinationPort": "Rotterdam",
      "destinationState": "Netherlands",
      "eta": "2026-05-15"
    }
  ]
}

Current cap: 100 port calls per request. With persistQueue, each ranked row gets a caseId; one-time caseAccessToken values are returned only in persistedCases for drill-down, evidence upload, and workflow tracking.

GET /v1/fleet-queue

Lists persisted fleet queue cases for an internal reviewer/operator view. Requires X-MarinaPSC-Reviewer-Token; case access tokens are never returned by this listing.

POST /v1/voyage-readiness

Resolves AIS/voyage destination text to known ports or LOCODEs, then runs the same ranked readiness workflow. Unresolved events are returned separately rather than guessed.

{
  "events": [
    {
      "imo": "9379478",
      "mmsi": "123456789",
      "aisDestination": "SGSIN",
      "eta": "2026-05-25"
    }
  ]
}

Each resolved report includes voyageSignal with raw destination text, resolved port/state/LOCODE, confidence, method, warnings, and score policy.

POST /v1/marinaais-voyage-readiness

Fetches live vessel records from internal MarinaAIS, converts successful hits into voyage readiness events, and ranks them with the same deterministic PSC scorer.

{
  "identifiers": ["9379478", "123456789"],
  "persistQueue": true,
  "email": "ops@example.com",
  "companyName": "Example Ship Management",
  "consent": true
}

Requires X-MarinaPSC-MarinaAIS-Adapter-Token and, when global API auth is configured, the normal bearer token too. The adapter only calls configured MarinaAIS hostports, never user-supplied URLs. MMSI-only responses without an IMO are returned as missing_imo failures and are not scored.

POST /v1/leads/upgrade

Captures follow-up interest after the free readiness screen.

{
  "email": "ops@example.com",
  "companyName": "Example Shipping",
  "imo": "9379478",
  "requestedAction": "request_detailed_review",
  "consent": true,
  "reportSnapshot": {}
}

Allowed actions: upgrade_ai_readiness, request_detailed_review, and upload_vessel_documents.

POST /v1/readiness-cases

Creates a paid/demo readiness case for vessel-specific evidence review.

{
  "email": "ops@example.com",
  "imo": "9379478",
  "destinationPort": "Rotterdam",
  "destinationState": "Netherlands",
  "eta": "2026-05-15",
  "consent": true,
  "reportSnapshot": {}
}

The response includes a one-time case.accessToken. Send it as X-MarinaPSC-Case-Token on case lookup, workflow update, evidence upload, PSC submission, Readiness Pack generation, and reasoning calls.

GET /v1/readiness-cases/{case_id}

Returns case metadata and attached evidence metadata. Requires X-MarinaPSC-Case-Token.

PATCH /v1/readiness-cases/{case_id}/workflow

Updates case-scoped fleet workflow fields such as readiness state, assigned owner, due timing, and ETA window. Requires X-MarinaPSC-Case-Token.

{
  "readinessState": "in_progress",
  "assignedOwner": "Fleet Superintendent",
  "dueBeforeEta": "Due in 2 days",
  "etaWindow": "2026-05-25 AM"
}
POST /v1/readiness-cases/{case_id}/evidence

Uploads case evidence for retrieval-backed readiness review. Requires X-MarinaPSC-Case-Token.

documentCategory=PSC Inspection Reports
files=@psc-report.pdf

Allowed case evidence extensions: .pdf, .csv, .txt, .jpg, .jpeg, and .png. Files are staged, pre-screened by the configured scan policy, and released only after the scan allows them. Direct text is classified locally; PDF/image extraction is deferred until manual Readiness Pack generation.

POST /v1/readiness-cases/{case_id}/readiness-pack

Generates an immutable versioned Readiness Pack for a case. Requires X-MarinaPSC-Case-Token and MARINAPSC_AI_ENRICHMENT_ENABLED=true.

{
  "reportSnapshot": {}
}

The pack contains crewBriefing, worklist, evidenceMatrix, and sourceTrace. Numeric detention risk is rebuilt deterministically server-side.

POST /v1/readiness-cases/{case_id}/psc-submissions

Records the actual PSC inspection outcome and closeout state against a readiness case. Operator submissions require X-MarinaPSC-Case-Token and stay pending. Final reviewer transitions require X-MarinaPSC-Reviewer-Token.

{
  "inspectionDate": "2026-05-15",
  "port": "Rotterdam",
  "authority": "Paris MoU",
  "result": "deficiencies_found",
  "detained": false,
  "deficiencies": [{"code": "07105", "description": "Fire doors"}],
  "correctiveActions": [{"owner": "Chief Engineer", "status": "closed"}],
  "reviewerStatus": "accepted"
}

The endpoint stores structured deficiency/CAPA details, verifies attachment evidence references, and writes an actor-attributed audit event. Only accepted or closed reviewer statuses mark the case psc_submitted; operator-submitted outcomes remain pending.

GET /v1/readiness-cases/{case_id}/psc-submissions

Lists post-inspection submissions for the case. Requires X-MarinaPSC-Case-Token.

POST /v1/readiness-cases/{case_id}/reasoning

Generates retrieval-backed missing evidence, analog signals, crew questions, citations, and targeted actions. Requires X-MarinaPSC-Case-Token and MARINAPSC_AI_ENRICHMENT_ENABLED=true.

Score policy: the endpoint rebuilds the deterministic report server-side and does not trust client snapshots for detention probability or risk tier.
POST /v1/demo-document-upload

Multipart demo upload intake for PSC reports and supporting evidence.

email=ops@example.com
imo=9379478
documentCategory=PSC Report
consent=true
files=@psc-report.pdf
Demo intake only: this path is intentionally lightweight. Production replacement should use authenticated or expiring case-scoped uploads, object storage, scanning, and audit events.

Deployment Notes

  • Structured request logs are emitted through the marinapsc.api logger with request id, latency, and failure class.
  • Artifact telemetry currently includes the deployed Tokyo mirror manifest, model hashes, port features, peer benchmarks, and vessel particulars counts.
  • Demo and case uploads are stored outside static/; case uploads are protected by case-scoped tokens and staged before metadata is committed.
  • Hybrid reasoning and Readiness Packs are feature-flagged and additive. Numeric risk remains owned by the deterministic port-call model.
  • The MarinaAIS adapter is disabled by default; enable it with MARINAPSC_MARINAAIS_ENABLED=true and configure MARINAPSC_MARINAAIS_ADAPTER_TOKEN outside local tests.
  • The public API is intentionally thin: most business logic stays inside the deterministic readiness report builder.
MarinaPSC API Guide. Human-readable docs page for the same FastAPI surface exposed through /docs, /redoc, and /openapi.json.