Skip to content
TotalView API

Patch Project

PATCH
/api/v1/projects/{project_id}
 
curl --request PATCH \
  --url https://api.totalview.energy/api/v1/projects/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "project_name": "example", "portfolio_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "latitude": 1, "longitude": 1, "state": "example", "county": "example", "city": "example", "zip_code": "example", "timezone": "example", "project_nerc_code": "example", "eia_ba_code": "example", "cod_date": "2026-04-15T12:00:00Z", "decommision_date": "2026-04-15T12:00:00Z", "nameplate_capacity": 1, "poi_limit": 1, "project_additional_load": 0, "existing_project_flag": true, "sam_profile_flag": true, "tech_type_id": "example", "ppa_flag": true, "ppa_percentage": 1, "ppa_capacity": 1, "battery_flag": true, "battery_capacity_mwh": 1, "battery_duration_hours": 1, "battery_charge_rate_mw": 1, "battery_discharge_rate_mw": 1, "battery_round_trip_eff": 1, "battery_soc_min": 1, "battery_chemistry": "example", "battery_calendar_life_years": 1, "battery_cycle_life": 1, "battery_augmentation_flag": true, "battery_depth_of_discharge": 1, "gen_hour_profile_mw": [ { "timestamp": "2026-04-15T12:00:00Z", "value": 1, "source": "example" } ], "gen_aggregate_points": [ { "period_start": "2026-04-15", "period_end": "2026-04-15", "sum_mwh": 1, "granularity": "5min", "source": "example" } ], "auto_queue": true }'

Partially update a project’s config.

  • Only fields you include (non-None) are updated.
  • Both the typed ORM columns and the config_snapshot JSON blob are kept in sync so a subsequent /queue call sees the new values.
  • If any results-affecting field changes, status is set to "config_updated" and results_invalidated=true is returned — latest run is now stale.
  • Pass auto_queue=true to immediately enqueue a fresh model run.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
project_id
required
Project Id
string

Request Body required

Section titled “Request Body required ”
Media type application/json
ProjectPatch

Partial update schema for PATCH /projects/{project_id}. Only include fields you want to change.

object
project_name
Any of:
string
portfolio_id
Any of:
string format: uuid
latitude
Any of:
number
longitude
Any of:
number
state
Any of:
string
county
Any of:
string
city
Any of:
string
zip_code
Any of:
string
timezone
Any of:
string
project_nerc_code
Any of:
string
eia_ba_code
Any of:
string
cod_date
Any of:
string format: date-time
decommision_date
Any of:
string format: date-time
nameplate_capacity
Any of:
number
poi_limit
Any of:
number
project_additional_load
Any of:
number
existing_project_flag
Any of:
boolean
sam_profile_flag
Any of:
boolean
tech_type_id
Any of:
string
ppa_flag
Any of:
boolean
ppa_percentage
Any of:
number
ppa_capacity
Any of:
number
battery_flag
Any of:
boolean
battery_capacity_mwh
Any of:
number
battery_duration_hours
Any of:
number
battery_charge_rate_mw
Any of:
number
battery_discharge_rate_mw
Any of:
number
battery_round_trip_eff
Any of:
number
battery_soc_min
Any of:
number
battery_chemistry
Any of:
string
battery_calendar_life_years
Any of:
number
battery_cycle_life
Any of:
integer
battery_augmentation_flag
Any of:
boolean
battery_depth_of_discharge
Any of:
number
gen_hour_profile_mw
Any of:
Array<object>
HourlyGenEntry

Hourly generation profile entry.

The optional source field records the provenance of the value (e.g., "metered", "sam_modeled", "gap_filled_zero"). The engine surfaces the per-source hour-count in the run summary’s GenerationMetadata.profile_source_breakdown so reviewers can audit which fraction of the profile is metered vs. simulated. Source is opaque — any string is allowed.

object
timestamp
required
Timestamp
string format: date-time
value
required
Any of:
number
source
Any of:
string
gen_aggregate_points
Any of:
Array<object>
AggregateGenPoint

A metered generation total over a time window.

Used when a customer can’t provide a full hourly profile but does have aggregate totals (monthly settlement, daily SCADA export, annual operational report). The engine combines these with a SAM-generated 8760 shape — preserving the SAM diurnal/seasonal pattern within each window while rescaling so the window sum matches sum_mwh exactly.

source is a free-text provenance tag carried through to ISO 14040 disclosure (e.g., "settlement", "scada_export", "operational_report").

object
period_start
required
Period Start
string format: date
period_end
required
Period End
string format: date
sum_mwh
required
Sum Mwh
number
granularity
required
Granularity
string
Allowed values: 5min 15min hourly daily weekly monthly quarterly annual
source
Any of:
string
auto_queue
Any of:
boolean

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

Media type application/json
ProjectPatchOut

Response after patching a project.

object
project_id
required
Project Id
string format: uuid
config
required
Config
object
key
additional properties
any
queued_model_run_id
Any of:
string
config_version
Config Version

Current configuration version

integer
default: 1
results_invalidated
Results Invalidated

True if any patched field affects model results (latest run is now stale). Pass auto_queue=true to immediately re-run, or POST /queue when ready.

boolean
fields_changed
Fields Changed

Fields actually changed by this PATCH (only those whose value differed).

Array<string>
Example 
{
  "config_version": 1,
  "results_invalidated": false
}

422

Section titled “422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object
Example generated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}