openapi: 3.2.0
info:
  title: PlantPredict Time Series API
  version: 12.13.0
  description: '## What is PlantPredict?'
servers:
- url: https://api.plantpredict.terabase.energy
  description: Production
security:
- bearerAuth: []
tags:
- name: Time Series
  description: Custom time series data inputs
paths:
  /Project/{projectId}/Prediction/{predictionId}/TimeSeriesData:
    get:
      tags:
      - Time Series
      summary: List time series data sets
      description: 'Returns all time series data for a prediction.


        **Parameters:**


        - `projectId` (path, required): The project ID.


        - `predictionId` (path, required): The prediction ID.'
      operationId: listTimeSeries
      x-doc-source: postman
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: integer
      - name: predictionId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Time series list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeSeriesMeta'
              examples:
                postman-get-time-series:
                  value:
                  - id: 56735
                    predictionId: 707325
                    type: 3
                    name: 'MST Input #1'
                    detailsCount: 8760
                  - id: 56736
                    predictionId: 707325
                    type: 2
                    name: 'TSD Input #1'
                    detailsCount: 8760
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
      - Time Series
      summary: Create new time series
      description: 'Adds time series data via JSON. Requires TimeSeriesDTO with Details array.


        **Parameters:**


        - `projectId` (path, required): The project ID.


        - `predictionId` (path, required): The prediction ID.


        - `timeSeriesData` (body, required): TimeSeriesDTO with Details array (non-empty).'
      operationId: createTimeSeries
      x-doc-source: postman
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: integer
      - name: predictionId
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeSeriesDetail'
      responses:
        '200':
          description: Created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      tags:
      - Time Series
      summary: Upload time series CSV
      description: 'Updates time series data via file upload. Replaces existing data with the uploaded file contents.


        **Parameters:**


        - `projectId` (path, required): The project ID.


        - `predictionId` (path, required): The prediction ID.


        - `file` (form, required): The CSV or data file to upload.'
      operationId: uploadTimeSeriesCSV
      x-doc-source: postman
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: integer
      - name: predictionId
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Uploaded
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /Project/{projectId}/Prediction/{predictionId}/TimeSeriesData/Template:
    get:
      tags:
      - Time Series
      summary: Download time series CSV template
      description: 'Returns a CSV template for time series data upload. Use to understand the expected format.


        **Parameters:**


        - `projectId` (path, required): The project ID.


        - `predictionId` (path, required): The prediction ID.'
      operationId: getTimeSeriesTemplate
      x-doc-source: postman
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: integer
      - name: predictionId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: CSV template file
          content:
            text/csv:
              schema:
                type: string
                description: 'CSV template: header row only. Fill in values per row and

                  re-upload via `POST .../TimeSeriesData` to create a new

                  time series.

                  '
              example: 'timestamp,value

                2024-01-01T00:00:00,

                2024-01-01T01:00:00,

                2024-01-01T02:00:00,

                '
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /Project/{projectId}/Prediction/{predictionId}/TimeSeriesData/{timeSeriesId}/Details:
    get:
      tags:
      - Time Series
      summary: Get time series details
      description: Returns the specified time series data properties, including timestamp details.
      operationId: getTimeSeriesDetails
      x-doc-source: postman
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: integer
      - name: predictionId
        in: path
        required: true
        schema:
          type: integer
      - name: timeSeriesId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Time series with row data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /Project/{projectId}/Prediction/{predictionId}/TimeSeriesData/{timeSeriesId}/CSV:
    get:
      tags:
      - Time Series
      summary: Download time series as CSV
      description: Returns the specified time series data properties, including timestamp details except as a .csv binary stream.
      operationId: downloadTimeSeriesCSV
      x-doc-source: postman
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: integer
      - name: predictionId
        in: path
        required: true
        schema:
          type: integer
      - name: timeSeriesId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string
                description: Time-series data exported as CSV, one row per timestamp.
              example: 'timestamp,value

                2024-01-01T00:00:00,0.250

                2024-01-01T01:00:00,0.251

                2024-01-01T02:00:00,0.253

                '
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /Project/{projectId}/Prediction/{predictionId}/TimeSeriesData/{timeSeriesId}:
    delete:
      tags:
      - Time Series
      summary: Delete a time series
      description: 'Deletes a time series data entry by ID. Note: Time series inputs with active assignments to a power plant cannot be deleted.


        **Parameters:**


        - `projectId` (path, required): The project ID.


        - `predictionId` (path, required): The prediction ID.


        - `timeSeriesId` (path, required): The time series entry ID to delete.'
      operationId: deleteTimeSeries
      x-doc-source: postman
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: integer
      - name: predictionId
        in: path
        required: true
        schema:
          type: integer
      - name: timeSeriesId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    TimeSeriesMeta:
      type: object
      properties:
        id:
          type: integer
        predictionId:
          type: integer
        type:
          type: integer
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          x-enum-varnames:
          - InverterSetPoint
          - InverterDerate
          - TrackingAngle
          - ModuleSurfaceTemperature
          - LGIALimit
          - IMPPAdjustment
          - VMPPAdjustment
          description: TimeSeriesType
        name:
          type: string
        detailsCount:
          type: integer
    ModelStateError:
      type: object
      description: 'ASP.NET Web API validation error. `modelState` maps the offending

        field name (or `request`) to a list of human-readable messages.

        '
      properties:
        message:
          type: string
        modelState:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
      - message
    TimeSeriesDetail:
      allOf:
      - $ref: '#/components/schemas/TimeSeriesMeta'
      - type: object
        properties:
          details:
            type: array
            items:
              type: object
  responses:
    ServerError:
      description: 'Unexpected server-side error. The body is usually a plain-text message

        but its structure is not guaranteed — treat it as opaque diagnostic

        text. Common causes: database constraint violation, downstream

        service timeout, internal exception. Retry-safe for idempotent

        requests; for non-idempotent ones, verify state before retrying.

        '
      content:
        text/plain:
          schema:
            type: string
          example: An error has occurred.
    BadRequest:
      description: "The request was rejected. PlantPredict returns one of two shapes:\n\n* `application/json` with `{message, modelState}` for input\n  validation errors (ASP.NET Web API model-state). The `modelState`\n  map keys field names to lists of human-readable error messages.\n* `text/plain` with a free-form message for runtime / database\n  errors that bubble up before validation completes.\n\nClients should branch on the `Content-Type` header.\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ModelStateError'
          example:
            message: The request is invalid.
            modelState:
              latitude:
              - The field Latitude must be between -90 and 90.
        text/plain:
          schema:
            type: string
          example: A successfully completed prediction cannot be cancelled.
    NotFound:
      description: The referenced resource does not exist or is not accessible to the caller.
      content:
        text/plain:
          schema:
            type: string
          example: Project not found.
    Unauthorized:
      description: Missing or invalid bearer token. The response body is empty and no `Content-Type` header is set; the 401 status code is the only signal. Fetch a fresh token (see the **Authentication** section of the API description) and retry.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Pass `Authorization: Bearer <token>` on every request. See the **Authentication** section of the API description for how to fetch a token.'