API Overview
The Farsight feed adapter HTTP and gRPC surface at a glance — with pointers to feature pages.
The adapter exposes one HTTP API on :8080 (:18181 for the local launchd
agent, farsight.r2d2.office.ilab.zone for the production deployment) and a
parallel gRPC service on :50051. The OpenAPI 3.1 contract is at
/openapi.yaml / /openapi.json, and a
ready-to-browse Scalar reference lives at /reference.
Where to look
| If you want… | Read |
|---|---|
| The full route catalog with parameter & response schemas | /reference (Scalar over openapi.yaml). |
| What each layer is and where it comes from | Feed Reference. |
| The TrailBase localizer & layer counts | TrailBase Cache. |
| Operator AOIs, sub-feeds, sources | Operator Control Plane. |
| Alerts query + facet API | Alerts API. |
| Spacecraft catalog + propagation | Satellites. |
| Per-vessel enrichment + bad-actor watchlist | Vessels. |
| Learned aircraft corridors + predicted tracks + fusion | Analysis. |
| Vector tiles, live streaming, history/replay (planned) | Tiles & Streaming. |
| The Rust→Rust gRPC IPC surface | gRPC Service. |
| The SSRF-guarded camera-stream proxy | Webcam Proxy. |
Surface summary
| Group | Routes | Live today? |
|---|---|---|
| Health / docs / OpenAPI / Scalar | ~10 | yes |
| Catalog, layers, datasets, feeds, upstreams | ~10 | yes |
| Operator control plane (AOIs, sub-feeds, sources, regions) | 13 | yes |
| Alerts (query + facets) | 2 | yes |
| Satellites (search, positions, stats, detail, track, passes) | 6 | yes |
| Vessels (enrichment + watchlist) | 3 | yes |
| Analysis (corridors, predicted, fusion) | 3 | yes |
| Webcam proxy | 1 | yes |
| Farsight SPA + assets | ~7 | yes (gated on JOSHUA_ENABLED) |
| Vector tiles, SSE/WS streaming, history/replay | 6 | planned — 404 today |
| Custom feeds + MQTT admin + catalog marketplace | 15+ | planned — 404 today |
| gRPC RPCs | 10 | yes (9 unary + StreamLayer) |
Planned endpoints carry a 🚧 banner in the Scalar reference so consumers don't mistake them for live.
Export formats
GET /layers/{key}?format=… supports:
| Format | Media type | Notes |
|---|---|---|
geojson (default) | application/geo+json | |
json | application/json | |
kml | application/vnd.google-earth.kml+xml | |
kmz | application/vnd.google-earth.kmz | Zipped KML. |
topojson | application/json | |
shp | application/zip | Shapefile bundle. |
fgb | application/flatgeobuf | FlatGeobuf, R-tree-indexed binary. |
oth | text/plain | OTherGold record list. |
mvt | application/vnd.mapbox-vector-tile | Planned — see Tiles & Streaming. |
Documentation boundary
This site documents the adapter's external contracts. Internal Rust crate
layout, build steps, and operator runbooks live in the repo README.md and
CLAUDE.md. The OpenAPI document is the single source of truth for request
and response shapes — anything ambiguous on a feature page is settled there.