Kilowatt Cost API — API Documentation

🔒 Authentication

POST /auth/signup Register a new account ▶

Creates a new user account and sends a verification code to the provided email address.

Request Body (JSON)

Field	Type	Description
`email`required	string	Valid email address
`password`required	string	Min 8 chars, uppercase, lowercase, number, special char

Example

curl -X POST "https://api.kwcost.com/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"MyP@ss123"}'

Response — 200

{
  "message": "Signup successful. Check your email for a verification code.",
  "user_confirmed": false
}

POST /auth/confirm Verify your email ▶

Confirms the account using the 6-digit code sent to your email.

Request Body (JSON)

Field	Type	Description
`email`required	string	Email used during signup
`code`required	string	6-digit verification code from email

Example

curl -X POST "https://api.kwcost.com/auth/confirm" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","code":"123456"}'

Response — 200

{
  "message": "Email confirmed. You can now log in."
}

POST /auth/login Get access token ▶

Authenticates with email and password, returns JWT tokens. The access_token should be passed as a Bearer token on all subsequent requests.

Request Body (JSON)

Field	Type	Description
`email`required	string	Registered email
`password`required	string	Account password

Example

curl -X POST "https://api.kwcost.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"MyP@ss123"}'

Response — 200

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJjdHkiOiJKV1QiLCJl..."
}

$ Rates

GET /rates List all jurisdictions & schedules ▶

Returns all available jurisdictions with their rate schedule names grouped by category.

Example

curl "https://api.kwcost.com/rates" \
  -H "Authorization: Bearer <token>"

Response — 200

{
  "metadata": { "source": "Duke Energy published tariffs", ... },
  "jurisdictions": {
    "DEC": {
      "name": "Duke Energy Carolinas",
      "states": ["NC", "SC"],
      "schedules": {
        "residential": { "RS": "Residential Service", ... },
        "business": { "SGS": "Small General Service", ... }
      }
    }
  }
}

GET /rates/{jurisdiction} All schedules for a jurisdiction ▶

Returns complete rate data for a specific jurisdiction including all categories and schedules.

Path Parameters

Parameter	Type	Description
`jurisdiction`required	string	Jurisdiction code: `DEC`, `DEP`, `DEI`, `DEF`, `DEO`, `DEK`

Example

curl "https://api.kwcost.com/rates/DEC" \
  -H "Authorization: Bearer <token>"

GET /rates/{jurisdiction}/{category} Schedules by category ▶

Returns rate schedules for a jurisdiction filtered by category (residential or business).

Path Parameters

Parameter	Type	Description
`jurisdiction`required	string	Jurisdiction code
`category`required	string	`residential` or `business`

Example

curl "https://api.kwcost.com/rates/DEC/residential" \
  -H "Authorization: Bearer <token>"

GET /rates/{jurisdiction}/{category}/{schedule} Full schedule details ▶

Returns the full details for a specific rate schedule including all charges, tiers, and the effective rate summary.

Path Parameters

Parameter	Type	Description
`jurisdiction`required	string	Jurisdiction code
`category`required	string	`residential` or `business`
`schedule`required	string	Schedule code: `RS`, `SGS`, `LGS`, `OPT-V`, etc.

Example

curl "https://api.kwcost.com/rates/DEC/residential/RS" \
  -H "Authorization: Bearer <token>"

Response — 200

{
  "jurisdiction": "DEC",
  "category": "residential",
  "schedule_code": "RS",
  "details": {
    "name": "Residential Service",
    "basic_facilities_charge_dollars": 14.00,
    "energy_charges_per_kwh": [
      { "tier": "all kWh", "rate": 0.117845 }
    ]
  },
  "effective_rate_summary": {
    "effective_rate_per_kwh": 0.117845,
    "note": "Excludes fixed monthly charges"
  }
}

GET /rates/{jurisdiction}/riders All riders (mandatory & optional) ▶

Lists all riders for a jurisdiction. Mandatory riders (Fuel Cost, Energy Efficiency, CPRE, DSM, BPM, etc.) are applied automatically by the calculator. Optional riders (RSC, NM, NMB) must be explicitly requested. Filter by category or schedule to see which riders apply to your rate.

Mandatory rider codes: FC (Fuel), EE (Energy Efficiency), EDPR (DSM/EE Program Rider), BPM (BPM Prospective), BPMTU (BPM True-Up), CPRE (Competitive Procurement), EDIT4 (Tax Reform), CAR (Cost Adjustment Rider), RDM (Revenue Decoupling), ESM (Earnings Sharing), PIM (Performance Incentive), NPTC (Nuclear Production Tax Credit).

Optional rider codes: RSC (Rider Solar Choice), NM (Net Metering — legacy, closed), NMB (Net Metering Bridge).

Path Parameters

Parameter	Type	Description
`jurisdiction`required	string	Jurisdiction code

Query Parameters

Parameter	Type	Description
`category`optional	string	Filter: `residential` or `business`
`schedule`optional	string	Filter by eligible schedule code

Example

curl "https://api.kwcost.com/rates/DEC/riders?category=residential" \
  -H "Authorization: Bearer <token>"

⏳ Time-of-Use

GET /tou/schedules List TOU schedule definitions ▶

Returns all available time-of-use schedule definitions with their seasons and holidays.

Example

curl "https://api.kwcost.com/tou/schedules" \
  -H "Authorization: Bearer <token>"

Response — 200

{
  "DEC_RESIDENTIAL_TOU": {
    "description": "Duke Energy Carolinas Residential TOU",
    "seasons": ["summer", "non_summer"],
    "holidays": ["2026-01-01", "2026-05-25", ...]
  },
  "DEC_BUSINESS_TOU": { ... }
}

GET /tou/now Current TOU period ▶

Returns the TOU period in effect right now for the given schedule, including the current rate.

Query Parameters

Parameter	Type	Description
`schedule`required	string	TOU schedule name, e.g. `DEC_BUSINESS_TOU`, `DEC_RESIDENTIAL_TOU`

Example

curl "https://api.kwcost.com/tou/now?schedule=DEC_RESIDENTIAL_TOU" \
  -H "Authorization: Bearer <token>"

Response — 200

{
  "schedule": "DEC_RESIDENTIAL_TOU",
  "datetime": "2026-07-15T14:30:00",
  "season": "summer",
  "period": "on_peak",
  "periods_info": { ... }
}

GET /tou/lookup Lookup period by date/time ▶

Look up the TOU period for any specific date/time combination. Useful for historical or future planning.

Query Parameters

Parameter	Type	Description
`schedule`required	string	TOU schedule name
`datetime`required	string	ISO 8601 datetime, e.g. `2026-07-15T14:30:00`

Example

curl "https://api.kwcost.com/tou/lookup?schedule=DEC_BUSINESS_TOU&datetime=2026-07-15T14:30:00" \
  -H "Authorization: Bearer <token>"

Response — 200

{
  "schedule": "DEC_BUSINESS_TOU",
  "datetime": "2026-07-15T14:30:00",
  "season": "summer",
  "period": "on_peak"
}

GET /tou/daily-profile 24-hour TOU profile ▶

Returns a full 24-hour TOU breakdown for a specific date. Shows which period applies for each hour — useful for planning when to run equipment or shift load.

Query Parameters

Parameter	Type	Description
`schedule`required	string	TOU schedule name
`date`required	string	Date in `YYYY-MM-DD` format

Example

curl "https://api.kwcost.com/tou/daily-profile?schedule=DEC_BUSINESS_TOU&date=2026-07-15" \
  -H "Authorization: Bearer <token>"

Response — 200

{
  "schedule": "DEC_BUSINESS_TOU",
  "date": "2026-07-15",
  "day_of_week": "Wednesday",
  "season": "summer",
  "summary": {
    "on_peak": "10 hours",
    "off_peak": "14 hours"
  },
  "hours": [
    { "hour": 0, "time": "00:00", "period": "off_peak" },
    ...
  ]
}

⚡ Calculator

POST /calculate/cost Full cost estimate ▶

Estimates total electricity cost for a billing period. Supports flat-rate, tiered, TOU, and demand-billed schedules. Automatically applies mandatory riders (fuel, EE, CPRE, etc.) unless excluded. Optional riders (RSC, NM, NMB) can be added for solar/generation customers.

Request Body (JSON)

Field	Type	Description
`jurisdiction`required	string	Jurisdiction code: `DEC`, `DEP`, etc.
`category`required	string	`residential` or `business`
`schedule`required	string	Rate schedule code
`total_kwh`optional	number	Total kWh consumed (flat-rate schedules). Default: 0
`usage_breakdown`optional	object	Per-period kWh for TOU: `on_peak_kwh`, `off_peak_kwh`, `super_off_peak_kwh`, `shoulder_kwh`
`demand_kw`optional	number	Peak demand in kW (demand-billed schedules). Default: 0
`on_peak_demand_kw`optional	number	On-peak demand in kW. Default: 0
`include_riders`optional	boolean	Include mandatory riders (fuel, EE, CPRE, etc.). Default: true
`exclude_riders`optional	string[]	Mandatory rider codes to exclude, e.g. `["EE"]`. See `GET /rates/{jur}/riders` for codes
`optional_riders`optional	string[]	Optional rider codes to add: `["RSC"]`, `["NM"]`, `["NMB"]`
`exported_kwh`optional	number	kWh exported to grid (for solar credit calculation). Default: 0
`nameplate_capacity_kw`optional	number	System nameplate capacity in kW (for RSC/NMB per-kW charges). Default: 0

Example — Simple Residential

curl -X POST "https://api.kwcost.com/calculate/cost" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction": "DEC",
    "category": "residential",
    "schedule": "RS",
    "total_kwh": 1000
  }'

Response — 200

{
  "jurisdiction": "DEC",
  "schedule": "RS",
  "total_kwh": 1000,
  "mandatory_riders_applied": ["FC", "EE", "EDPR", "BPM", ...],
  "mandatory_riders_excluded": [],
  "optional_riders_applied": [],
  "line_items": [
    { "item": "Basic Facilities Charge Dollars", "amount": 14.00 },
    { "item": "Energy charge (all kWh)", "rate_per_kwh": 0.117845, "kwh": 1000, "amount": 117.85 },
    { "item": "Rider FC: Fuel Cost", "rate_per_kwh": 0.02616, "kwh": 1000, "amount": 26.16 },
    "...more riders..."
  ],
  "total_estimated_cost": 136.80,
  "effective_cost_per_kwh": 0.13680
}

Example — TOU with Demand

curl -X POST "https://api.kwcost.com/calculate/cost" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction": "DEC",
    "category": "business",
    "schedule": "OPT-V",
    "usage_breakdown": {
      "on_peak_kwh": 20000,
      "off_peak_kwh": 50000,
      "super_off_peak_kwh": 10000
    },
    "demand_kw": 150,
    "on_peak_demand_kw": 120
  }'

POST /calculate/quick Quick cost estimate ▶

Simplified cost estimate — just provide jurisdiction, schedule, and kWh. Returns the estimated total without a full line-item breakdown.

Request Body (JSON)

Field	Type	Description
`jurisdiction`required	string	Jurisdiction code
`schedule`required	string	Rate schedule code
`kwh`required	number	Total kWh consumed

Example

curl -X POST "https://api.kwcost.com/calculate/quick" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jurisdiction":"DEC","schedule":"RS","kwh":1000}'

Response — 200

{
  "jurisdiction": "DEC",
  "schedule": "RS",
  "kwh": 1000,
  "estimated_cost": 131.85,
  "effective_rate": 0.13185
}

⚠ Error Responses

All errors follow a consistent format. Common HTTP status codes:

Status	Meaning
`400`	Bad request — invalid parameters or body
`401`	Unauthorized — missing or invalid Bearer token
`404`	Not found — invalid jurisdiction, category, or schedule
`409`	Conflict — account already exists (signup)
`422`	Validation error — request body failed schema validation

Error Format

{
  "detail": "Schedule 'XYZ' not found. Available: ['RS', 'RSTC', ...]"
}