NvGrid API Specification#

The NvGrid gRPC API provides methods for scheduling power constraints, querying power status, and receiving power event notifications. This specification details all available endpoints, message types, and data structures.

Service Definition#

service NvGrid {
  rpc SetLoadTarget(LoadTargetRequest) returns (LoadTargetResponse);
  rpc GetLoadSchedule(GetLoadScheduleRequest) returns (LoadSchedule);
  rpc GetCurrentLoadTarget(google.protobuf.Empty) returns(GetCurrentLoadTargetResponse);
  rpc GetMetadata(google.protobuf.Empty) returns (FeedMetadata);
  rpc RegisterWebhook(RegisterWebhookRequest) returns (LoadTargetResponse);
  rpc UnregisterWebhook(UnregisterWebhookRequest) returns (LoadTargetResponse);
  rpc GetStatus(google.protobuf.Empty) returns (LoadTargetStatus);
}

Enums#

StatusCode#

Status codes indicate success or failure of API operations.

enum StatusCode {
  STATUS_CODE_UNSPECIFIED = 0;
  STATUS_CODE_SUCCESS = 1;
  STATUS_CODE_ERROR = 2;
}

Values:

  • STATUS_CODE_UNSPECIFIED - Status code was not set

  • STATUS_CODE_SUCCESS - Operation completed successfully

  • STATUS_CODE_ERROR - Operation encountered an error

PowerEvent#

Power events are used in webhook registration and webhook notifications.

enum PowerEvent {
  POWER_EVENT_UNSPECIFIED = 0;
  POWER_EVENT_START_RAMP_UP = 1;
  POWER_EVENT_END_RAMP_UP = 2;
  POWER_EVENT_START_RAMP_DOWN = 3;
  POWER_EVENT_END_RAMP_DOWN = 4;
}

Values:

  • POWER_EVENT_UNSPECIFIED - Subscribe to all events when used with RegisterWebhook

  • POWER_EVENT_START_RAMP_UP - Scheduled LoadTarget ramp up event has started

  • POWER_EVENT_END_RAMP_UP - Scheduled LoadTarget ramp up event has completed

  • POWER_EVENT_START_RAMP_DOWN - Scheduled LoadTarget ramp down event has started

  • POWER_EVENT_END_RAMP_DOWN - Scheduled LoadTarget ramp down event has completed

Unit#

Units of measurement for power values.

enum Unit {
  UNIT_UNSPECIFIED = 0;
  UNIT_WATT = 1;
  UNIT_KILOWATT = 2;
  UNIT_MEGAWATT = 3;
}

Values:

  • UNIT_UNSPECIFIED - Unit not specified

  • UNIT_WATT - Power measured in watts

  • UNIT_KILOWATT - Power measured in kilowatts

  • UNIT_MEGAWATT - Power measured in megawatts

RPC Methods#

SetLoadTarget#

Schedule power constraint changes with specified start and end times.

Request: LoadTargetRequest Response: LoadTargetResponse

Updates the future load target schedule using the provided list of LoadTarget objects. Each LoadTarget defines starting time, optional ending time, and target load. Setting target load to null resets to datacenter default. For overlapping time intervals, the most recently scheduled LoadTarget becomes effective.

Use cases:

  • Schedule power reductions for demand response events

  • Set power constraints based on utility curtailment signals

  • Define power limits for planned maintenance windows

GetLoadSchedule#

Retrieve scheduled load targets for a specified time interval and feeds.

Request: GetLoadScheduleRequest Response: LoadSchedule

Returns load schedules for specified power feeds within a given time interval. The schedule includes the LoadTarget active at the interval start and all future LoadTargets scheduled before the interval end.

Use cases:

  • Query upcoming power constraint schedule

  • Verify scheduled load targets

  • Audit power constraint history

GetCurrentLoadTarget#

Query the currently active load target for each power feed.

Request: google.protobuf.Empty Response: GetCurrentLoadTargetResponse

Returns the current load target for all configured power feeds, including target values, feed tags, and correlation identifiers.

Use cases:

  • Check current power constraints

  • Verify active load targets

  • Monitor current constraint status

GetMetadata#

Discover feed configurations, power thresholds, and default constraints.

Request: google.protobuf.Empty Response: FeedMetadata

Returns metadata for all configured power feeds, including minimum/maximum power thresholds and default constraints. Use this API to discover available feeds and their operational limits.

Use cases:

  • Discover available power feeds

  • Query power threshold limits

  • Determine default power constraints

RegisterWebhook#

Subscribe to power event notifications via HTTP webhook.

Request: RegisterWebhookRequest Response: LoadTargetResponse

Registers a webhook URL to receive notifications for specified power events. The webhook receives HTTP POST requests with event payloads when power state changes occur.

URL Whitelisting:

For security, DPS validates webhook URLs against a configured whitelist. RegisterWebhook will reject non-whitelisted URLs with error STATUS_CODE_ERROR and diagnostic message “webhook URL not whitelisted”.

Whitelist configuration supports:

  • Exact URL matches

  • Path prefix matching (e.g., https://example.com/api/ matches https://example.com/api/webhooks/nvgrid)

  • Query parameter validation

  • Scheme, hostname, and port enforcement

Configure the webhook whitelist in server configuration. See Prerequisites for detailed configuration instructions.

Use cases:

  • Receive notifications of power ramp events

  • Track in real-time

  • Integrate with external monitoring systems

UnregisterWebhook#

Unsubscribe from power event notifications.

Request: UnregisterWebhookRequest Response: LoadTargetResponse

Removes a previously registered webhook URL from power event notifications.

Use cases:

  • Clean up webhook subscriptions

  • Stop receiving event notifications

  • Decommission integration endpoints

GetStatus#

Query current power status including targets, calculated loads, and in-flight transitions.

Request: google.protobuf.Empty Response: LoadTargetStatus

Returns comprehensive status for all power feeds, including current targets, calculated loads, target achievement status, and whether power transitions are in progress.

Use cases:

  • Monitor current power consumption

  • Check target achievement status

  • Track power transition progress

Message Types#

LoadTargetRequest#

Request message containing one or more load targets to schedule.

message LoadTargetRequest {
  repeated LoadTarget targets = 1;
}

Fields:

  • targets - List of LoadTarget objects to schedule

LoadTarget#

Defines a time-based power constraint with strategy and feed assignments.

message LoadTarget {
  Interval interval = 1;
  LoadValue load_constraint = 2;
  LoadTargetStrategy load_target_strategy = 3;
  repeated string feed_tags = 4;
  string correlation_id = 5;
}

Fields:

  • interval - Start and end times for the constraint

  • load_constraint - Target power limit (null removes constraint)

  • load_target_strategy - Strategy for achieving target

  • feed_tags - Power feeds to apply constraint (empty = all feeds)

  • correlation_id - Unique identifier for tracking (auto-generated if omitted, max 36 bytes)

LoadTargetResponse#

Response indicating success or failure with diagnostic information.

message LoadTargetResponse {
  message Detail {
    StatusCode code = 1;
    google.protobuf.Any details = 2;
    string correlation_id = 3;
  }

  StatusCode code = 1;
  string diag_msg = 2;
  repeated Detail details = 3;
}

Fields:

  • code - Overall response status (refer to the StatusCode enum)

  • diag_msg - Diagnostic message describing the failure

  • details - List of detailed status messages per target

Detail Fields:

  • code - Status code for this specific target

  • details - Additional error details

  • correlation_id - If the request is a load target request, the correlation IDs of the requests in the same order as the requests. If correlation IDs are not specified in the request, this will return the generated UUIDs for each request.

LoadTargetStrategy#

Specifies the strategy for achieving power targets.

message LoadTargetStrategy {
  oneof strategy {
    bool best_effort = 1;
  }
}

Strategies:

best_effort - If power constraints require shedding load, DPS will reduce power from DPM-enabled jobs until the constraint is satisfied. If the constraint cannot be satisfied, DPS will reduce as much power as possible, but may not achieve the target until jobs terminate.

Interval#

Time interval with optional start and end times.

message Interval {
  google.protobuf.Timestamp start_time = 1;
  google.protobuf.Timestamp end_time = 2;
}

Fields:

  • start_time - Interval start (omitted = current time)

  • end_time - Interval end (omitted = indefinite duration)

LoadValue#

Power value with unit specification.

message LoadValue {
  double value = 1;
  Unit unit = 2;
}

Fields:

  • value - Numeric power value

  • unit - Power unit (refer to the Unit enum). This must be explicitly set.

GetLoadScheduleRequest#

Request to query load schedule for specific feeds and time interval.

message GetLoadScheduleRequest {
  repeated string feed_tags = 1;
  Interval interval = 2;
}

Fields:

  • feed_tags - Feed tags to query (empty = all feeds)

  • interval - Time interval for schedule query

LoadSchedule#

Ordered list of scheduled load targets.

message LoadSchedule {
  repeated LoadTarget targets = 1;
}

Fields:

  • targets - Chronologically ordered LoadTarget objects

GetCurrentLoadTargetResponse#

Current load target for each feed.

message GetCurrentLoadTargetResponse {
  map<string, LoadTarget> load_targets = 1;
}

Fields:

  • load_targets - Map of feed tag to current LoadTarget

FeedMetadata#

Metadata for all configured power feeds.

message FeedMetadata {
  message Entry {
    string feed_tag = 1;
    LoadValue power_minimum = 2;
    LoadValue power_maximum = 3;
    LoadValue default_constraint = 4;
  }

  map<string, Entry> metadata = 1;
}

Fields:

  • metadata - Map of feed tag to metadata entry

Entry fields:

  • feed_tag - Feed identifier

  • power_minimum - Minimum allowable power cap

  • power_maximum - Maximum allowable power cap

  • default_constraint - Default topology power constraint

RegisterWebhookRequest#

Request to register webhook for power event notifications.

message RegisterWebhookRequest {
  repeated PowerEvent for_events = 1;
  string url = 2;
}

Fields:

  • for_events - List of events to subscribe to (refer to the PowerEvent enum). If unspecified, subscribes to all power events.

  • url - URL to register for notifications

UnregisterWebhookRequest#

Request to unregister webhook.

message UnregisterWebhookRequest {
  string url = 1;
}

Fields:

  • url - Webhook URL to unregister

LoadTargetStatus#

Current system status including targets and calculated loads.

message LoadTargetStatus {
  message FeedStatus {
    LoadValue current_load_target = 1;
    LoadValue current_calculated_load = 2;
    bool in_flight = 3;
    google.protobuf.Timestamp power_event_start_time = 4;
    string correlation_id = 5;
  }

  map<string, FeedStatus> statuses = 1;
}

Fields:

  • statuses - Map of feed tag to feed status

FeedStatus fields:

  • current_load_target - Active power target from LoadTarget

  • current_calculated_load - Calculated load by DPS (may differ from target and actual)

  • in_flight - Power transition in progress

  • power_event_start_time - Scheduled start time of current power event

  • correlation_id - Correlation ID of active load target

Webhook Payload#

Power event webhooks receive HTTP POST requests with JSON payloads:

{
  "event": "start_ramp_down",
  "start_time": "2025-01-24T17:00:00Z",
  "end_time": "2025-01-24T18:00:00Z",
  "strategy": "best_effort",
  "target_load": {
    "value": 6.5,
    "unit": "mw"
  },
  "prev_target_load": {
    "value": 10.0,
    "unit": "mw"
  },
  "calculated_load": {
    "value": 9.2,
    "unit": "mw"
  },
  "compliant": false,
  "correlation_id": "curtailment-20250101-170000"
}

Payload fields:

  • event - Event type (start_ramp_up, end_ramp_up, start_ramp_down, end_ramp_down)

  • start_time - LoadTarget scheduled start time

  • end_time - LoadTarget scheduled end time (may be omitted)

  • strategy - Strategy used to achieve target

  • target_load - Target power constraint

  • prev_target_load - Previous target before this change

  • calculated_load - Current calculated load

  • compliant - Whether calculated load meets target (calculated_load ≤ target_load). If true, the target was met. If false, the requested LoadTarget could not be met.

  • correlation_id - Correlation ID from LoadTarget

API Usage Patterns#

Schedule Constraint Pattern#

1. GetMetadata() - Discover feeds and limits
2. Calculate target based on grid signal
3. SetLoadTarget() - Schedule constraint
4. GetLoadSchedule() - Verify schedule

Webhook Integration Pattern#

1. RegisterWebhook() - Subscribe to events
2. Receive START_RAMP_DOWN event
3. Track power reduction progress
4. Receive END_RAMP_DOWN event
5. Verify target achievement status
6. UnregisterWebhook() - Optionally, clean up when done

Monitoring Pattern#

1. GetCurrentLoadTarget() - Check active constraints
2. GetStatus() - Query current power state
3. Compare target vs calculated load
4. Verify target achievement

Error Handling#

API methods return LoadTargetResponse with status codes:

  • STATUS_CODE_SUCCESS - Operation completed successfully

  • STATUS_CODE_ERROR - Operation failed (refer to diag_msg for details)

Check the details field for per-target status information when scheduling multiple load targets.

Protocol Buffer Definition#

The complete API specification is defined in:

api/v1/nvgrid.proto

Generate client code using protocol buffer compiler:

# Python
python3 -m grpc_tools.protoc \
  -I./api/v1 \
  --python_out=./generated \
  --grpc_python_out=./generated \
  ./api/v1/nvgrid.proto

# Go
protoc --go_out=. --go-grpc_out=. api/v1/nvgrid.proto