openapi: 3.2.0
info:
title: PlantPredict Predictions 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: Predictions
description: Energy prediction configuration and execution
paths:
/Project/{projectId}/Prediction:
get:
tags:
- Predictions
summary: List predictions for a project
description: 'Returns all predictions for a project. Predictions do not include power plant data; use the Power Plant operation for sub-entities.
**Parameters:**
- `projectId` (path, required): The project ID.
'
operationId: listPredictions
x-doc-source: postman
parameters:
- name: projectId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Array of predictions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Prediction'
examples:
postman-predictions:
value:
- status: 2
start: '2005-01-01T00:00:00'
end: '2005-12-31T23:00:00'
startIndex: 0
endIndex: 0
yearRepeater: 1
transpositionModel: 1
perezCoefficients: 0
diffuseDirectDecompModel: 3
circumsolarTreatment: 0
diffuseDirectDecompModelExecuted: false
useMeteoDni: false
useMeteoPOAI: false
useBacksidePOAI: false
useLeapYears: false
useWeatherFileAlbedoData: false
useMetastability: false
enableLeTID: false
airMassModel: 0
soilingModel: 0
modTempModel: 0
incAngleModel: 5
directBeamShadingModel: 5
degradationModel: 0
diffuseShadingModel: 1
linearDegradationRate: 0.5
firstYearDegradation: false
nonLinearDegradationRates: []
lightAndElevatedTemperatureDegradationRates: []
errorModelAcc: 2.9
errorSensAcc: 5
errorIntAnnVar: 3
errorMonAcc: 2
errorSpaVar: 2
spectralShiftModel: 2
spectralWeatherType: 0
powerPlantId: 1185523
monthlyFactors:
- month: 1
monthName: Jan
soilingLoss: 2
albedo: 0.2
- month: 2
monthName: Feb
soilingLoss: 2
albedo: 0.2
- month: 3
monthName: Mar
soilingLoss: 2
albedo: 0.2
- month: 4
monthName: Apr
soilingLoss: 2
albedo: 0.2
- month: 5
monthName: May
soilingLoss: 2
albedo: 0.2
- month: 6
monthName: Jun
soilingLoss: 2
albedo: 0.2
- month: 7
monthName: Jul
soilingLoss: 2
albedo: 0.2
- month: 8
monthName: Aug
soilingLoss: 2
albedo: 0.2
- month: 9
monthName: Sep
soilingLoss: 2
albedo: 0.2
- month: 10
monthName: Oct
soilingLoss: 2
albedo: 0.2
- month: 11
monthName: Nov
soilingLoss: 2
albedo: 0.2
- month: 12
monthName: Dec
soilingLoss: 2
albedo: 0.2
horizonDetails: []
ashraeStation: RIVERPORT MUNICIPAL AP, ST, USA
ashraeVersion: 2021
cool996: 32.5
max50Year: 39.4
min50Year: -30.3
minAnnualMeanDBTemp: -19.1
elevation: 184
timeZone: -5
weatherId: 230763
projectId: 187749
shadeScenePropertiesId: 4297
shadeEngineRunInfo_Id: 6806
shading3DModel: 0
tabtEngineRunInfo_Id: 802
percentComplete: 0
processingStatus: 0
processingStep: 0
processingMessage: Unknown
pValues: []
isReadOnly: false
pValuesString: ''
nodalData: false
hasTimeSeriesData: false
isBatch: false
batchStepVariable: []
batchQualified: true
logicVersion: 12
mapBuilderCreateDCAs: 0
useMapBuilder: false
scenePropertiesKey: 00000000-0000-0000-0000-000000000000
setback: 0
targetDC: 0
weatherLocked: false
electricalShadingFractionalEffect: 100
numberOfModuleFractions: 0
numOfBlocks: 0
numOfWeatherDetails: 0
hasObjectShading: false
numOfShadingObjects: 0
reportsId: 941620
canImportAlbedoData: false
useSpectral30: false
spectral30B0: -0.0967
spectral30B1: 0.0126
spectral30B2: 0
spectral30B3: 0.00223
spectral30B4: 0
spectral30B5: 0
spectral30B6: 1.086
id: 955415
name: Baseline Yield Study
companyId: 1042
ownerId: 8903
createdDate: '2025-11-25T16:21:07.213'
lastModified: '2025-11-25T16:22:16.553'
lastModifiedById: 8903
- status: 2
start: '2005-01-01T00:00:00'
end: '2005-12-31T23:00:00'
lastPublishedDateToQueue: '2026-02-06T13:01:30.893'
startIndex: 0
endIndex: 0
yearRepeater: 1
transpositionModel: 1
perezCoefficients: 0
diffuseDirectDecompModel: 3
circumsolarTreatment: 0
diffuseDirectDecompModelExecuted: false
useMeteoDni: false
useMeteoPOAI: false
useBacksidePOAI: false
useLeapYears: false
useWeatherFileAlbedoData: false
useMetastability: false
enableLeTID: false
airMassModel: 0
soilingModel: 0
modTempModel: 0
incAngleModel: 5
directBeamShadingModel: 5
degradationModel: 0
diffuseShadingModel: 1
linearDegradationRate: 0.5
firstYearDegradation: false
nonLinearDegradationRates: []
lightAndElevatedTemperatureDegradationRates: []
errorModelAcc: 2.9
errorSensAcc: 5
errorIntAnnVar: 3
errorMonAcc: 2
errorSpaVar: 2
spectralShiftModel: 2
spectralWeatherType: 0
powerPlantId: 1187255
monthlyFactors:
- month: 1
monthName: Jan
soilingLoss: 2
albedo: 0.2
- month: 2
monthName: Feb
soilingLoss: 2
albedo: 0.2
- month: 3
monthName: Mar
soilingLoss: 2
albedo: 0.2
- month: 4
monthName: Apr
soilingLoss: 2
albedo: 0.2
- month: 5
monthName: May
soilingLoss: 2
albedo: 0.2
- month: 6
monthName: Jun
soilingLoss: 2
albedo: 0.2
- month: 7
monthName: Jul
soilingLoss: 2
albedo: 0.2
- month: 8
monthName: Aug
soilingLoss: 2
albedo: 0.2
- month: 9
monthName: Sep
soilingLoss: 2
albedo: 0.2
- month: 10
monthName: Oct
soilingLoss: 2
albedo: 0.2
- month: 11
monthName: Nov
soilingLoss: 2
albedo: 0.2
- month: 12
monthName: Dec
soilingLoss: 2
albedo: 0.2
horizonDetails:
- azimuth: 0
elevation: 2.3
- azimuth: 7.5
elevation: 2.3
- azimuth: 15
elevation: 2.3
- azimuth: 22.5
elevation: 2.3
- azimuth: 30
elevation: 2.3
- azimuth: 37.5
elevation: 2.3
- azimuth: 45
elevation: 1.5
- azimuth: 52.5
elevation: 1.5
- azimuth: 60
elevation: 1.5
- azimuth: 67.5
elevation: 1.5
- azimuth: 75
elevation: 1.9
- azimuth: 82.5
elevation: 1.9
- azimuth: 90
elevation: 1.9
- azimuth: 97.5
elevation: 2.3
- azimuth: 105
elevation: 2.3
- azimuth: 112.5
elevation: 1.9
- azimuth: 120
elevation: 1.9
- azimuth: 127.5
elevation: 1.9
- azimuth: 135
elevation: 1.9
- azimuth: 142.5
elevation: 1.1
- azimuth: 150
elevation: 0.8
- azimuth: 157.5
elevation: 0.4
- azimuth: 165
elevation: 0.4
- azimuth: 172.5
elevation: 0
- azimuth: 180
elevation: 0
- azimuth: 187.5
elevation: 0.4
- azimuth: 195
elevation: 0.4
- azimuth: 202.5
elevation: 0.8
- azimuth: 210
elevation: 0.4
- azimuth: 217.5
elevation: 0
- azimuth: 225
elevation: 0
- azimuth: 232.5
elevation: 0
- azimuth: 240
elevation: 0
- azimuth: 247.5
elevation: 0
- azimuth: 255
elevation: 0
- azimuth: 262.5
elevation: 0
- azimuth: 270
elevation: 0.8
- azimuth: 277.5
elevation: 1.1
- azimuth: 285
elevation: 0.8
- azimuth: 292.5
elevation: 0.8
- azimuth: 300
elevation: 0.4
- azimuth: 307.5
elevation: 1.1
- azimuth: 315
elevation: 1.1
- azimuth: 322.5
elevation: 2.3
- azimuth: 330
elevation: 2.3
- azimuth: 337.5
elevation: 2.3
- azimuth: 345
elevation: 2.3
- azimuth: 352.5
elevation: 2.3
- azimuth: 360
elevation: 2.3
ashraeStation: PRAIRIE RIDGE RGNL AP, ST, USA
ashraeVersion: 2021
cool996: 37.6
max50Year: 45.4
min50Year: -28.9
minAnnualMeanDBTemp: -17.2
elevation: 229
timeZone: -6
weatherId: 139907
projectId: 187749
shading3DModel: 0
percentComplete: 100
processingStatus: 0
processingStep: 40
processingMessage: Unknown
pValues: []
isReadOnly: false
pValuesString: ''
nodalData: false
hasTimeSeriesData: false
isBatch: false
batchStepVariable: []
batchQualified: true
logicVersion: 10
mapBuilderCreateDCAs: 0
useMapBuilder: false
scenePropertiesKey: 00000000-0000-0000-0000-000000000000
setback: 0
targetDC: 0
weatherLocked: false
electricalShadingFractionalEffect: 100
numberOfModuleFractions: 0
numOfBlocks: 1
numOfWeatherDetails: 8760
hasObjectShading: false
numOfShadingObjects: 0
reportsId: 943796
canImportAlbedoData: false
runningOnVMName: ''
runCompletedDateTimeUTC: '2026-02-06T13:01:41.323'
useSpectral30: false
spectral30B0: -0.0967
spectral30B1: 0.0126
spectral30B2: 0
spectral30B3: 0.00223
spectral30B4: 0
spectral30B5: 0
spectral30B6: 1.086
id: 957032
name: Site B – Fixed-Tilt Baseline (v10)
description: Cloned from prior baseline study and updated for fixed-tilt layout; created for comparative analysis.
companyId: 1042
ownerId: 8903
createdDate: '2026-02-06T14:19:24.517'
lastModified: '2026-02-06T14:19:24.517'
lastModifiedById: 8903
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
post:
tags:
- Predictions
summary: Create a prediction
description: 'Creates a new prediction under the given project. The prediction starts in `status: 0` (Draft) and must subsequently be associated with a `PowerPlant` via `POST .../PowerPlant` before it can be run. Most model parameters can be left at their defaults; see the `Prediction` schema for the complete list and their enum values.'
operationId: createPrediction
x-doc-source: drafted
parameters:
- name: projectId
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Prediction'
examples:
postman-projects-prediction-prediction:
value:
name: Postman Doc Sample
status: 1
pValues: []
horizonDetails: []
nonLinearDegradationRates: []
plantDesignTemperatures: []
yearRepeater: 1
airMassModel: 0
modTempModel: 0
incAngleModel: 5
directBeamShadingModel: 5
degradationModel: 0
diffuseShadingModel: 1
transpositionModel: 1
diffuseDirectDecompModel: 3
max50Year: 39.4
min50Year: -30.3
cool996: 32.5
minAnnualMeanDBTemp: -19.1
elevation: 184
timeZone: -5
ashraeStation: TOLEDO CGS, OH, USA
ashraeWMO: '997295'
ashraeDistance: 7.079021066538359
monthlyFactors:
- month: 1
soilingLoss: 2.2
albedo: 0.3
- month: 2
soilingLoss: 2.2
albedo: 0.3
- month: 3
soilingLoss: 2.2
albedo: 0.3
- month: 4
soilingLoss: 2.2
albedo: 0.3
- month: 5
soilingLoss: 2.2
albedo: 0.3
- month: 6
soilingLoss: 2.2
albedo: 0.3
- month: 7
soilingLoss: 2.2
albedo: 0.3
- month: 8
soilingLoss: 2.2
albedo: 0.3
- month: 9
soilingLoss: 2.2
albedo: 0.3
- month: 10
soilingLoss: 2.2
albedo: 0.3
- month: 11
soilingLoss: 2.2
albedo: 0.3
- month: 12
soilingLoss: 2.2
albedo: 0.3
spectralShiftModel: 2
soilingModel: 0
useMeteoDni: false
firstYearDegradation: false
linearDegradationRate: 0.5
errorIntAnnVar: 3
errorSensAcc: 5
errorMonAcc: 2
errorSpaVar: 2
errorModelAcc: 2.9
logicVersion: 11
ashraeVersion: 2021
originalAshraeStation: TOLEDO CGS, OH, USA
originalAshraeWMO: '997295'
originalAshraeDistance: 7.079021066538359
originalCool996: 32.5
originalMax50Year: 39.4
originalMin50Year: -30.3
originalMinAnnualMeanDBTemp: -19.1
originalTimeZone: -5
originalElevation: 184
circumsolarTreatment: 0
responses:
'200':
description: Created prediction ID
content:
application/json:
schema:
$ref: '#/components/schemas/IdResponse'
examples:
postman-prediction:
value:
id: 726228
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/ServerError'
put:
tags:
- Predictions
summary: Update a prediction
description: "Updates an existing prediction. May attach an X-Message header with a non-blocking warning about the updated entity.\n\n**Parameters:**\n\n- `projectId` (path, required): The project ID.\n \n- `prediction` (body, required): The updated prediction entity.\n"
operationId: updatePrediction
x-doc-source: postman
parameters:
- name: projectId
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Prediction'
examples:
postman-projects-prediction-prediction:
value:
name: Postman Doc Sample - Name Update
description: Sample Description PUT
status: 1
yearRepeater: 1
transpositionModel: 1
perezCoefficients: 0
diffuseDirectDecompModel: 3
circumsolarTreatment: 0
diffuseDirectDecompModelExecuted: false
useMeteoDni: false
useMeteoPOAI: false
useBacksidePOAI: false
useLeapYears: false
useWeatherFileAlbedoData: false
useMetastability: false
enableLeTID: false
airMassModel: 0
soilingModel: 0
modTempModel: 0
incAngleModel: 5
directBeamShadingModel: 5
degradationModel: 0
diffuseShadingModel: 1
linearDegradationRate: 0.5
firstYearDegradation: false
nonLinearDegradationRates: []
lightAndElevatedTemperatureDegradationRates: []
errorModelAcc: 2.9
errorSensAcc: 5
errorIntAnnVar: 3
errorMonAcc: 2
errorSpaVar: 2
siteResultList: null
spectralShiftModel: 2
spectralWeatherType: 0
powerPlantId: null
monthlyFactors:
- id: 39132062
month: 1
monthName: Jan
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132063
month: 2
monthName: Feb
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132064
month: 3
monthName: Mar
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132065
month: 4
monthName: Apr
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132066
month: 5
monthName: May
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132067
month: 6
monthName: Jun
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132068
month: 7
monthName: Jul
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132069
month: 8
monthName: Aug
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132070
month: 9
monthName: Sep
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132071
month: 10
monthName: Oct
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132072
month: 11
monthName: Nov
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
- id: 39132073
month: 12
monthName: Dec
soilingLoss: 2.2
albedo: 0.3
spectralShift: null
horizonDetails: []
ashraeStation: TOLEDO CGS, OH, USA
ashraeVersion: 2021
heat996: null
cool996: 32.5
max50Year: 39.4
min50Year: -30.3
minAnnualMeanDBTemp: -19.1
weather: null
weatherId: null
projectId: 133005
pValues: []
pValuesString: ''
logicVersion: 11
setback: 0
targetDC: 0
weatherLocked: false
electricalShadingFractionalEffect: 100
useSpectral30: false
spectral30B0: -0.0967
spectral30B1: 0.0126
spectral30B2: 0.00223
spectral30B3: 1.086
id: 957033
responses:
'200':
description: Update result
content:
application/json:
schema:
$ref: '#/components/schemas/PredictionUpdateResponse'
examples:
postman-prediction:
value:
changesMade: true
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/ServerError'
/Project/{projectId}/Prediction/{predictionId}:
get:
tags:
- Predictions
summary: Get a prediction
description: "Retrieves a single prediction by project and prediction ID. Does not includ
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/terabase-energy/refs/heads/main/openapi/terabase-energy-predictions-api-openapi.yml