openapi: 3.2.0
info:
title: PlantPredict Weather API
version: 12.13.0
description: "## What is PlantPredict?\n\nPlantPredict is an industry-leading performance modeling platform for utility-scale\nsolar power plants. It predicts energy yield across the full project lifecycle —\nfrom early-stage site prospecting through detailed engineering and operational\nmonitoring. The same engine that powers the PlantPredict web UI is fully exposed\nvia this REST API, enabling automation of complex, high-time-resolution energy\npredictions without any UI interaction.\n\n## Domain Model — read this first\n\nUnderstanding the object hierarchy is essential before calling the API:\n\n- **Weather** — A weather file (hourly irradiance, temperature, wind, etc.) for a\n geographic location. Imported from a provider (e.g. SolarAnywhere, Meteonorm) or\n uploaded manually. Weather files live in a company-wide library and are referenced\n by Predictions.\n\n- **Module** — A PV module definition parameterized with electrical characteristics\n (STC power, temperature coefficients, single-diode model parameters, IAM curves,\n etc.). Modules live in a company-wide library.\n\n- **Inverter** — An inverter definition with efficiency curves, voltage/power ratings,\n and optional kVA derating curves. Inverters live in a company-wide library.\n\n- **Project** — A named location (lat/lon) that acts as a container for one or more\n Predictions. Holds geographic metadata (country, elevation, UTC offset) and a status.\n\n- **Prediction** — The core simulation configuration nested under a Project. Defines\n the simulation period, model selections (transposition, air mass, degradation,\n soiling, shading, spectral shift models), uncertainty error terms, and references\n to a Weather file. A Prediction must be linked to a PowerPlant before it can be run.\n Status values: 0 = Draft, 1 = Active, 2 = Issued, 3 = Archived.\n\n- **PowerPlant** — The physical plant design attached to a Prediction. Describes the\n electrical topology: Blocks → Arrays → Inverters → DC Fields (strings of modules).\n Also includes transformers, transmission lines, energy storage (ESS), availability\n losses, and LGIA export limits.\n\n- **Shade Scene** — An optional 3D shading model (PVJ format) attached to a\n Prediction's DC Fields. Supports import from PVC or SHD files. Shade and TABT\n (Tracker Angle Back-Tracking) calculations are queued and run asynchronously.\n\n## Typical workflow to run a prediction\n\n1. Ensure a **Weather** file exists (search, download, or import one).\n2. Ensure a **Module** and **Inverter** exist in the library.\n3. **POST /Project** — create a project at the site location.\n4. **POST /Project/{projectId}/Prediction** — create a prediction with model settings.\n5. **POST /Project/{projectId}/Prediction/{predictionId}/PowerPlant** — attach a plant\n design referencing your module and inverter.\n6. **POST /Project/{projectId}/Prediction/{predictionId}/Run** — queue the simulation.\n7. Poll **GET /Project/{projectId}/Prediction/{predictionId}/Overview** until\n `status` reaches 2 (complete), then retrieve results via `/ResultSummary`,\n `/ResultDetails`, or `/NodalJson`.\n\n## Authentication\n\nOAuth 2.0 **Client Credentials** flow via AWS Cognito. The spec advertises\na single `bearerAuth` scheme — fetch a token yourself with the snippet\nbelow, then either paste it into the in-browser playground or pass it on\nevery request as `Authorization: Bearer <token>`.\n\n> **Why not advertise OAuth2 directly?** Most users have access to the\n> production tenant only, and we don't want to invite anyone to enter\n> long-lived `client_id` / `client_secret` credentials into a third-party\n> documentation site. Keep credentials in your own environment; ship\n> short-lived bearer tokens to wherever they are needed.\n\n- Token URL: `https://terabase-prd.auth.us-west-2.amazoncognito.com/oauth2/token`\n- Scopes: `transactions/get` (read), `transactions/post` (write) — request\n both to access the entire surface.\n- Send credentials as **Basic Auth** in the token request header.\n\nExample:\n\n```bash\ncurl -X POST 'https://terabase-prd.auth.us-west-2.amazoncognito.com/oauth2/token' \\\n -u \"$PP_CLIENT_ID:$PP_CLIENT_SECRET\" \\\n -d 'grant_type=client_credentials&scope=transactions/get transactions/post'\n```\n\nAPI credentials (Client ID + Secret) are generated per user by a company admin\ninside the PlantPredict UI (gear icon → user profile → Generate API Credentials).\nStore them securely — they are shown only once.\n\n## Notes\n\n- All request/response bodies are JSON (`Content-Type: application/json`).\n- The API is stateless — every request must supply complete inputs; there is no session.\n- POST operations that create entities return `{\"id\": <integer>}`.\n- Many integer fields (model types, status codes) map to named enums — use\n `GET /Definitions` to retrieve the full enum catalog at runtime.\n- Long-running operations (Run, Shade calculations, TABT) are asynchronous; poll\n the corresponding `ProcessingStatus` endpoint to track progress.\n- Responses may include an `X-Message` header with non-blocking warnings (e.g.\n duplicate project name).\n"
servers:
- url: https://api.plantpredict.terabase.energy
description: Production
security:
- bearerAuth: []
tags:
- name: Weather
description: Weather file import, download, and management
paths:
/Weather:
post:
tags:
- Weather
summary: Create a weather file
description: Creates a new weather file in the company library from a payload of hourly meteorological records (irradiance, temperature, wind, etc.). For provider-sourced data, use `POST /Weather/Download/{providerId}` instead so metadata and downloads are handled automatically.
operationId: createWeather
x-doc-source: drafted
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WeatherFile'
examples:
postman-weather-create:
value:
status: 1
distance: 0
locality: Oxford
stateProvince: Nebraska
stateProvinceCode: NE
country: United States
countryCode: US
region: North America
source: LocalWeatherFile.xlsx
stationName: ''
format: 3
stationCode: null
latitude: 40.1932678
longitude: -99.7152252
elevation: 665
timeZone: -6
timestampDefinition: 0
timestampDefinitionOriginal: 0
timeInterval: 60
startDate: '2005-01-01T00:00:00'
endDate: '2005-01-01T23:00:00'
globalHorizontalIrradianceSum: 0.6
diffuseHorizontalIrradianceSum: 0.6
directNormalIrradianceSum: 0
planeOfArrayIrradianceSum: null
averageAirTemperature: 6.55
maxAirTemperature: 8.25
averageRelativeHumidity: 79.56
averageWindSpeed: 3.25
averagePrecipitableWater: null
averageDewpoint: null
averageSoilingLoss: null
rainfallSum: 4.57
weatherDataModelVersion: 8.1.2.15989
dataProvider: 4
pLevel: 0
windSensorHeight: 10
weatherDetails:
- id: 0
weatherId: 68915
index: 1
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 930.32
temperature: 6.07
relativeHumidity: 87.76
windspeed: 3
windDirection: 173.1
timeStamp: '2005-01-01T00:00:00'
adjustedTimeStamp: '2005-01-01T00:30:00'
precipitableWater: null
rainfall: 2.23
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 2
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 930.32
temperature: 6.27
relativeHumidity: 79.89
windspeed: 2.5
windDirection: 206.5
timeStamp: '2005-01-01T01:00:00'
adjustedTimeStamp: '2005-01-01T01:30:00'
precipitableWater: null
rainfall: 0.1
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 3
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 930.32
temperature: 6.01
relativeHumidity: 82.03
windspeed: 2
windDirection: 204.1
timeStamp: '2005-01-01T02:00:00'
adjustedTimeStamp: '2005-01-01T02:30:00'
precipitableWater: null
rainfall: 0.15
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 4
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 930.32
temperature: 5.93
relativeHumidity: 79.61
windspeed: 2.5
windDirection: 264.5
timeStamp: '2005-01-01T03:00:00'
adjustedTimeStamp: '2005-01-01T03:30:00'
precipitableWater: null
rainfall: 0.03
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 5
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 930.32
temperature: 5.81
relativeHumidity: 77.89
windspeed: 2.3
windDirection: 218.4
timeStamp: '2005-01-01T04:00:00'
adjustedTimeStamp: '2005-01-01T04:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 6
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 930.32
temperature: 5.7
relativeHumidity: 76.96
windspeed: 2.6
windDirection: 207.4
timeStamp: '2005-01-01T05:00:00'
adjustedTimeStamp: '2005-01-01T05:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 7
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 930.32
temperature: 5.62
relativeHumidity: 80.45
windspeed: 2.2
windDirection: 231
timeStamp: '2005-01-01T06:00:00'
adjustedTimeStamp: '2005-01-01T06:30:00'
precipitableWater: null
rainfall: 0.01
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 8
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 930.32
temperature: 5.54
relativeHumidity: 80.71
windspeed: 3
windDirection: 191.6
timeStamp: '2005-01-01T07:00:00'
adjustedTimeStamp: '2005-01-01T07:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 9
dewpoint: null
diffuseHorizontalIrradiance: 6.1
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 6.1
pressure: 930.32
temperature: 5.76
relativeHumidity: 80.31
windspeed: 2.6
windDirection: 168.9
timeStamp: '2005-01-01T08:00:00'
adjustedTimeStamp: '2005-01-01T08:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 30.0402528947981
- id: 0
weatherId: 68915
index: 10
dewpoint: null
diffuseHorizontalIrradiance: 50.08
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 50.08
pressure: 930.32
temperature: 6.57
relativeHumidity: 83.12
windspeed: 4.1
windDirection: 252.7
timeStamp: '2005-01-01T09:00:00'
adjustedTimeStamp: '2005-01-01T09:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 185.49330738635734
- id: 0
weatherId: 68915
index: 11
dewpoint: null
diffuseHorizontalIrradiance: 88.92
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 88.92
pressure: 930.32
temperature: 7.31
relativeHumidity: 76.96
windspeed: 3.7
windDirection: 50.4
timeStamp: '2005-01-01T10:00:00'
adjustedTimeStamp: '2005-01-01T10:30:00'
precipitableWater: null
rainfall: 0.02
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 320.34875208133815
- id: 0
weatherId: 68915
index: 12
dewpoint: null
diffuseHorizontalIrradiance: 103.67
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 103.67
pressure: 930.32
temperature: 7.82
relativeHumidity: 74.6
windspeed: 3.5
windDirection: 181.3
timeStamp: '2005-01-01T11:00:00'
adjustedTimeStamp: '2005-01-01T11:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 412.4474580667211
- id: 0
weatherId: 68915
index: 13
dewpoint: null
diffuseHorizontalIrradiance: 99.12
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 99.12
pressure: 930.32
temperature: 8.08
relativeHumidity: 71.52
windspeed: 3.9
windDirection: 189.9
timeStamp: '2005-01-01T12:00:00'
adjustedTimeStamp: '2005-01-01T12:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 452.27318005064905
- id: 0
weatherId: 68915
index: 14
dewpoint: null
diffuseHorizontalIrradiance: 92.96
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 92.96
pressure: 930.45
temperature: 8.23
relativeHumidity: 72.61
windspeed: 4.4
windDirection: 57.8
timeStamp: '2005-01-01T13:00:00'
adjustedTimeStamp: '2005-01-01T13:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 436.06204606577194
- id: 0
weatherId: 68915
index: 15
dewpoint: null
diffuseHorizontalIrradiance: 79.1
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 79.1
pressure: 930.58
temperature: 8.25
relativeHumidity: 67.18
windspeed: 3.7
windDirection: 55.1
timeStamp: '2005-01-01T14:00:00'
adjustedTimeStamp: '2005-01-01T14:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 365.3295473095477
- id: 0
weatherId: 68915
index: 16
dewpoint: null
diffuseHorizontalIrradiance: 52.79
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 52.79
pressure: 930.7
temperature: 8.09
relativeHumidity: 66.09
windspeed: 5.1
windDirection: 175.9
timeStamp: '2005-01-01T15:00:00'
adjustedTimeStamp: '2005-01-01T15:30:00'
precipitableWater: null
rainfall: 0.06
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 247.01201691729582
- id: 0
weatherId: 68915
index: 17
dewpoint: null
diffuseHorizontalIrradiance: 22.03
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 22.03
pressure: 930.83
temperature: 7.7
relativeHumidity: 81.96
windspeed: 3.9
windDirection: 36
timeStamp: '2005-01-01T16:00:00'
adjustedTimeStamp: '2005-01-01T16:30:00'
precipitableWater: null
rainfall: 0.23
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 95.29513760680047
- id: 0
weatherId: 68915
index: 18
dewpoint: null
diffuseHorizontalIrradiance: 0.59
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0.59
pressure: 930.96
temperature: 7.23
relativeHumidity: 81.98
windspeed: 4.4
windDirection: 155.2
timeStamp: '2005-01-01T17:00:00'
adjustedTimeStamp: '2005-01-01T17:30:00'
precipitableWater: null
rainfall: 0.52
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 19
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 931.09
temperature: 6.75
relativeHumidity: 82
windspeed: 3.7
windDirection: 52.1
timeStamp: '2005-01-01T18:00:00'
adjustedTimeStamp: '2005-01-01T18:30:00'
precipitableWater: null
rainfall: 0.88
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 20
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 931.22
temperature: 6.45
relativeHumidity: 82.01
windspeed: 3.7
windDirection: 190.7
timeStamp: '2005-01-01T19:00:00'
adjustedTimeStamp: '2005-01-01T19:30:00'
precipitableWater: null
rainfall: 0.34
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 21
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 931.34
temperature: 6.09
relativeHumidity: 85.91
windspeed: 3.7
windDirection: 203.5
timeStamp: '2005-01-01T20:00:00'
adjustedTimeStamp: '2005-01-01T20:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 22
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 931.47
temperature: 5.69
relativeHumidity: 85.92
windspeed: 2.9
windDirection: 164.6
timeStamp: '2005-01-01T21:00:00'
adjustedTimeStamp: '2005-01-01T21:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 23
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 931.6
temperature: 5.29
relativeHumidity: 85.94
windspeed: 2.3
windDirection: 220.2
timeStamp: '2005-01-01T22:00:00'
adjustedTimeStamp: '2005-01-01T22:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
- id: 0
weatherId: 68915
index: 24
dewpoint: null
diffuseHorizontalIrradiance: 0
directNormalIrradiance: 0
planeOfArrayIrradiance: null
globalHorizontalIrradiance: 0
pressure: 931.73
temperature: 4.88
relativeHumidity: 85.95
windspeed: 2.2
windDirection: 170.6
timeStamp: '2005-01-01T23:00:00'
adjustedTimeStamp: '2005-01-01T23:30:00'
precipitableWater: null
rainfall: 0
albedo: 0
soilingLoss: null
beamHorizontalIrradiance: 0
clearSkyIrradiance: 0
dataType: 1
customerName: ''
apiLocked: false
apiDownloaded: false
offsetMinutes: 0
usingSytemKey: false
moduleTilt: null
moduleAzimuth: null
trackingType: null
trackingBacktrackingType: 0
minimumTrackingLimitAngleD: 0
maximumTrackingLimitAngleD: null
trackerPitchAngleD: 0
trackerStowAngle: 0
groundCoverageRatio: null
id: 68915
name: Meteonorm - 40.193N - 99.715W
description: null
responses:
'200':
description: Created weather ID
content:
application/json:
schema:
$ref: '#/components/schemas/IdResponse'
examples:
postman-create:
value:
id: 68916
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/ServerError'
/Weather/{weatherId}:
get:
tags:
- Weather
summary: Get a weather file
description: Retrieves a single weather file's metadata (provider, location, time range, status). To fetch the actual hourly records, call `GET /Weather/{weatherId}/Detail`.
operationId: getWeather
x-doc-source: drafted
parameters:
- name: weatherId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Weather file
content:
application/json:
schema:
$ref: '#/components/schemas/WeatherFile'
examples:
postman-weather:
value:
status: 1
distance: 0
locality: Oxford
stateProvince: Nebraska
stateProvinceCode: NE
country: United States
countryCode: US
region: North America
source: Book2.xlsx
stationName: ''
format: 3
stationCode: null
latitude: 40.1932678
longitude: -99.7152252
elevation: 665
timeZone: -6
timestampDefinition: 0
timestampDefinitionOriginal: 0
timeInterval: 60
startDate: '2005-01-01T00:00:00'
endDate: '2005-01-01T23:00:00'
globalHorizontalIrradianceSum: 0.6
diffuseHorizontalIrradianceSum: 0.6
directNormalIrradianceSum: 0
planeOfArrayIrradianceSum: null
averageAirTemperature: 6.55
maxAirTemperature: 8.25
averageRelativeHumidity: 79.56
averageWindSpeed: 3.25
averagePrecipitableWater: null
averageDewpoint: null
averageSoilingLoss: null
rainfallSum: 4.57
weatherDataModelVersion: 8.1.2.15989
dataProvider: 4
pLevel: 0
windSensorHeight: 10
weatherDetails: null
dataType: 1
customerName: ''
apiLocked: false
apiDownloaded: false
weatherFileKey: 00000000-0000-0000-0000-000000000000
offsetMinutes: 0
usingSytemKey: false
moduleTilt: null
moduleAzimuth: null
trackingType: null
trackingBacktrackingType: 0
# --- truncated at 32 KB (251 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/terabase-energy/refs/heads/main/openapi/terabase-energy-weather-api-openapi.yml