API Guide

Access your devices and profile programmatically using API tokens.

API tokens let you access your Power Cost Calculator data programmatically — pull your device list, read your rate config, automate cost tracking scripts.

Base URL: https://api.powerusage.app

Authentication

All /api/v1 endpoints require an API token passed in the X-API-Key header:

X-API-Key: pcalc_your_token_here

Tokens are created and managed at powerusage.app/api-tokens. Up to 10 tokens per account.

Rate Limit

60 requests/minute per token. Exceeding this returns HTTP 429 with a Retry-After header (seconds until the window resets) and body:

{ "error": "rate_limited", "retry_after": 42 }

Endpoints

GET /api/v1/me/devices

List all tracked devices for the authenticated user.

curl https://api.powerusage.app/api/v1/me/devices \
  -H "X-API-Key: pcalc_your_token_here"

Response: Array of device objects.

[
  {
    "id": "a1b2c3...",
    "name": "NAS",
    "catalog_device_slug": "synology-ds923",
    "watts": 30,
    "hours_per_day": 24,
    "schedule": [[0, 24]],
    "shiftable": false,
    "metadata": {},
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-03-01T08:22:00Z"
  }
]

Field	Description
`id`	Device UUID
`name`	User-assigned label
`catalog_device_slug`	Catalog entry slug, or `null` for custom devices
`watts`	Snapshot wattage at time of add
`hours_per_day`	Average daily runtime
`schedule`	Array of `[start_hour, end_hour]` tuples. Hours are 0–23; `end_hour` can exceed 24 for overnight windows (e.g. `[22, 30]` = 10 pm–6 am)
`shiftable`	Whether device supports TOU shift optimization
`metadata`	Freeform device metadata

GET /api/v1/me/profile

Get the authenticated user's rate configuration and location.

curl https://api.powerusage.app/api/v1/me/profile \
  -H "X-API-Key: pcalc_your_token_here"

Response:

{
  "region_code": "US-CA",
  "rate_config": null,
  "created_at": "2025-01-10T09:00:00Z"
}

Field	Description
`region_code`	Internal location identifier used to look up electricity rates
`rate_config`	Custom rate override (JSON), or `null` if using the default rate for your location
`created_at`	Account creation timestamp

Returns {} if no profile row exists yet.

Error Responses

Status	Body	Meaning
`401`	`{ "error": "invalid_api_key" }`	Token missing, invalid, or deleted
`429`	`{ "error": "rate_limited", "retry_after": N }`	Rate limit exceeded; wait `N` seconds

Example: cost script

Fetch all devices and compute a rough annual cost estimate using a flat rate:

Set TOKEN to your token and RATE to your electricity rate in $/kWh:

TOKEN="pcalc_your_token_here"
RATE=0.15

Then fetch your devices:

curl -s https://api.powerusage.app/api/v1/me/devices \
  -H "X-API-Key: $TOKEN" | jq -r '.[] | "\(.name): \(.watts)W x \(.hours_per_day)h/day"'