openapi: 3.2.0
info:
title: PlantPredict Company 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: Company
description: Company settings and user management
paths:
/Company/DefaultSettings:
get:
tags:
- Company
summary: Get company default settings
description: Returns default settings for your company.
operationId: getCompanyDefaultSettings
x-doc-source: postman
responses:
'200':
description: Default settings
content:
application/json:
schema:
type: object
properties:
id:
type: integer
environmentalConditions:
type: object
description: The Environmental Conditions Page allows you to configure the weather and environmental parameters that influence solar resource modeling in your prediction. This includes selecting weather data, defining soiling and spectral loss profiles, setting design temperatures, and importing horizon scene data.
x-doc-source: inferred+docs:user-guide/ui/environmental-conditions.mdx
properties:
id:
type: integer
monthlySoilingLoss:
type: number
monthlyAlbedo:
type: number
powerPlantBuilder:
type: object
description: The 3D View provides tools for analyzing terrain and racking placement within your map-based power plant design. This interface enables terrain slope analysis, table slope constraint identification, and post height calculations.
x-doc-source: inferred+docs:user-guide/ui/power-plant-builder-3d-view.mdx
properties:
id:
type: integer
acCollectionLoss:
type: number
dasLoad:
type: number
coolingLoad:
type: number
transformerHighSideVoltage:
type: number
transformerNoLoadLoss:
type: number
transformerFullLoadLoss:
type: number
powerFactor:
type: number
inverter:
type: object
properties:
status:
type: integer
model:
type: string
manufacturer:
type: string
powerRated:
type: number
apparentPower:
type: number
minDCPowerThreshold:
type: number
minVoltage:
type: number
maxMPPVoltage:
type: number
maxAbsoluteVoltage:
type: number
maxCurrent:
type: number
maxElevation:
type: number
outputVoltage:
type: number
usekVACurves:
type: boolean
usePQCurves:
type: boolean
dataSource:
type: integer
efficiencyCurves:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
kVACurves:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
pqCurves:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
inverterType:
type: integer
id:
type: integer
name:
type: string
description:
type: string
companyId:
type: integer
company:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
ownerId:
type: integer
owner:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
createdDate:
type: string
description: ISO-8601 datetime as returned by the PlantPredict API. May or may not include a timezone offset.
lastModified:
type: string
description: ISO-8601 datetime as returned by the PlantPredict API. May or may not include a timezone offset.
lastModifiedById:
type: integer
lastModifiedBy:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
inverter_Id:
type: integer
dcacRatio:
type: number
dcWiringLossAtSTC:
type: number
dcHealth:
type: number
trackerLoadLoss:
type: number
minimumTrackingLimitAngleD:
type: number
maximumTrackingLimitAngleD:
type: number
structureShading:
type: number
module_Id:
type: integer
module:
type: object
properties:
status:
type: integer
model:
type: string
manufacturer:
type: string
length:
type: number
width:
type: number
weight:
type: number
defaultOrientation:
type: integer
numberOfCellsInSeries:
type: integer
numberOfCellsInParallel:
type: integer
stcShortCircuitCurrent:
type: number
stcOpenCircuitVoltage:
type: number
stcmppCurrent:
type: number
stcmppVoltage:
type: number
stcMaxPower:
type: number
stcPowerTempCoef:
type: number
stcShortCircuitCurrentTempCoef:
type: number
stcOpenCircuitVoltageTempCoef:
type: number
stcEfficiency:
type: number
minTolerance:
type: number
maxTolerance:
type: number
cellTechnologyType:
type: integer
constructionType:
type: integer
faciality:
type: integer
bifacialityFactor:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
transmissionFactor:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
backSideMismatch:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
dataSource:
type: integer
lightInducedDegradation:
type: number
moduleQuality:
type: number
moduleMismatchCoefficient:
type: number
heatBalanceConvectiveCoef:
type: number
heatBalanceConductiveCoef:
type: number
sandiaConductiveCoef:
type: number
sandiaConvectiveCoef:
type: number
cellToModuleTempDiff:
type: number
saturationCurrentAtSTC:
type: number
seriesResistanceAtSTC:
type: number
shuntResistanceAtSTC:
type: number
diodeIdealityFactorAtSTC:
type: number
exponentialDependencyOnShuntResistance:
type: number
darkShuntResistance:
type: number
linearTempDependenceOnGamma:
type: number
shortCircuitCurrentAtSTC:
type: number
recombinationParameter:
type: number
builtInVoltage:
type: number
bandgapVoltage:
type: number
linearTempDependenceOnIsc:
type: number
heatAbsorptionCoefAlphaT:
type: number
referenceIrradiance:
type: number
referenceTemperature:
type: number
aGamma:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
bGamma:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
cGamma:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
dGamma:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
spectralResponse:
type: integer
pvModel:
type: integer
useDefaultSandiaIAM:
type: boolean
useDefaultTabularIAM:
type: boolean
sandiaSpectralA0:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
sandiaSpectralA1:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
sandiaSpectralA2:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
sandiaSpectralA3:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
sandiaSpectralA4:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
sandiaIAMB0:
type: number
sandiaIAMB1:
type: number
sandiaIAMB2:
type: number
sandiaIAMB3:
type: number
sandiaIAMB4:
type: number
sandiaIAMB5:
type: number
ashraeiamB0:
type: number
spectral2B0:
type: number
spectral2B1:
type: number
spectral2B2:
type: number
spectral2B3:
type: number
spectral2B4:
type: number
spectral2B5:
type: number
iamFactors:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
degradationModel:
type: integer
linearDegradationRate:
type: number
nonLinearDegradationRates:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
cellDesignType:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
useAntiReflectiveCoating:
type: boolean
refractiveIndex:
type: number
refractiveIndexOfARC:
type: number
glazingExtinctionCoef:
type: number
glazingThickness:
type: number
powerAtSTC:
type: number
powerAtSTCExcludingWiringLosses:
type: number
effectiveIrradianceResponse:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
electricalShadingFractionalEffect:
type: number
moduleShadingResponse:
type: integer
isMetastable:
type: boolean
metastabilityProperties:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
id:
type: integer
name:
type: string
description:
type: string
companyId:
type: integer
company:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
ownerId:
type: integer
owner:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
createdDate:
type: string
description: ISO-8601 datetime as returned by the PlantPredict API. May or may not include a timezone offset.
lastModified:
type: string
description: ISO-8601 datetime as returned by the PlantPredict API. May or may not include a timezone offset.
lastModifiedById:
type: integer
lastModifiedBy:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
dcFieldTrackingTypeEnum:
type: integer
tiltAngle:
type: number
gcr:
type: number
northernHemisphereAzimuth:
type: number
southernHemisphereAzimuth:
type: number
azimuth:
type: number
irradianceOptimization:
type: boolean
irradianceOptimizationType:
type: integer
rotationSpeed:
type: number
nonIdealityFactor:
type: number
postHeightCalculationMethod:
type: integer
postHeight:
type: number
modTempModel:
type: integer
mapBuilderCreateDCAs:
type: integer
shadingAlgorithm:
type: integer
setback:
type: number
northSouthRoadWidth:
type: number
eastWestRoadWidth:
type: number
simulationSettings:
type: object
description: The Simulation Settings page allows you to configure the prediction timeframe and select the sub-models used for irradiance calculation, module performance, shading analysis, and degradation. These settings control the algorithms applied during the energy prediction simulation.
x-doc-source: inferred+docs:user-guide/ui/simulation-settings.mdx
properties:
id:
type: integer
errorModelAcc:
type: number
errorSensAcc:
type: number
errorIntAnnVar:
type: number
errorMonAcc:
type: number
errorSpaVar:
type: number
transpositionModel:
type: integer
diffuseDirectDecompModel:
type: integer
useMeteoDni:
type: boolean
airMassModel:
type: integer
soilingModel:
type: integer
modTempModel:
type: integer
spectralShiftModel:
type: integer
incAngleModel:
type: integer
directBeamShadingModel:
type: integer
degradationModel:
type: integer
diffuseShadingModel:
type: integer
defaultDegradation:
type: integer
circumsolarTreatment:
type: integer
linearDegradationRate:
type: number
firstYearDegradation:
type: boolean
weatherAPISettings:
type: object
description: 'The Add New Weather page provides three methods for adding weather data to PlantPredict:'
x-doc-source: inferred+docs:user-guide/ui/add-new-weather.mdx
properties:
id:
type: integer
meteonormSettings:
type: object
properties:
key:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
cprSettings:
type: object
properties:
apiKey:
type: string
userName:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
password:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
licenseNumber:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
solarGISSettings:
type: object
properties:
key:
type: string
tmyKey:
type: string
version:
type: integer
arrayTechnologiesAPIKey:
type: string
essSettings:
type: object
description: 'The Energy Storage System page allows you to configure an optional AC-coupled battery energy storage system (BESS) for your prediction. To enable energy storage, enter a Nameplate capacity value (input #1) and an Inverter Real Power rating (input #9). The Dispatch Algorithm should also be configured to ensure the...'
x-doc-source: inferred+docs:user-guide/ui/energy-storage-system.mdx
properties:
id:
type: integer
factor:
type: number
usableEnergyCapacityCalendarDeg:
type: number
usableEnergyCapacityCycleDeg:
type: number
roundtripDCEfficiencyYear1:
type: number
roundtripDCEfficiencyCalendarDeg:
type: number
roundtripDCEfficiencyCycleDeg:
type: number
hvacNoLoadLoss:
type: number
hvacFullLoadLoss:
type: number
mvNoLoadLoss:
type: number
mvFullLoadLoss:
type: number
mvCapacity:
description: Observed as null in test-account samples; the field's actual type is undocumented. Re-run the typing probe against an account where this field is populated to refine.
inverterEfficiency:
type: number
chargeAlgorithm:
type: integer
financialModelParameters:
type: object
x-doc-source: inferred
properties:
id:
type: integer
bosInput:
type: number
developmentCostPerWatt:
type: number
moduleCostPerWatt:
type: number
itcPercentage:
type: number
yearOneE
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/terabase-energy/refs/heads/main/openapi/terabase-energy-company-api-openapi.yml