Terabase Energy Shade Scene API

openapi: 3.2.0
info:
  title: PlantPredict Shade Scene 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: ShadeScene
  description: 3D shade scene management and calculations
paths:
  /ShadeScene/ConvertPVCtoPVJ:
    post:
      tags:
      - ShadeScene
      summary: Convert PVC file to PVJ shade scene format
      description: The PlantPredict 3D Scene uses a JSON-based format to represent common shapefiles (e.g., PVC, SHD). This endpoint converts a standard PV Collada file into the compatible PVJ format.
      operationId: convertPVCtoPVJ
      x-doc-source: postman
      parameters:
      - name: Latitude
        in: query
        required: true
        schema:
          type: number
      - name: Longitude
        in: query
        required: true
        schema:
          type: number
      - name: RotateShadingResult
        in: query
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Converted shade scene
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShadeSceneProperties'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /ShadeScene/ConvertSHDtoPVJ:
    post:
      tags:
      - ShadeScene
      summary: Convert SHD file to PVJ shade scene format
      description: The PlantPredict 3D Scene uses a JSON-based format to represent common shapefiles (e.g., PVC, SHD). This endpoint converts a standard SHD file into the compatible PVJ format.
      operationId: convertSHDtoPVJ
      x-doc-source: postman
      parameters:
      - name: Latitude
        in: query
        required: true
        schema:
          type: number
      - name: Longitude
        in: query
        required: true
        schema:
          type: number
      - name: RotateShadingResult
        in: query
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Converted shade scene
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShadeSceneProperties'
              examples:
                postman-convert-shd-to-pvj:
                  value:
                    latitude: 43
                    longitude: -84
                    shadeSceneSurfaceArea: 2399.923896000002
                    shadingObjectCount: 0
                    shadingTableCount: 105
                    shadingElectricalEffectModel: 0
                    fractionalShadingPercent: 0
                    useRotationAngleSchedule: false
                    boundingBoxType: 0
                    numberOfModuleFractions: null
                    tables:
                    - id: 0
                      refId: Shd_1
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 0
                        refId: Shd_1_Geometry
                        points:
                        - x: -50.66899999999999
                          y: 33.43403797752449
                          z: -2.1880331978122705
                        - x: -50.669
                          y: 24.402000000000008
                          z: 0.131
                        - x: -48.196999999999996
                          y: 24.402000000000008
                          z: 0.131
                        - x: -48.19699999999999
                          y: 33.43403797752449
                          z: -2.1880331978122705
                    - id: 1
                      refId: Shd_2
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 1
                        refId: Shd_2_Geometry
                        points:
                        - x: -50.669
                          y: 23.79519292333526
                          z: 0.24967103921971479
                        - x: -50.669
                          y: 14.763000000000005
                          z: 1.94
                        - x: -48.196999999999996
                          y: 14.763000000000005
                          z: 1.94
                        - x: -48.196999999999996
                          y: 23.79519292333526
                          z: 0.24967103921971479
                    - id: 2
                      refId: Shd_3
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 2
                        refId: Shd_3_Geometry
                        points:
                        - x: -50.669
                          y: 14.15619292333526
                          z: 2.058671039219715
                        - x: -50.669
                          y: 5.124000000000006
                          z: 3.749
                        - x: -48.196999999999996
                          y: 5.124000000000006
                          z: 3.749
                        - x: -48.196999999999996
                          y: 14.15619292333526
                          z: 2.058671039219715
                    - id: 3
                      refId: Shd_4
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 3
                        refId: Shd_4_Geometry
                        points:
                        - x: -50.669
                          y: 4.518192923335262
                          z: 3.8676710392197142
                        - x: -50.669
                          y: -4.513999999999994
                          z: 5.558
                        - x: -48.196999999999996
                          y: -4.513999999999994
                          z: 5.558
                        - x: -48.196999999999996
                          y: 4.518192923335262
                          z: 3.8676710392197142
                    - id: 4
                      refId: Shd_5
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 4
                        refId: Shd_5_Geometry
                        points:
                        - x: -50.669
                          y: -5.119837164209945
                          z: 5.676802227303641
                        - x: -50.669
                          y: -14.152999999999995
                          z: 7.351
                        - x: -48.196999999999996
                          y: -14.152999999999995
                          z: 7.351
                        - x: -48.196999999999996
                          y: -5.119837164209945
                          z: 5.676802227303641
                    - id: 5
                      refId: Shd_6
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 5
                        refId: Shd_6_Geometry
                        points:
                        - x: -50.669
                          y: -14.760801100217778
                          z: 7.4230767386847045
                        - x: -50.669
                          y: -23.791999999999994
                          z: 8.58
                        - x: -48.196999999999996
                          y: -23.791999999999994
                          z: 8.58
                        - x: -48.196999999999996
                          y: -14.760801100217778
                          z: 7.4230767386847045
                    - id: 6
                      refId: Shd_7
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 6
                        refId: Shd_7_Geometry
                        points:
                        - x: -50.669
                          y: -24.399801100217772
                          z: 8.652076738684704
                        - x: -50.669000000000004
                          y: -33.43099999999999
                          z: 9.809
                        - x: -48.197
                          y: -33.43099999999999
                          z: 9.809
                        - x: -48.196999999999996
                          y: -24.399801100217772
                          z: 8.652076738684704
                    - id: 7
                      refId: Shd_8
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 7
                        refId: Shd_8_Geometry
                        points:
                        - x: -43.60699999999999
                          y: 33.43419292333526
                          z: -3.748328960780285
                        - x: -43.607
                          y: 24.402000000000008
                          z: -2.058
                        - x: -41.135
                          y: 24.402000000000005
                          z: -2.058
                        - x: -41.13499999999999
                          y: 33.43419292333526
                          z: -3.748328960780285
                    - id: 8
                      refId: Shd_9
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 8
                        refId: Shd_9_Geometry
                        points:
                        - x: -43.607
                          y: 23.79519292333526
                          z: -1.9393289607802853
                        - x: -43.607
                          y: 14.763000000000005
                          z: -0.249
                        - x: -41.135
                          y: 14.763000000000005
                          z: -0.249
                        - x: -41.135
                          y: 23.795192923335257
                          z: -1.9393289607802853
                    - id: 9
                      refId: Shd_10
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 9
                        refId: Shd_10_Geometry
                        points:
                        - x: -43.607
                          y: 14.15619292333526
                          z: -0.1303289607802851
                        - x: -43.607
                          y: 5.124000000000005
                          z: 1.56
                        - x: -41.135
                          y: 5.124000000000005
                          z: 1.56
                        - x: -41.135
                          y: 14.15619292333526
                          z: -0.1303289607802851
                    - id: 10
                      refId: Shd_11
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 10
                        refId: Shd_11_Geometry
                        points:
                        - x: -43.607
                          y: 4.519162835790056
                          z: 1.6798022273036413
                        - x: -43.607
                          y: -4.513999999999995
                          z: 3.354
                        - x: -41.135
                          y: -4.513999999999995
                          z: 3.354
                        - x: -41.135
                          y: 4.519162835790056
                          z: 1.6798022273036413
                    - id: 11
                      refId: Shd_12
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 11
                        refId: Shd_12_Geometry
                        points:
                        - x: -43.607
                          y: -5.120809205775187
                          z: 3.4669496740761025
                        - x: -43.607
                          y: -14.152999999999995
                          z: 4.624
                        - x: -41.135
                          y: -14.152999999999995
                          z: 4.624
                        - x: -41.135
                          y: -5.120809205775187
                          z: 3.4669496740761025
                    - id: 12
                      refId: Shd_13
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 12
                        refId: Shd_13_Geometry
                        points:
                        - x: -43.607
                          y: -14.760801100217778
                          z: 4.695076738684705
                        - x: -43.607
                          y: -23.791999999999994
                          z: 5.852
                        - x: -41.135
                          y: -23.791999999999998
                          z: 5.852
                        - x: -41.135
                          y: -14.760801100217778
                          z: 4.695076738684705
                    - id: 13
                      refId: Shd_14
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 13
                        refId: Shd_14_Geometry
                        points:
                        - x: -43.607
                          y: -24.399801100217772
                          z: 5.924076738684705
                        - x: -43.607000000000006
                          y: -33.43099999999999
                          z: 7.081
                        - x: -41.135000000000005
                          y: -33.43099999999999
                          z: 7.081
                        - x: -41.135
                          y: -24.399801100217775
                          z: 5.924076738684705
                    - id: 14
                      refId: Shd_15
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 14
                        refId: Shd_15_Geometry
                        points:
                        - x: -36.54599999999999
                          y: 33.43419292333526
                          z: -5.565328960780285
                        - x: -36.546
                          y: 24.402000000000005
                          z: -3.875
                        - x: -34.074
                          y: 24.402000000000005
                          z: -3.875
                        - x: -34.07399999999999
                          y: 33.43419292333526
                          z: -5.565328960780285
                    - id: 15
                      refId: Shd_16
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 15
                        refId: Shd_16_Geometry
                        points:
                        - x: -36.546
                          y: 23.795192923335257
                          z: -3.756328960780285
                        - x: -36.546
                          y: 14.763000000000005
                          z: -2.066
                        - x: -34.074
                          y: 14.763000000000003
                          z: -2.066
                        - x: -34.074
                          y: 23.795192923335257
                          z: -3.756328960780285
                    - id: 16
                      refId: Shd_17
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 16
                        refId: Shd_17_Geometry
                        points:
                        - x: -36.546
                          y: 14.15619292333526
                          z: -1.9473289607802853
                        - x: -36.546
                          y: 5.124000000000004
                          z: -0.257
                        - x: -34.074
                          y: 5.124000000000004
                          z: -0.257
                        - x: -34.074
                          y: 14.156192923335258
                          z: -1.9473289607802853
                    - id: 17
                      refId: Shd_18
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 17
                        refId: Shd_18_Geometry
                        points:
                        - x: -36.546
                          y: 4.518656710627976
                          z: -0.13570108556108496
                        - x: -36.546
                          y: -4.513999999999996
                          z: 1.457
                        - x: -34.074
                          y: -4.513999999999996
                          z: 1.457
                        - x: -34.074
                          y: 4.518656710627976
                          z: -0.13570108556108496
                    - id: 18
                      refId: Shd_19
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 18
                        refId: Shd_19_Geometry
                        points:
                        - x: -36.546
                          y: -5.1208092057751875
                          z: 1.5689496740761029
                        - x: -36.546
                          y: -14.152999999999995
                          z: 2.726
                        - x: -34.074
                          y: -14.152999999999997
                          z: 2.726
                        - x: -34.074
                          y: -5.1208092057751875
                          z: 1.5689496740761029
                    - id: 19
                      refId: Shd_20
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 19
                        refId: Shd_20_Geometry
                        points:
                        - x: -36.546
                          y: -14.760801100217778
                          z: 2.7980767386847045
                        - x: -36.546
                          y: -23.791999999999998
                          z: 3.955
                        - x: -34.074
                          y: -23.791999999999998
                          z: 3.955
                        - x: -34.074
                          y: -14.76080110021778
                          z: 2.7980767386847045
                    - id: 20
                      refId: Shd_21
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 20
                        refId: Shd_21_Geometry
                        points:
                        - x: -36.546
                          y: -24.399801100217775
                          z: 4.027076738684705
                        - x: -36.54600000000001
                          y: -33.43099999999999
                          z: 5.184
                        - x: -34.074000000000005
                          y: -33.43099999999999
                          z: 5.184
                        - x: -34.074
                          y: -24.399801100217775
                          z: 4.027076738684705
                    - id: 21
                      refId: Shd_22
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 21
                        refId: Shd_22_Geometry
                        points:
                        - x: -29.483999999999998
                          y: 33.43419292333526
                          z: -7.382328960780285
                        - x: -29.483999999999998
                          y: 24.402000000000005
                          z: -5.692
                        - x: -27.011999999999997
                          y: 24.402000000000005
                          z: -5.692
                        - x: -27.011999999999997
                          y: 33.43419292333525
                          z: -7.382328960780285
                    - id: 22
                      refId: Shd_23
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 22
                        refId: Shd_23_Geometry
                        points:
                        - x: -29.483999999999998
                          y: 23.795192923335257
                          z: -5.573328960780286
                        - x: -29.483999999999998
                          y: 14.763000000000003
                          z: -3.883
                        - x: -27.011999999999997
                          y: 14.763000000000003
                          z: -3.883
                        - x: -27.011999999999997
                          y: 23.795192923335257
                          z: -5.573328960780286
                    - id: 23
                      refId: Shd_24
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 23
                        refId: Shd_24_Geometry
                        points:
                        - x: -29.484
                          y: 14.156947289941709
                          z: -3.7642837466531356
                        - x: -29.484
                          y: 5.124000000000003
                          z: -2.139
                        - x: -27.012
                          y: 5.124000000000003
                          z: -2.139
                        - x: -27.012
                          y: 14.156947289941709
                          z: -3.7642837466531356
                    - id: 24
                      refId: Shd_25
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 24
                        refId: Shd_25_Geometry
                        points:
                        - x: -29.484
                          y: 4.517671902874965
                          z: -2.0335274373834187
                        - x: -29.484
                          y: -4.513999999999997
                          z: -0.441
                        - x: -27.012
                          y: -4.513999999999997
                          z: -0.441
                        - x: -27.012
                          y: 4.517671902874965
                          z: -2.0335274373834187
                    - id: 25
                      refId: Shd_26
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 25
                        refId: Shd_26_Geometry
                        points:
                        - x: -29.484
                          y: -5.120809205775188
                          z: -0.32805032592389716
                        - x: -29.484
                          y: -14.152999999999997
                          z: 0.829
                        - x: -27.012
                          y: -14.152999999999997
                          z: 0.829
                        - x: -27.012
                          y: -5.120809205775188
                          z: -0.32805032592389716
                    - id: 26
                      refId: Shd_27
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 26
                        refId: Shd_27_Geometry
                        points:
                        - x: -29.484000000000005
                          y: -14.76080110021778
                          z: 0.9000767386847042
                        - x: -29.484000000000005
                          y: -23.791999999999998
                          z: 2.057
                        - x: -27.012000000000004
                          y: -23.791999999999998
                          z: 2.057
                        - x: -27.012000000000004
                          y: -14.76080110021778
                          z: 0.9000767386847042
                    - id: 27
                      refId: Shd_28
                      table_Type: 1
                      inverter_Id: ''
                      group_Id: ''
                      table_Id: ''
                      geometries:
                      - id: 27
                        refId: Shd_28_Geometry
                        points:
                        - x: -29.484000000000005
                          y: -24.399677447112307
                          z: 2.1274068949950955
                        - 

# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/terabase-energy/refs/heads/main/openapi/terabase-energy-shadescene-api-openapi.yml