Developer docs

Strait-Signal API Documentation

Base URL: https://api.obsidiandynamics.co.uk

Obsidian Alignment (v1 conventions)

Canonical cross-module conventions: /v1/maritime/events, /v1/nodes/{id}/risk, /v1/watchlists, /v1/alerts, and /v1/history/replay share vocabulary with sister modules.

Strait-Signal Module Context

This project is the dedicated maritime module. The richest production surfaces in this repository are maritime chokepoint risk, queue/dwell anomalies, route risk, and maritime alert workflows.

Reporting and Monetization Endpoints

GET/v1/account/usage

Usage and metering metrics for API calls, transition scores, replay events, and projected overage.

GET/v1/account/value

Estimated operational value generated from alerts, high-risk detection, and replay analysis.

Schema evolution reference: /api/changelog

The endpoints below under /api/* remain available as a compatibility layer for the current Strait-Signal module. New integrations should use /v1/*.

Locations

GET/api/locations

List all tracked chokepoints and ports with current risk summary.

GET/api/locations/{id}/current

Get full live metrics for a specific location.

id — Location identifier (e.g. suez, panama, singapore)

GET/api/locations/{id}/history

Get historical daily metrics for a location.

id — Location identifier
window — Time window: 7d, 30d, 90d, 365d (default: 30d)
start — Start date (YYYY-MM-DD)
end — End date (YYYY-MM-DD)

Route Risk

GET/api/routes/risk

Score route risk between two ports by the chokepoints it transits.

origin — UN/LOCODE (e.g. SGSIN)
destination — UN/LOCODE (e.g. NLRTM)

Alerts

GET/api/alerts

List active disruption alerts.

location_id — Filter by location (optional)
severity — Filter: info, warning, critical (optional)

Webhooks

POST/api/webhooks/test

Send a test webhook to verify your endpoint.

body: { "url": "https://your-server.com/hook" }

Data ExportTEAM+

GET/api/export/locations/{id}/csv

Export historical metrics for a location as CSV.

id — Location identifier
window — Time window: 7d, 30d, 90d, 365d (default: 30d)

FirehoseENTERPRISE

Real-time event stream for platform integrations and DaaS licensing. Available on Enterprise plans only.

GET/api/firehose/meta

Describe the firehose — available event types, tracked locations, and latest cursor position.

GET/api/firehose/events

Fetch events with cursor-based pagination. Poll this endpoint to ingest all StraitSignal data reliably.

cursor — Last event ID seen. Omit to start from the beginning.
limit — Max events per page: 1–1000 (default: 100)
event_type — Filter: metric.updated, vessel.observed, weather.updated, disruption.created, disruption.resolved, news.published
location_id — Filter by location (optional, repeatable)
since — Only events after this ISO-8601 timestamp

GET/api/firehose/stream

Server-Sent Events (SSE) stream. Opens a persistent connection and pushes events in real time with heartbeats.

cursor — Resume from this event ID (optional)
event_type — Filter by event type(s) (optional, repeatable)
location_id — Filter by location(s) (optional, repeatable)

GET/api/firehose/sample

Sanitized sample frame for sister-company integration testing. Contains schema-valid synthetic payloads only.

Event Types

metric.updatedQueue count, wait/dwell times, density updated for a location

vessel.observedVessel count summary for a location (total, queued, transiting)

weather.updatedWeather conditions updated for a location

disruption.createdNew disruption alert triggered (anomaly spike, weather, queue surge)

disruption.resolvedExisting disruption auto-resolved

news.publishedMaritime disruption news article ingested

Authentication

All API requests require authentication. Use either an API key or a Clerk JWT bearer token.

API Key

Pass your key in the X-API-Key header:

X-API-Key: ss_live_your_api_key_here

Bearer Token (Clerk JWT)

Authorization: Bearer eyJhbGciOi...

Rate Limits

Authenticated

200 requests / minute

Anonymous

30 requests / minute

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) are included in every response.

Plan Limits

Plan	API Calls / mo	Locations	Webhooks	Firehose
Starter	10,000	5	2	—
Pro	100,000	20	10	—
Team	500,000	50	50	—
Enterprise	5,000,000	100	100	✓

Portfolio Alignment

For the standalone-plus-unified operating contract, see the portfolio docs page.

Open portfolio docs