Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wattshift.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

Authentication can be done in two different ways. Session tokens are useful for frontend calls, while API keys are useful for backend calls.
  1. API Key: Add your API key in the header x-ws-api-key
    -> { 'x-ws-api-key': '{apiKey}' }
  2. Session Token: Add the token in the header Authorization as: Bearer {sessionToken}
    -> { 'Authorization': 'Bearer {sessionToken}' }

​
How to Get a Session Token

Use this endpoint to get a session token (helpful for frontend calls): [POST] /v1/onboarding/session-token/generate 
// Response Body
{ "sessionToken": "your_session_token" }

​
Onboarding Flow

​
Steps to Onboard a Home

​
1. Fetch Utilities and Rate Plans

Fetch all utilities and rate plans for a given zip code. [POST] /v1/utility/get 
// Request
{ "zipcode": "95313" }

// Response
[
  {
    "utilityId": "14328",
    "utilityName": "Pacific Gas & Electric",
    "ratePlans": [
      {
        "id": "6915de3f881cbc6041e4c887",
        "rateID": "<semantic_rate_id_1>",
        "ratePlanName": "TOU-D"
      },
      {
        "id": "<rate_plan_id_2>",
        "rateID": "<semantic_rate_id_2>",
        "ratePlanName": "TOU-C"
      },
      {
        "id": "<rate_plan_id_3>",
        "rateID": "<semantic_rate_id_3>",
        "ratePlanName": "E-6"
      }
    ]
  }
]
Choose the matching entry from ratePlans, then use that plan’s ratePlans[].id value as ratePlanId when calling the home endpoints. The companion ratePlans[].rateID field is the semantic normalized tariff identifier for reference and troubleshooting.

​
2. Create a Home

Create Home with basic details, connecting to the utility, and select a rate plan. [POST] /v1/homes/create 
// Request
{
  "name": "Your Home Name",
  "zipcode": "95313",
  "utilityId": "14328",
  "ratePlanId": "<selected ratePlans[].id>",

  // Optional fields
  "hasEvCharger": true, // boolean | null | undefined
  "hasElectricHeater": false,
  "hasSmartWaterHeater": null,
  "hasElectricWaterHeater": true,
  "hasAC": true,
  "acType": "central", // central | window | split | other
}

// Response
{ "id": "ws_home_123456789" }
The response field is named id; use that value as the homeId in later requests.

​
3. Create Solar (if needed)

Provide details about Solar System. [POST] /v1/homes/solar/create 
// Request
{
  "homeId": "ws_home_123456789",
  "solarSystemSizeKw": 5,
  "isNonNetMetered": false
}

// Response
{ "homeId": "ws_home_123456789" }

​
4. Get Price Signal Data

See the Price Signal documentation for more details.