openapi: 3.2.0
info:
title: PlantPredict Projects 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: Projects
description: Solar project management
paths:
/Project:
get:
tags:
- Projects
summary: List projects (paginated)
description: "Returns a paginated list of projects for which the user has access. Supports optional pagination parameters.\n\n**Parameters:**\n\n- `skip` (query, optional): Number of records to skip for pagination.\n \n- `top` (query, optional): Maximum number of records to return.\n"
operationId: listProjects
x-doc-source: postman
parameters:
- name: skip
in: query
schema:
type: integer
default: 0
- name: top
in: query
schema:
type: integer
default: 10
responses:
'200':
description: Array of projects
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Project'
examples:
postman-projects:
value:
- latitude: 41.6528052
longitude: -83.5378674
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Toledo
region: North America
elevation: 178.5460357666016
standardOffsetFromUTC: -5
status: 0
distance: 0
id: 190781
name: Mock Project Atlas
companyId: 1042
createdDate: '2026-01-29T09:49:36.19'
- latitude: 33.348
longitude: -112.817
country: United States
countryCode: US
stateProvince: Arizona
stateProvinceCode: AZ
locality: Arlington
region: North America
elevation: 268.2567138671875
standardOffsetFromUTC: -7
status: 0
distance: 0
id: 190780
name: Mock Project Saguaro
companyId: 1042
createdDate: '2026-01-29T09:47:08.917'
- latitude: 31.63
longitude: -89.95
country: United States
countryCode: US
stateProvince: Mississippi
stateProvinceCode: MS
locality: Prentiss
region: North America
elevation: 124.3755340576172
standardOffsetFromUTC: -6
status: 0
distance: 0
id: 190779
name: Mock Project Magnolia
companyId: 1042
createdDate: '2026-01-29T09:08:06.157'
- latitude: 37.745439395979105
longitude: -119.53304740776922
country: United States
countryCode: US
stateProvince: California
stateProvinceCode: CA
locality: Mariposa County
region: North America
elevation: 2675.35595703125
standardOffsetFromUTC: -8
status: 0
distance: 0
id: 190764
name: Mock Project Sierra
companyId: 1042
createdDate: '2026-01-26T21:42:48.037'
- latitude: 45.19650126701191
longitude: -84.9482652314071
country: United States
countryCode: US
stateProvince: Michigan
stateProvinceCode: MI
locality: Boyne City
region: North America
elevation: 210.8321380615234
standardOffsetFromUTC: -5
status: 0
distance: 0
id: 190744
name: Mock Project Great Lakes
companyId: 1042
createdDate: '2026-01-23T13:47:33.16'
- latitude: 45.5635
longitude: -120.5628
country: United States
countryCode: US
stateProvince: Oregon
stateProvinceCode: OR
locality: Wasco
region: North America
elevation: 461.2723083496094
standardOffsetFromUTC: -8
status: 0
distance: 0
id: 190742
name: Mock Project Columbia
companyId: 1042
createdDate: '2026-01-22T19:24:25.303'
- latitude: -35.14729
longitude: 149.599047
country: Australia
countryCode: AU
stateProvince: New South Wales
stateProvinceCode: NSW
locality: Tarago
region: Australia
elevation: 762.80419921875
standardOffsetFromUTC: 10
status: 0
distance: 0
id: 190738
name: Mock Project Southern Cross
companyId: 1042
createdDate: '2026-01-22T09:14:10.217'
- latitude: 45.64675117988259
longitude: -120.58828583328498
country: United States
countryCode: US
stateProvince: Oregon
stateProvinceCode: OR
locality: Wasco
region: North America
elevation: 379.0628356933594
standardOffsetFromUTC: -8
status: 0
distance: 0
id: 190737
name: Mock Project High Desert
companyId: 1042
createdDate: '2026-01-22T06:00:14.433'
- latitude: 45.64675117988259
longitude: -120.58828583328498
country: United States
countryCode: US
stateProvince: Oregon
stateProvinceCode: OR
locality: Wasco
region: North America
elevation: 379.0628356933594
standardOffsetFromUTC: -8
status: 0
distance: 0
id: 190736
name: Mock Project Cascade
companyId: 1042
createdDate: '2026-01-22T05:59:26.08'
- latitude: 38.122296115753
longitude: -91.40624999997603
country: United States
countryCode: US
stateProvince: Missouri
stateProvinceCode: MO
locality: Cuba
region: North America
elevation: 269.2212829589844
standardOffsetFromUTC: -6
status: 0
distance: 0
id: 190733
name: Mock Project Ozark
companyId: 1042
createdDate: '2026-01-22T05:20:26.747'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/ServerError'
post:
tags:
- Projects
summary: Create a project
description: "Creates a new project. Returns the created project ID. May attach an X-Message header with a non-blocking warning about the new entity.\n\n**Parameters:**\n\n- `project` (body, required): The project entity to create.\n \n- `enableMeteonormDownload` (query, optional): Whether to enable Meteonorm weather data download. Default: false.\n"
operationId: createProject
x-doc-source: postman
parameters:
- name: enableMeteonormDownload
in: query
required: false
schema:
type: boolean
default: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
examples:
postman-projects-project-project:
value:
latitude: 41.6528052
longitude: -83.5378674
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Toledo
region: North America
elevation: 178.5460357666016
standardOffsetFromUTC: -5
predictions: []
status: 0
name: Sample Project
description: null
responses:
'200':
description: Created project ID
content:
application/json:
schema:
$ref: '#/components/schemas/IdResponse'
examples:
postman-project:
value:
id: 76495
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/ServerError'
/Project/My:
get:
tags:
- Projects
summary: Get current user's projects
description: 'Returns all projects owned by the current user. Optionally filter by status.
**Parameters:**
- `status` (query, optional): Filter by project status (ProjectStatusEnum).
'
operationId: getMyProjects
x-doc-source: postman
parameters:
- name: status
in: query
required: false
schema:
type: integer
responses:
'200':
description: Array of projects
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Project'
examples:
postman-my-projects:
value:
- latitude: 37.09024
longitude: -95.712891
country: United States
countryCode: US
stateProvince: Kansas
stateProvinceCode: KS
locality: Montgomery County
region: North America
elevation: 257.4061584472656
standardOffsetFromUTC: -6
status: 0
distance: 0
id: 187745
name: Mock Project Sunflower
companyId: 1042
createdDate: '2024-10-23T12:50:21.497'
- latitude: 31
longitude: -95
country: United States
countryCode: US
stateProvince: Texas
stateProvinceCode: TX
locality: Groveton
region: North America
elevation: 128.1359710693359
standardOffsetFromUTC: -6
status: 0
distance: 0
id: 187746
name: Mock Project Pine Ridge
companyId: 1042
createdDate: '2024-10-23T12:58:32.03'
- latitude: -34.122009101021725
longitude: 150.4711842668258
country: Australia
countryCode: AU
stateProvince: New South Wales
stateProvinceCode: NSW
locality: Oakdale
region: Australia
elevation: 250.9766998291016
standardOffsetFromUTC: 10
status: 0
distance: 0
id: 187747
name: Mock Project Southern Sky
companyId: 1042
createdDate: '2024-10-23T12:59:23.027'
- latitude: -15.79453658771201
longitude: -47.2072032901765
country: Brazil
countryCode: BR
stateProvince: Goiás
stateProvinceCode: GO
locality: Formosa
region: South America
elevation: 912.9883422851562
standardOffsetFromUTC: -3
status: 0
distance: 0
id: 187748
name: Mock Project Cerrado
companyId: 1042
createdDate: '2024-10-23T13:03:51.75'
- latitude: 41.6528052
longitude: -83.5378674
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Toledo
region: North America
elevation: 178.5460357666016
standardOffsetFromUTC: -5
status: 0
distance: 0
id: 187749
name: Mock Project Papertrail
companyId: 1042
createdDate: '2024-10-23T13:04:30.243'
- latitude: 35.42887998943477
longitude: -81.85512828232781
country: United States
countryCode: US
stateProvince: North Carolina
stateProvinceCode: NC
locality: Bostic
region: North America
elevation: 299.8757629394531
standardOffsetFromUTC: -5
status: 0
distance: 0
id: 190210
name: Mock Project Blue Horizon
companyId: 1042
createdDate: '2025-10-22T19:22:47.63'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/ServerError'
/ProjectsAndPredictions/My:
get:
tags:
- Projects
summary: Get current user's projects including their predictions
description: Returns all projects owned by the current user, including their associated predictions. No parameters required.
operationId: getMyProjectsAndPredictions
x-doc-source: postman
responses:
'200':
description: Array of projects with nested predictions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Project'
examples:
postman-my-projects-predictions:
value:
- latitude: 37.09024
longitude: -95.712891
country: United States
countryCode: US
stateProvince: Kansas
stateProvinceCode: KS
locality: Montgomery County
region: North America
elevation: 257.4061584472656
standardOffsetFromUTC: -6
status: 0
distance: 0
id: 187745
name: Mock Project Sunflower
companyId: 1042
createdDate: '2024-10-23T12:50:21.497'
- latitude: 31
longitude: -95
country: United States
countryCode: US
stateProvince: Texas
stateProvinceCode: TX
locality: Groveton
region: North America
elevation: 128.1359710693359
standardOffsetFromUTC: -6
status: 0
distance: 0
id: 187746
name: Mock Project Pine Ridge
companyId: 1042
createdDate: '2024-10-23T12:58:32.03'
- latitude: -34.122009101021725
longitude: 150.4711842668258
country: Australia
countryCode: AU
stateProvince: New South Wales
stateProvinceCode: NSW
locality: Oakdale
region: Australia
elevation: 250.9766998291016
standardOffsetFromUTC: 10
status: 0
distance: 0
id: 187747
name: Mock Project Southern Sky
companyId: 1042
createdDate: '2024-10-23T12:59:23.027'
- latitude: -15.79453658771201
longitude: -47.2072032901765
country: Brazil
countryCode: BR
stateProvince: Goiás
stateProvinceCode: GO
locality: Formosa
region: South America
elevation: 912.9883422851562
standardOffsetFromUTC: -3
status: 0
distance: 0
id: 187748
name: Mock Project Cerrado
companyId: 1042
createdDate: '2024-10-23T13:03:51.75'
- latitude: 41.6528052
longitude: -83.5378674
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Toledo
region: North America
elevation: 178.5460357666016
standardOffsetFromUTC: -5
status: 0
distance: 0
id: 187749
name: Mock Project Papertrail
companyId: 1042
createdDate: '2024-10-23T13:04:30.243'
- latitude: 35.42887998943477
longitude: -81.85512828232781
country: United States
countryCode: US
stateProvince: North Carolina
stateProvinceCode: NC
locality: Bostic
region: North America
elevation: 299.8757629394531
standardOffsetFromUTC: -5
status: 0
distance: 0
id: 190210
name: Mock Project Blue Horizon
companyId: 1042
createdDate: '2025-10-22T19:22:47.63'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/ServerError'
/Project/Search:
get:
tags:
- Projects
summary: Search projects by geographic radius
description: "Returns projects within a geographic radius of a latitude/longitude point. Only projects the user has access to are included.\n\n**Parameters:**\n\n- `latitude` (query, required): Center point latitude.\n \n- `longitude` (query, required): Center point longitude.\n \n- `searchRadius` (query, required): Search radius in miles.\n"
operationId: searchProjects
x-doc-source: postman
parameters:
- name: latitude
in: query
required: true
schema:
type: number
format: double
- name: longitude
in: query
required: true
schema:
type: number
format: double
- name: searchRadius
in: query
required: true
schema:
type: number
responses:
'200':
description: Matching projects
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Project'
examples:
postman-project-search:
value:
- latitude: 41.3844964
longitude: -83.32048069999999
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Gibsonburg
region: North America
elevation: 208.6482391357422
standardOffsetFromUTC: -5
status: 0
distance: 0.38619901694003844
id: 173910
name: Mock Project Hearthstone
companyId: 1042
createdDate: '2024-05-04T13:55:02.667'
- latitude: 41.361566704160964
longitude: -83.31704747246094
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Gibsonburg
region: North America
elevation: 211.3801574707031
standardOffsetFromUTC: -5
status: 0
distance: 0.39669829386889693
id: 179578
name: Mock Project Sandhill
companyId: 1042
createdDate: '2024-06-17T17:53:49.503'
- latitude: 41.36
longitude: -83.32
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Gibsonburg
region: North America
elevation: 211.073486328125
standardOffsetFromUTC: -5
status: 0
distance: 0.39999999999999575
id: 123737
name: Mock Project Buckeye
companyId: 1042
createdDate: '2023-05-18T19:31:59.313'
- latitude: 41.56
longitude: -83.45
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Millbury
region: North America
elevation: 188.1432647705078
standardOffsetFromUTC: -5
status: 0
distance: 0.45177427992306346
id: 161410
name: Mock Project Lakeview
companyId: 1042
createdDate: '2024-02-28T15:50:12.63'
- latitude: 41.27017568847599
longitude: -82.8878170336973
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Bellevue
region: North America
elevation: 236.6902618408203
standardOffsetFromUTC: -5
status: 0
distance: 0.34838067455120497
id: 169082
name: Mock Project Ridgeway
companyId: 1042
createdDate: '2024-03-28T18:30:10.057'
- latitude: 41.26418140161006
longitude: -82.88165923151855
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Bellevue
region: North America
elevation: 238.0453338623047
standardOffsetFromUTC: -5
status: 0
distance: 0.356059922638487
id: 169080
name: Mock Project Heartland
companyId: 1042
createdDate: '2024-03-28T18:01:38.047'
- latitude: 41.65404
longitude: -83.53674
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Toledo
region: North America
elevation: 178.8838348388672
standardOffsetFromUTC: -5
status: 0
distance: 0.5394535653788881
id: 149782
name: Mock Project Riverbend
companyId: 1042
createdDate: '2023-12-04T17:26:27.027'
- latitude: 41.6528052
longitude: -83.5378674
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Toledo
region: North America
elevation: 178.5460357666016
standardOffsetFromUTC: -5
status: 0
distance: 0.5404532626692118
id: 159167
name: Mock Project Keystone
companyId: 1042
createdDate: '2024-02-14T12:49:43.447'
- latitude: 41.6528052
longitude: -83.5378674
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Toledo
region: North America
elevation: 178.5460357666016
standardOffsetFromUTC: -5
status: 0
distance: 0.5404532626692118
id: 159488
name: Mock Project Keystone West
companyId: 1042
createdDate: '2024-02-15T13:14:09.907'
- latitude: 41.6528052
longitude: -83.5378674
country: United States
countryCode: US
stateProvince: Ohio
stateProvinceCode: OH
locality: Toledo
region: North America
elevation: 178.5460357666016
standardOffsetFromUTC: -5
# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/terabase-energy/refs/heads/main/openapi/terabase-energy-projects-api-openapi.yml