API reference

Every route the API serves. Generated, not written.

This reference renders from the OpenAPI document the server emits about itself, checked in and gated in CI, so it cannot describe a route the deployed API does not serve. Even the curl commands are generated, example values included. Base URL: https://api.orr.sh. Version 0.1.0. Every data endpoint works without a key (60 requests/minute per IP); create an account for an API key and plan-rate limits.

Field	Type	Description
service	string
status	string

atmosphere

International Standard Atmosphere state

get/v1/atmosphere

ISA state for a geometric altitude, computed with the standard-atmosphere crate.

curl 'https://api.orr.sh/v1/atmosphere?altitude_m=1000'

Parameter	Type	Description
altitude_m	number (double)	Geometric altitude, metres, -500 to 86000

200AtmosphereResponseISA temperature, pressure, and density at the altitude
400ProblemMissing or out-of-range altitude_m
429ProblemRate limit exceeded

Response fields · AtmosphereResponse

AtmosphereResponse

ISA state at an altitude.

Field	Type	Description
density_kg_m3	number (double)	Air density, kg/m^3.
geopotential_altitude_m	number (double)	Geopotential altitude corresponding to the geometric input, metres.
input	Input
model	string	The atmosphere model behind the numbers.
pressure	Pressure
source	string	Where the computation comes from.
temperature	Temperature

Input

Field	Type	Description
altitude_kind	string	How the altitude is measured (`geometric`).
altitude_m	number (double)	The altitude the state was computed for, metres.

Pressure

Pressure in pascals and hectopascals.

Field	Type	Description
hpa	number (double)
pa	number (double)

Temperature

Temperature in kelvin and degrees Celsius.

Field	Type	Description
c	number (double)
k	number (double)

weather

Weather intelligence (the V1 beachhead)

get/v1/weather/forecast

Hourly point forecast, one time series per requested variable.

curl 'https://api.orr.sh/v1/weather/forecast?lat=35&lon=-100&vars=temperature_2m,wind_speed_80m,ghi'

Parameter	Type	Description
lat	number (double)	Latitude, WGS84 degrees, -90 to 90
lon	number (double)	Longitude, WGS84 degrees, -180 to 180
vars	string	Comma-separated canonical variable ids. Served today: temperature_2m, wind_speed_10m, wind_direction_10m, wind_speed_80m, wind_direction_80m, ghi
model?	string	Model: auto (default) or gfs; other models return 400 until they are served with published verification
horizon_hours?	integer (int32)	Hourly points to return, starting at the current hour, 1 to 96 (default 48)

200ForecastResponseOne hourly series per requested variable from the freshest published GFS cycle covering the horizon, with model lineage
400ProblemMissing or invalid parameters, an unsupported variable, or an unserved model
429ProblemRate limit exceeded
503ProblemNo published GFS cycle covers the requested horizon

Response fields · ForecastResponse

ForecastResponse

Point forecast: one hourly time series per requested variable, with the producing model run's lineage.

Field	Type	Description
cycle	string (date-time)	Issue time of the producing model cycle.
location	LonLat
model	WeatherModel	The model that answered (`auto` resolves to the only served model today; more arrive with published verification).
series	TimeSeries[]

LonLat

A longitude/latitude point in WGS84 degrees.

Field	Type	Description
lat	number (double)	Latitude in degrees, -90..90.
lon	number (double)	Longitude in degrees, -180..180.

WeatherModel

Which model (or blend) backs a forecast.

one of: auto · nbm · hrrr · gfs · ecmwf

TimeSeries

A dense series for one variable at one place: the common API response.

Field	Type	Description
location	LonLat	Where the series applies.
points	TimeSeriesPoint[]	The ordered points.
source	string	Which connector/source produced this.
unit	string	Canonical unit string for the values in this series.
variable	VariableId	Which variable this series reports.

TimeSeriesPoint

A single point in a [`TimeSeries`].

Field	Type	Description
at	string (date-time)	When this point applies.
value	number (double)	The value, in the series' unit.

VariableId

Canonical variable identifiers, stable across all providers and domains.

one of: temperature_2m · wind_speed_10m · wind_direction_10m · wind_speed_80m · wind_direction_80m · wind_speed_100m · wind_direction_100m · precipitation · pressure_msl · ghi · load · solar_generation · wind_generation · lmp

get/v1/weather/observations

Recent station observations near a point.

curl 'https://api.orr.sh/v1/weather/observations?lat=32.9&lon=-97.04&var=temperature_2m'

Parameter	Type	Description
lat	number (double)	Latitude, WGS84 degrees, -90 to 90
lon	number (double)	Longitude, WGS84 degrees, -180 to 180
var	string	Canonical variable id. Observed: temperature_2m, wind_speed_10m, wind_direction_10m, pressure_msl, precipitation
since?	string	Return values at or after this RFC 3339 instant, at most 7 days back (default: the last 24 hours)

200ObservationsResponseObservations from the nearest reporting NWS station, oldest first, with the station named
400ProblemMissing or invalid parameters, a variable stations do not observe, or a `since` beyond the observation window
404ProblemThe point is outside the NWS observing network
429ProblemRate limit exceeded
503ProblemThe observations source is unreachable

Response fields · ObservationsResponse

ObservationsResponse

Recent observed values near a point, from the nearest reporting station.

Field	Type	Description
location	LonLat	The requested point; records carry the station's own coordinates.
observations	Observation[]	The records, oldest first.
station	ObsStation	The nearest station that reported the variable in the window - or, when none did, the nearest station asked (with `observations` empty).
unit	string	Canonical unit for every value in `observations`.
variable	VariableId

LonLat

A longitude/latitude point in WGS84 degrees.

Field	Type	Description
lat	number (double)	Latitude in degrees, -90..90.
lon	number (double)	Longitude in degrees, -180..180.

Observation

A single observed or analysed value at a place and time.

Field	Type	Description
at	string (date-time)	When the value applies.
location	LonLat	Where the value applies.
source	string	Which connector/source produced this (lineage for trust and debugging).
value	number (double)	The value, in the variable's canonical unit.
variable	VariableId	Which variable this measures.

VariableId

Canonical variable identifiers, stable across all providers and domains.

ObsStation

The station whose instruments answered an observations request.

Field	Type	Description
id	string	NWS station identifier, e.g. `KDFW`.
location	LonLat	Station coordinates, WGS84.
name	string	Human-readable site name.

get/v1/weather/wind

Wind at a height above ground, for wind-energy work.

curl 'https://api.orr.sh/v1/weather/wind?lat=35&lon=-100&height_m=120'

Parameter	Type	Description
lat	number (double)	Latitude, WGS84 degrees, -90 to 90
lon	number (double)	Longitude, WGS84 degrees, -180 to 180
height_m	number (double)	Height above ground to report wind at, metres, 10 to 300 (modern turbine hubs sit at 80-160 m)

200WindResponseWind at the requested height from the freshest published GFS cycle, with the shear derivation and model lineage
400ProblemMissing or invalid parameters
429ProblemRate limit exceeded
503ProblemNo recent GFS cycle is reachable

Response fields · WindResponse

WindResponse

Wind at the requested height at a point, with model lineage.

Field	Type	Description
location	LonLat
model	ModelRun
source	string	Data source and license; attribution travels with the data.
wind	HubHeightWind

LonLat

A longitude/latitude point in WGS84 degrees.

Field	Type	Description
lat	number (double)	Latitude in degrees, -90..90.
lon	number (double)	Longitude in degrees, -180..180.

ModelRun

The model run behind a served value. A forecast always carries both its issue time and its valid time.

Field	Type	Description
cycle	string (date-time)	When the model run was initialised (issue time).
forecast_hour	integer (int32)	Hours from issue to valid.
grid	string	Grid the values were sampled from.
name	string	Producing model.
valid_at	string (date-time)	The moment the values describe.

HubHeightWind

Wind extrapolated to a requested height above ground: the hub-height product (docs/DECISIONS.md D9).

Field	Type	Description
anchors	WindAnchor[]	The two model levels the profile was anchored on, lower first.
direction_deg?	number \| null	Meteorological wind direction (degrees the wind blows from), taken at the upper model level, the one nearest a turbine hub; direction veer above that anchor is not modeled. `None` in near-calm air.
height_m	number (double)	The requested height above ground, metres.
shear_exponent	number (double)	The power-law exponent the extrapolation used.
shear_method	ShearMethod	Where that exponent came from.
speed_m_s	number (double)	Wind speed at that height, m/s, by the power law.

WindAnchor

One model anchor level, reported back so a caller can see what the extrapolation stood on.

Field	Type	Description
height_m	number (double)	Height above ground, metres.
speed_m_s	number (double)	Wind speed at that height, m/s.

ShearMethod

How the shear exponent behind a hub-height answer was obtained.

one of: two_level · fallback_one_seventh

energy

Power-system data, keyed by ISO zone

get/v1/energy/load

System load (demand) for a zone.

curl 'https://api.orr.sh/v1/energy/load?zone=ERCOT'

Parameter	Type	Description
zone	string	Balancing authority / ISO zone, e.g. ERCOT, CAISO, MISO, PJM, SPP, NYISO, ISONE
since?	string	Return values at or after this RFC 3339 instant (default: last 24 hours)

200LoadResponseHourly system demand for the zone from the EIA grid monitor, oldest first
400ProblemMissing or invalid parameters
429ProblemRate limit exceeded
503ProblemThe EIA data source is unreachable

Response fields · LoadResponse

LoadResponse

System load for a zone.

Field	Type	Description
series?	TimeSeries \| null
zone	string	The balancing authority / ISO zone asked about.

TimeSeries

A dense series for one variable at one place: the common API response.

Field	Type	Description
location	LonLat	Where the series applies.
points	TimeSeriesPoint[]	The ordered points.
source	string	Which connector/source produced this.
unit	string	Canonical unit string for the values in this series.
variable	VariableId	Which variable this series reports.

LonLat

A longitude/latitude point in WGS84 degrees.

Field	Type	Description
lat	number (double)	Latitude in degrees, -90..90.
lon	number (double)	Longitude in degrees, -180..180.

TimeSeriesPoint

A single point in a [`TimeSeries`].

Field	Type	Description
at	string (date-time)	When this point applies.
value	number (double)	The value, in the series' unit.

VariableId

Canonical variable identifiers, stable across all providers and domains.

get/v1/energy/prices

Locational marginal prices for a zone (optionally one node/hub).

curl 'https://api.orr.sh/v1/energy/prices?zone=ERCOT'

Parameter	Type	Description
zone	string	Balancing authority / ISO zone, e.g. ERCOT, CAISO, MISO, PJM
node?	string	Node or hub within the zone
since?	string	Return values at or after this RFC 3339 instant (default: last 24 hours)

200PricesResponseLMP series for the zone and node, null when the zone has no price source yet
400ProblemMissing or invalid parameters
429ProblemRate limit exceeded
503ProblemThe price data source is unreachable

Response fields · PricesResponse

PricesResponse

Locational marginal prices for a zone.

Field	Type	Description
node?	string \| null	The specific node or hub, when one was requested.
series?	TimeSeries \| null
zone	string	The balancing authority / ISO zone asked about.

TimeSeries

A dense series for one variable at one place: the common API response.

Field	Type	Description
location	LonLat	Where the series applies.
points	TimeSeriesPoint[]	The ordered points.
source	string	Which connector/source produced this.
unit	string	Canonical unit string for the values in this series.
variable	VariableId	Which variable this series reports.

LonLat

A longitude/latitude point in WGS84 degrees.

Field	Type	Description
lat	number (double)	Latitude in degrees, -90..90.
lon	number (double)	Longitude in degrees, -180..180.

TimeSeriesPoint

A single point in a [`TimeSeries`].

Field	Type	Description
at	string (date-time)	When this point applies.
value	number (double)	The value, in the series' unit.

VariableId

Canonical variable identifiers, stable across all providers and domains.

account

Self-serve accounts and API keys. Data endpoints work without a key at 60 requests/minute per IP; a free key raises that to 300.

post/v1/accounts

Create an account and its first API key.

curl -X POST 'https://api.orr.sh/v1/accounts' \
  -H 'content-type: application/json' \
  -d '{"email":"trader@example.com","password":"correct-horse-battery"}'

201AccountCreatedAccount created; the key secret is shown only here
400ProblemInvalid email or password shape
409ProblemAn account with this email already exists
429ProblemRate limit exceeded

Response fields · AccountCreated

AccountCreated

A new account with its first API key.

Field	Type	Description
account_id	string
api_key	IssuedKey	The first API key. The secret is shown exactly once.
email	string
plan	PlanId	Plan the account starts on (free; upgrade paths come with the console).

IssuedKey

A freshly minted API key. The secret appears here and never again; store it now.

Field	Type	Description
key_id	string	The key id, safe to log and show; use it to revoke the key.
secret	string	The key secret (`orrery_sk_...`), shown exactly once. Send it as `Authorization: Bearer <secret>`.

PlanId

The published plan tiers.

one of: free · build · pro · scale

post/v1/auth/login

Verify credentials and see the account and its keys.

curl -X POST 'https://api.orr.sh/v1/auth/login' \
  -H 'content-type: application/json' \
  -d '{"email":"trader@example.com","password":"correct-horse-battery"}'

200AccountViewCredentials verified; the account and its key metadata
401ProblemEmail or password is incorrect
429ProblemRate limit exceeded

Response fields · AccountView

AccountView

The account behind a successful login.

Field	Type	Description
account_id	string
email	string
keys	KeySummary[]	Metadata for every live key on the account.
plan	PlanId

KeySummary

One key's metadata (never the secret).

Field	Type	Description
created_at	string	When the key was minted, RFC 3339 UTC.
key_id	string

PlanId

The published plan tiers.

one of: free · build · pro · scale

post/v1/keys

Mint an additional API key.

curl -X POST 'https://api.orr.sh/v1/keys' \
  -H 'content-type: application/json' \
  -d '{"email":"trader@example.com","password":"correct-horse-battery"}'

201IssuedKeyKey minted; the secret is shown only here
401ProblemEmail or password is incorrect
429ProblemRate limit exceeded

Response fields · IssuedKey

IssuedKey

A freshly minted API key. The secret appears here and never again; store it now.

Field	Type	Description
key_id	string	The key id, safe to log and show; use it to revoke the key.
secret	string	The key secret (`orrery_sk_...`), shown exactly once. Send it as `Authorization: Bearer <secret>`.

post/v1/keys/revoke

Revoke an API key by id.

curl -X POST 'https://api.orr.sh/v1/keys/revoke' \
  -H 'content-type: application/json' \
  -d '{"email":"trader@example.com","key_id":"ok_1a2b3c4d5e6f","password":"correct-horse-battery"}'

200RevokedKey revoked
401ProblemEmail or password is incorrect
404ProblemNo such key on this account
429ProblemRate limit exceeded

Response fields · Revoked

Revoked

Revocation outcome.

Field	Type	Description
key_id	string
revoked	boolean

get/v1/me

The identity behind the presented API key.

curl 'https://api.orr.sh/v1/me' \
  -H "Authorization: Bearer $ORRERY_API_KEY"

200MeThe account, plan, and limits behind the key
401ProblemMissing, unknown, or revoked API key
429ProblemRate limit exceeded

Response fields · Me

Me

The identity and limits behind the presented API key.

Field	Type	Description
account_id	string
email	string
included_requests_per_month	integer (int64)	Requests included per month before overage, per the published plans.
key_id	string	The key that authenticated this request.
plan	PlanId
requests_per_minute	integer (int32)	Requests per minute this key may make (the plan's pooled rate).
usage?	Usage \| null

PlanId

The published plan tiers.

one of: free · build · pro · scale

Usage

This calendar month's usage against the plan's allowance.

Field	Type	Description
cheaper_plan?	PlanId \| null
included	integer (int64)	Requests included this month before overage.
overage_usd	number (double)	Overage accrued so far, in USD. Zero at or under the allowance, and always zero on the free plan, which stops rather than billing.
resets_at	string	When the counter resets, RFC 3339 UTC (the first of the next month).
spend_cap_usd?	number \| null	The effective spend cap in USD. `null` on the free plan (it hard-stops at the allowance). For paid plans, the customer-set value if any, otherwise the plan default (2x monthly price).
used	integer (int64)	Requests counted this month. Account routes, the plan catalog, and `/health` are not counted.

get/v1/plans

The published plans and their prices.

curl 'https://api.orr.sh/v1/plans'

200PlanCatalogThe published plan catalog and its upgrade crossovers
429ProblemRate limit exceeded

Response fields · PlanCatalog

PlanCatalog

The catalog: every tier, plus the volumes at which moving up costs less than staying put.

Field	Type	Description
plans	PublishedPlan[]	Every published tier, cheapest first.
upgrade_at	Crossover[]	Where the ladder's rungs meet. At and above `monthly_requests`, `to` is the cheaper plan - we publish this rather than let a customer overpay in overage without noticing.

PublishedPlan

One published tier, exactly as the gateway enforces it.

Field	Type	Description
included_requests_per_month	integer (int64)	Requests included each calendar month before overage.
month_to_month	boolean	No minimum term and no auto-renew trap. Always true.
monthly_price_usd	number (double)	Flat monthly price in USD. Month-to-month; cancel any time.
overage_per_1k_usd?	number \| null	USD per 1,000 requests past the included volume. `null` means the plan does not serve past its allowance at any price - it stops (HTTP 402) rather than billing, which is true of the free plan only.
plan	PlanId	The plan identifier, as it appears on `GET /v1/me`.
requests_per_minute	integer (int32)	Requests per minute this plan may make (the pooled steady-state rate).

PlanId

The published plan tiers.

one of: free · build · pro · scale

Crossover

Where two adjacent rungs meet: the monthly volume at which the lower plan plus its overage costs exactly what the higher plan costs flat.

Field	Type	Description
from	PlanId	The plan being outgrown.
monthly_requests	integer (int64)	The monthly request volume where the two cost the same.
to	PlanId	The plan that becomes the cheaper answer at (and above) this volume.

get/v1/confirm

Finish a double opt-in: match the token, flip to confirmed, render the page.

curl 'https://api.orr.sh/v1/confirm?e=you@example.com&t=one-time-token-from-the-email'

Parameter	Type	Description
e	string	Subscriber email address
t	string	One-time confirmation token from the email

200Confirmed onto the list; a branded HTML page
400Missing, malformed, or stale link; a branded HTML page
500Backend failure; a branded HTML page

post/v1/subscribe

Capture a signup: validate, store the row, best-effort send the confirm email.

curl -X POST 'https://api.orr.sh/v1/subscribe' \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com"}'

202SubscribeStatusAccepted. If the address is not already confirmed, a double opt-in email is on its way. Identical whether the address is new or already on the list, by design.
400ProblemNot a valid email address
500ProblemThe subscription store is unavailable

Response fields · SubscribeStatus

SubscribeStatus

Subscribe outcome. Deliberately uniform for every case (new address, repeat of a pending one, already confirmed) so the response cannot be used to probe which addresses are already on the list.

Field	Type	Description
status	string	Always `ok`: the signup was accepted.

billing

Subscriptions. Paddle is the merchant of record; Orrery's own meter stays the source of truth for usage.

post/v1/billing/checkout

Start a subscription.

curl -X POST 'https://api.orr.sh/v1/billing/checkout' \
  -H "Authorization: Bearer $ORRERY_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"plan":"build"}'

201CheckoutCreatedCheckout created; open it to pay
400ProblemThat plan cannot be purchased
401ProblemMissing, unknown, or revoked API key
503ProblemBilling is not configured on this deployment

Response fields · CheckoutCreated

CheckoutCreated

A checkout ready to be opened.

Field	Type	Description
checkout_url?	string \| null	A hosted checkout page for this transaction, when the vendor returned one. `null` means use the transaction id with Paddle.js instead.
plan	PlanId	The plan this checkout would put the account on.
transaction_id	string	The Paddle transaction id. Pass it to Paddle.js as `_ptxn` to open the overlay checkout in place.

PlanId

The published plan tiers.

one of: free · build · pro · scale

Every route the API serves. Generated, not written.

get/health

Health

get/v1/atmosphere

AtmosphereResponse

Input

Pressure

Temperature

get/v1/weather/forecast

ForecastResponse

LonLat

WeatherModel

TimeSeries

TimeSeriesPoint

VariableId

get/v1/weather/observations

ObservationsResponse

LonLat

Observation

VariableId

ObsStation

get/v1/weather/wind

WindResponse

LonLat

ModelRun

HubHeightWind

WindAnchor

ShearMethod

get/v1/energy/load

LoadResponse

TimeSeries

LonLat

TimeSeriesPoint

VariableId

get/v1/energy/prices

PricesResponse

TimeSeries

LonLat

TimeSeriesPoint

VariableId

post/v1/accounts

AccountCreated

IssuedKey

PlanId

post/v1/auth/login

AccountView

KeySummary

PlanId

post/v1/keys

IssuedKey

post/v1/keys/revoke

Revoked

get/v1/me

Me

PlanId

Usage

get/v1/plans

PlanCatalog

PublishedPlan

PlanId

Crossover

get/v1/confirm

post/v1/subscribe

SubscribeStatus

post/v1/billing/checkout

CheckoutCreated

PlanId