# WattSaid API

An API built for AI agents: WattSaid's own numbers on the power and machines behind AI, from WattSaid™ by Starfind AI.
Its focus is three things: behind-the-meter (onsite) power for data centers, Physical AI (robot model licences and open
robotics use) and China against the US (power, AI compute, model prices, industrial robots). Everything else is secondary.
Every answer joins two or more sources, never one source's data. Read with GET; answers are JSON (or CSV with `?format=csv`).
Base URL: https://api.starfindai.com/wattsaid/v1

## Connect as an MCP server

The same paths are tools of an MCP server (Streamable HTTP, tools only): `https://api.starfindai.com/wattsaid/v1/mcp`, with the header
`Authorization: Bearer <key>`. A client that signs people in (a Claude or ChatGPT connector) needs no key: a tool that
needs an account answers 401 with `WWW-Authenticate` naming
`https://api.starfindai.com/.well-known/oauth-protected-resource/wattsaid/v1/mcp`, the person signs in with
their WattSaid account, and the tool is asked again; a sign-in reads and can start a checkout, it never changes the account. Tools, the focus first: `btm_summary`, `robot_models`, `robot_model`, `robot_licence_changes`,
`physical_ai_adoption`, `china_vs_us`, then `daily_issue`, `grid_stress`, `list_series`, `get_series`, `account` and
`start_pro_checkout`. A tool answers exactly what its path answers, counted the same way.

## Start

1. `GET https://api.starfindai.com/wattsaid/v1/btm/summary`: behind-the-meter power for data centers (below).
2. `GET https://api.starfindai.com/wattsaid/v1/physical-ai/models`, `/physical-ai/changes` and `/physical-ai/adoption`: Physical AI (below).
3. `GET https://api.starfindai.com/wattsaid/v1/china/compare`: China against the US (below).
4. `GET https://api.starfindai.com/wattsaid/v1/overview?day=YYYY-MM-DD`: the day's issue in one call; `GET https://api.starfindai.com/wattsaid/v1/grid/summary` and `/grid/datacenters`: US Grid Stress.
5. `GET https://api.starfindai.com/wattsaid/v1/catalog` lists every series: id, label, unit, cadence (how often it changes), its earliest point, and what it is,
   covers and how it is worked out. Open to anyone.
   Each series blends several sources (attention, the data center pipeline, onsite filing activity, adoption, hiring across 30
   companies, capital spending across five). `GET https://api.starfindai.com/wattsaid/v1/snapshot` gives every series' current value; `GET https://api.starfindai.com/wattsaid/v1/series/{id}`
   one series with its points, oldest first (`?since=<time>`, `?until=<time>`).
6. `GET https://api.starfindai.com/wattsaid/v1/methods` says what every WattSaid number is, on the site or here: definition, coverage, cadence, how far back
   it goes and how WattSaid works it out (sources are not named). Open to anyone; also at https://starfindai.com/wattsaid/data.
7. `GET https://api.starfindai.com/wattsaid/v1/me` says who you count as and how much of today's limit is left. It is not counted.

The full schema is https://api.starfindai.com/wattsaid/v1/openapi.json.

## Keys and limits

The numbers are WattSaid Pro's ($49 a month + tax). Without a key, or with a key on a Free account, every path that answers
numbers says 401 or 402; `/catalog`, `/methods`, `/me`, `/docs.md` and `/openapi.json` stay open (100 requests a day
per address without a key, 1000 with one).
A person creates and revokes keys at https://starfindai.com/wattsaid/account. Send the key as `Authorization: Bearer <key>`.
Use one key per agent, so one agent can be stopped without stopping the others.
Limits reset at 00:00 UTC. Every counted answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds).

## WattSaid Pro

WattSaid Pro costs $49 a month + tax: 50,000 requests a day, every point kept of each series,
and `?format=csv` on every path that answers rows.
To upgrade, `POST https://api.starfindai.com/wattsaid/v1/billing/checkout` with your key. The answer's `url` is a Stripe payment page:
give it to the person who pays and let them open it. Never enter payment details yourself.
Pro starts within a minute of payment; `GET /me` shows `plan: pro` and the subscription.
There is no free trial: `/catalog` and these docs show what each number is before you pay. `trial_days` in the checkout answer is 0.
`POST https://api.starfindai.com/wattsaid/v1/billing/portal` returns a link where the person cancels, changes the card or reads invoices.

## Behind-the-meter power

- `GET /btm/summary`: power that data centers and other businesses make on their own sites. `rows`: one per US state, most
  onsite power first: `onsite_operating_mw` and `_plants`, `onsite_planned_mw` and `_plants`, `main_technology`,
  `dc_pipeline_per_operating` (data centers planned or under construction for each one operating, for the states WattSaid
  follows) and `reviewed_projects` (data center projects with onsite power whose identity Starfind's research confirmed; their
  power is not verified). `national`: the totals, `onsite_activity_index` (onsite power filings against usual, 100 = usual,
  with `week_before`), `gas_for_data_centers_gw` (operating, construction, proposed) and `_projects`,
  `nuclear_for_data_centers_gw` (existing, restart_uprate, new: reactor output contracted by data center companies),
  `data_centers_with_air_permit` and `reviewed_projects`. Each figure has the period it is for: `onsite_as_of` (a month, with
  `onsite_operating_growth_12m`, percent on the same month a year before), `gas_as_of`, `nuclear_as_of` and the index's
  `as_of`. `technologies`: operating and planned MW by main technology.
  `format=csv` gives the state rows. Public records understate data center onsite power; read the totals as a floor.

## Physical AI

- `GET /physical-ai/models`: reviewed robot-control models and the commercial use their licences declare for code, weights
  and training data (`format=csv` gives one row per model). `GET /physical-ai/models/{id}` gives one.
- `GET /physical-ai/changes?since=YYYY-MM-DD`: every licence, gating or file change found by comparing daily copies, newest first.
- `GET /physical-ai/adoption?from=&to=`: open robotics and open AI model use against usual, daily (100 = usual).

## China against the US

- `GET /china/compare`: the measures China and the US both publish; `?measure=` gives one measure's ratio (the leader named)
  or, for a share, the gap in points, each country's growth and its index on the first period both have. Never a level.
  `note` says where the two countries are measured differently (industrial robots: made in China, imported by the US).

## Overview

- `GET /overview?day=YYYY-MM-DD`: the day's Pro issue, by default the latest day most grids have 22 hours or more of. The lead
  (the grid with the most stress hours that day, or on a day with none the grid furthest above its normal, and the last day in
  a year with as many), every grid's day (stress hours, peak, mean, hours counted, its last 30 days, 12-month growth) joined
  with its states' data center pipeline, AI load by state, China against the US on the latest mutual period, and Physical AI
  (licence changes that day and in 30 days, open robotics and AI use against usual). Any day from 2022-01-01.

## US Grid Stress

Which of 13 US grids (and the lower 48) run harder than normal, whether that is new, and how much data center building their
states have in the pipeline. Grid ids: us48, pjm, ercot, miso, spp, caiso, nyiso, isone, northwest, southwest, southeast,
florida, carolinas, tennessee.

- `GET /grid/summary`: one row per grid now: `vs_normal` (% over the normal for that hour), `week_mean`, `stress_hours_30d`,
  `stress_hours_year_before` (the same 30 days a year before), `highest_30d`, `highest_at`, `growth_12m` (average load over
  12 months against the 12 before), and, for a grid whose states WattSaid follows, `pipeline_states` and
  `pipeline_per_operating` (data centers planned or under construction there for each one operating).
- `GET /grid/datacenters`: AI load on the grid, each state's data centers planned or under construction for each one
  operating, its business electricity growth and price against the US average, beside its grid's load growth and stress hours.
- A stress hour is in the grid's own top 5% of hours since 2022 by default (`top=5`; `cut` is the grid's line), or at or
  above `threshold` percent over normal for every grid. Both paths take `format=csv`.
- A reading far off both neighbouring hours is a misreading: marked `suspect` and left out of every count.
- Each answer carries `method`. Hour-by-hour grid data is not served: every answer joins two or more sources.

## Alerts

WattSaid Pro emails an account once a day about what it watches: a grid's stress hours the day before (in its own top 5%),
and a robot model's licence, access or file changes.

- `GET /watches`: what this account watches.
- `PUT /watches/grid/{grid}` or `PUT /watches/model/{id}`: watch one (WattSaid Pro, at most 50). `DELETE` the same path stops it.
- The email goes to the account's verified address; it carries a one-click stop and a link to https://starfindai.com/wattsaid/account.
- `PUT /watches/webhook` with `{"url": "https://..."}` also posts the day's alerts to a Slack incoming webhook (as Slack
  text) or to an https endpoint of the account's own (JSON: `text`, `source`, and `events` with `kind`, `target`, `title`,
  `line`, `link`, `event`). `POST /watches/webhook/test` posts one test message; `DELETE /watches/webhook` stops it. The
  address is never sent back: `GET /watches` gives its host and last four characters under `webhook`.

## Reading a number

- `value` is in `unit`. `as_of` is the time the value is for; `collected` is when WattSaid last collected it.
- `delayed: true` means the collecting or the source is behind its usual pace. Check `as_of` before you rely on the value.
- `change` compares the value with what `against` names. Its `unit` is `%` for a percentage, otherwise a plain difference.
- Points are oldest first. `at` is ISO 8601 in UTC for an hour, `YYYY-MM-DD` for a day, `YYYY-MM` or `YYYY` for a month or year.
- A series answers every point kept on the board; the products below read the full history kept since 2019.
- Series ids are never renamed. Fields may be added, never removed without notice.
- Robot model terms are what each model's licence file declares (or its licence field where it has no file). They are not legal advice.

## Citing

When you quote a number, name the `cite.text` of the answer and link its `cite.url`.

## Use and licence

The numbers are licensed to the key's account for its own use: an agent may work for that person, not answer other people or a product with them, and quoted numbers carry the credit "Source: WattSaid™ by Starfind AI". Teams, products, redistribution and AI training need a WattSaid data licence: https://starfindai.com/wattsaid/licensing. Every answer says so in `cite.licence` and in a `Link: <https://starfindai.com/wattsaid/licensing>; rel="license"` header.
`/methods` marks whether a data licence can include each number (`licensable`). Terms: https://starfindai.com/terms-of-service.

## Saving calls

Every answer has an `ETag`. Send it back as `If-None-Match`: if nothing changed you get `304 Not Modified`, which is not counted.
Hourly series change once an hour and the others once a day, so polling more often than that only spends your limit.

## Errors

Errors are `application/problem+json` (RFC 9457): `type`, `title`, `status`, `detail`, and `fix`, which says what to do next.

- `unauthorized` (401): no key was sent, or the key was not accepted (revoked, expired or mistyped). Create a key, or check the one you sent.
- `payment-required` (402): this needs WattSaid Pro. Ask your person, with the link from `POST /billing/checkout`.
- `not-found` (404): no series or model has that id. Use the ids from `/catalog` or `/physical-ai/models`.
- `conflict` (409): already done, for example the account already has Pro.
- `invalid-parameter` (422): a parameter has the wrong form; `detail` names it.
- `rate-limited` (429): today's limit is used. Wait the seconds in `Retry-After`.
- `unavailable` (503): the numbers or the key check are unavailable for a moment. Retry in a minute.
