{
  "openapi": "3.1.0",
  "info": {
    "title": "Rootz Shipping Intelligence",
    "description": "AI-readable global oil shipping data — trade flows, sanctions, fleet, prices, vessel emissions, document intelligence. 145K+ records from US and EU government sources, attested on Polygon.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://ship.rootz.global"
    }
  ],
  "paths": {
    "/api/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Database statistics — record counts by category",
        "responses": {
          "200": { "description": "Database status with record counts" }
        }
      }
    },
    "/api/intel/oil-flows": {
      "get": {
        "operationId": "getOilFlows",
        "summary": "Where is US-imported oil coming from? Top countries by volume with market share.",
        "parameters": [
          { "name": "period", "in": "query", "schema": { "type": "string" }, "description": "Period filter (e.g. 2026-01). Defaults to latest." }
        ],
        "responses": {
          "200": { "description": "US crude imports by country" }
        }
      }
    },
    "/api/intel/hormuz-premium": {
      "get": {
        "operationId": "getHormuzPremium",
        "summary": "Brent-WTI price spread as Hormuz disruption indicator. Normal is $3-8, current is $14+ crisis premium.",
        "responses": {
          "200": { "description": "Brent-WTI spread trend with Hormuz premium calculation" }
        }
      }
    },
    "/api/intel/terminal-activity": {
      "get": {
        "operationId": "getTerminalActivity",
        "summary": "Vessel positions by region from live AIS. Shows congestion, stationary vs moving vessels.",
        "responses": {
          "200": { "description": "Regional vessel activity and congestion" }
        }
      }
    },
    "/api/intel/rerouting": {
      "get": {
        "operationId": "getReroutingEvidence",
        "summary": "Evidence of oil shipping rerouting around Hormuz. Saudi volumes at 12-month high = Red Sea bypass working.",
        "responses": {
          "200": { "description": "Saudi monthly trend and rerouting evidence" }
        }
      }
    },
    "/api/sanctions": {
      "get": {
        "operationId": "searchSanctions",
        "summary": "Search OFAC sanctions list by vessel name, IMO number, company name, or keyword. 19,170 entities including 1,480 designated vessels.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search term — vessel name, IMO number (7 digits), company name, or keyword" }
        ],
        "responses": {
          "200": { "description": "Sanctions search results" }
        }
      }
    },
    "/api/sanctioned-at-eu": {
      "get": {
        "operationId": "getSanctionedAtEU",
        "summary": "Sanctioned vessels that called at EU ports. Cross-references OFAC sanctions with EU MRV emissions. 469 found across 2018-2024.",
        "parameters": [
          { "name": "year", "in": "query", "schema": { "type": "string" }, "description": "Filter by year (2018-2024)" }
        ],
        "responses": {
          "200": { "description": "Sanctioned vessels at EU ports with emissions data" }
        }
      }
    },
    "/api/emissions": {
      "get": {
        "operationId": "getEmissions",
        "summary": "EU MRV vessel emissions — CO2, fuel consumption, time at sea for 22,543 vessels (2018-2024).",
        "parameters": [
          { "name": "imo", "in": "query", "schema": { "type": "string" }, "description": "IMO number (7 digits)" },
          { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Ship type (e.g. Oil tanker, LNG carrier)" },
          { "name": "year", "in": "query", "schema": { "type": "string" }, "description": "Reporting year (2018-2024)" }
        ],
        "responses": {
          "200": { "description": "Vessel emissions records" }
        }
      }
    },
    "/api/prices": {
      "get": {
        "operationId": "getOilPrices",
        "summary": "WTI and Brent crude oil daily spot prices.",
        "parameters": [
          { "name": "benchmark", "in": "query", "schema": { "type": "string", "enum": ["WTI", "Brent", "all"] }, "description": "Price benchmark" },
          { "name": "days", "in": "query", "schema": { "type": "integer" }, "description": "Number of recent days (default 30)" }
        ],
        "responses": {
          "200": { "description": "Oil price data" }
        }
      }
    },
    "/api/fleet": {
      "get": {
        "operationId": "getFleet",
        "summary": "Tanker fleet database — 555 vessels across 12 companies including Bahri (Saudi), KOTC (Kuwait), ADNOC.",
        "parameters": [
          { "name": "company", "in": "query", "schema": { "type": "string" }, "description": "Company name (e.g. Bahri, Frontline, DHT)" },
          { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Vessel type (VLCC, Suezmax, Aframax, MR, LR2)" }
        ],
        "responses": {
          "200": { "description": "Fleet data" }
        }
      }
    },
    "/api/trade": {
      "get": {
        "operationId": "getTradeFlows",
        "summary": "Bilateral oil trade flows by country. 19,478 records from EIA (1973-2026) and Eurostat.",
        "parameters": [
          { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Country name or code (e.g. SAU, Saudi Arabia, IRQ, KWT)" },
          { "name": "period", "in": "query", "schema": { "type": "string" }, "description": "Period filter (e.g. 2026, 2025-06)" }
        ],
        "responses": {
          "200": { "description": "Trade flow records" }
        }
      }
    },
    "/api/cross-ref/oil-companies": {
      "get": {
        "operationId": "getOilCompanyCrossRef",
        "summary": "Cross-reference oil companies — links SEC-filed tanker companies to fleet data and Origin SEC earnings.",
        "responses": {
          "200": { "description": "Oil company cross-reference with fleet and SEC links" }
        }
      }
    },
    "/api/ebl-platforms": {
      "get": {
        "operationId": "getEBLPlatforms",
        "summary": "Electronic Bill of Lading platforms — 12 platforms, adoption status, technology.",
        "responses": {
          "200": { "description": "eBL platform data" }
        }
      }
    },
    "/api/mletr": {
      "get": {
        "operationId": "getMLETR",
        "summary": "MLETR (electronic trade document law) adoption by country — 23 countries tracked, 13 enacted.",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["enacted", "aligned", "in_progress", "studying", "not_started"] }, "description": "Filter by adoption status" }
        ],
        "responses": {
          "200": { "description": "Country adoption data" }
        }
      }
    },
    "/api/doc-fraud": {
      "get": {
        "operationId": "getDocFraud",
        "summary": "Documented shipping document fraud cases — $11.3B total across 6 major cases including Trafigura, Hin Leong, Russian shadow fleet.",
        "responses": {
          "200": { "description": "Fraud case database" }
        }
      }
    },
    "/api/doc-stats": {
      "get": {
        "operationId": "getDocStats",
        "summary": "Shipping document industry statistics — eBL adoption rates, fraud volumes, market data.",
        "responses": {
          "200": { "description": "Industry statistics" }
        }
      }
    },
    "/api/intel/documents": {
      "get": {
        "operationId": "getPublicDocuments",
        "summary": "Public shipping documents — 1,192 UK MAIB investigation reports indexed, tanker-related reports highlighted.",
        "responses": {
          "200": { "description": "Document index" }
        }
      }
    }
  }
}