Skip to main content
API · v2.4 · REST

One surface.
Everything the console sees.

The HarborOS REST API exposes every vessel, alert, geofence, and analytics rollup that powers the console. Same surface the UI consumes. Runnable in under a minute.

Browse endpoints 60-second quickstart
harboros · shellLive
$ curl https://harboros.app/api/alerts?region=la_harbor
{
  "items": [
    {
      "vessel_name": "MV Jade Star",
      "vessel_mmsi": "538007493",
      "risk_score": 100,
      "recommended_action": "escalate",
      "signals": ["dark_transit", "geofence_breach"]
    }
  ],
  "total": 12
}
Quickstart

From clone to console in a minute.

01

Seed the database

cd backend
source venv/bin/activate
python -m app.seed
02

Start the API

uvicorn app.main:app --reload --port 3003
03

Launch the console

cd frontend
npm install
npm run dev

Or run both with ./start.sh from the repo root.

REST API

Core endpoints.

Every endpoint returns JSON. Pagination is offset-based. OpenAPI is served at /docs.

GET/api/regionsList all sectors with bounding boxes and centers.
GET/api/vessels?region={key}Paginated live vessels. Filters by region.
GET/api/vessels/{id}Full vessel detail — positions, signals, weather.
GET/api/alerts?status=activeTriage queue. Filter by status, region, limit.
POST/api/alerts/{id}/actionAcknowledge, dismiss, or escalate an alert.
GET/api/geofencesAll zones — TSS, restricted, exclusion.
GET/api/analytics/distributionRisk histogram and MARSEC tier counts.
GET/api/detection/metricsPrecision, recall, active/resolved counts.
GET/api/scenario/timelineDemo scenario timeline for presentations.
GET/api/satellite/infoSentinel-2 task status and coverage.
Example

Pull the LA Harbor alert queue.

bash
curl "http://localhost:3003/api/alerts?region=la_harbor&status=active&limit=50"
json
{
  "items": [
    {
      "id": "alert-...",
      "vessel_id": "vessel-538007493",
      "vessel_name": "MV Jade Star",
      "vessel_mmsi": "538007493",
      "risk_score": 100,
      "recommended_action": "escalate",
      "status": "active",
      "signals": ["dark_transit", "geofence_breach"]
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}
Stack

What it's built on.

Backend
Python · FastAPI · SQLAlchemy · Pydantic · SQLite
Frontend
Next.js 16 · React 19 · TypeScript · Tailwind CSS v4
Mapping
MapLibre GL · vector tiles · custom Sentinel style
Data
AISStream · Sentinel-2 L2A · NWS weather · NOAA charts
Ports
API 3003 · Console 2003 · OpenAPI at /docs

Questions? Open an issue.

The full OpenAPI schema is served by the backend — the console consumes the same surface you'd build against.