# OpenWeather for agents

> OpenWeather for agents · powered by The Bot Forum — OpenWeather's agent lane, operated and sold by Extreme Electronics Ltd, trading as The Bot Forum, a company under common ownership with OpenWeather (registered in England and Wales, no. 08247457).
> Machine root: https://agents.openweathermap.org/ (JSON); the bare https://openweathermap.org/agents/ is the human site.
> Stage-by-stage walkthrough, with a real request and answer per stage and the whole error dictionary: https://agents.openweathermap.org/guide (markdown twin: https://agents.openweathermap.org/guide.md). Read it once and you know the surface end to end, including the money wall.
> Terms of service: https://agents.openweathermap.org/tos — version 2026-09-09-1; signing up accepts the version served at that moment, and the 201 tells you which. Each version stays at https://agents.openweathermap.org/tos?version=<version>.
> API status: live. Platform API: https://agents.openweathermap.org/ — signup: POST https://agents.openweathermap.org/v1/accounts with one field, your email, and no header: the 201 carries two strings, shown once — the SECRET that runs your account here, and the DATA KEY that fetches data on https://data.openweathermap.org.
> The full API description this very host serves: https://agents.openweathermap.org/openapi.yaml (also https://agents.openweathermap.org/openapi.json) — the document that lists every route.
> The machine error dictionary — every code with its HTTP status and reaction: https://agents.openweathermap.org/errors.json.
> Data plane: https://data.openweathermap.org — route grammar there is GET /{product}/{route}, with NO /v1 prefix (e.g. https://data.openweathermap.org/onecall/current). Authorization: Bearer <data key>. No data response reports a cost or a balance: the balance is one call, GET https://data.openweathermap.org/account/balance with the same data key — it answers the credits you bought and, per product, the free credits you have left today. The secret fetches nothing there, and a data key runs nothing here: the wrong string answers 403 wrong_credential naming the right one.

## Sign up, verbatim

One field, no header. Nothing to look up first, nothing to invent: the platform mints both
strings and records the Terms version it serves.

    curl -s -X POST https://agents.openweathermap.org/v1/accounts \
      -H 'Content-Type: application/json' \
      -d '{"email": "you@example.com"}'

The 201: account{account_id, tier, tos_version, created_at} · secret (bfa_…, runs the account on
this host — store it where account credentials live) · data_key{key_id, key (bf_live_…), created_at}
(fetches data on https://data.openweathermap.org — store it where your data calls read it). Both strings are shown exactly
once. The account starts with no bought credits: what you can call at once is each product's own
free credits, described under Paying below. If the 201 never reached you, do not sign up again: the
account exists, and your owner recovers it at https://console.forum.bot/ by mail, where a new secret is minted.

## Platform routes

- Accounts: POST https://agents.openweathermap.org/v1/accounts — signup; the only route under /v1/accounts.
- Self: GET https://agents.openweathermap.org/v1/account · GET https://agents.openweathermap.org/v1/account/usage · POST https://agents.openweathermap.org/v1/account/topup · POST https://agents.openweathermap.org/v1/account/verify · POST https://agents.openweathermap.org/v1/account/secret (replace the secret; the old one dies first) — your SECRET in Authorization, never a data key. The two payment POSTs take no header: one open page per account and per kind, and asking again returns it.
- Keys: GET https://agents.openweathermap.org/v1/keys · POST https://agents.openweathermap.org/v1/keys · DELETE https://agents.openweathermap.org/v1/keys/{id} · POST https://agents.openweathermap.org/v1/keys/{id}/rotate — under your secret; data keys live under /v1/keys, NOT /v1/account/keys. A data key carries no scopes: every key of the account reaches the same products, and those are the products the account can pay for right now — a product whose free credits for today are not yet spent, or any product at all while the account holds bought credits. POST /v1/keys takes an optional name only and answers key_id + key, the string shown once. The secret has no id and no name, and no route lists it.
- Discovery, no auth: GET https://agents.openweathermap.org/ · GET https://agents.openweathermap.org/v1/products · GET https://agents.openweathermap.org/v1/status · GET https://agents.openweathermap.org/tos (+ ?version=) · https://agents.openweathermap.org/openapi.yaml · https://agents.openweathermap.org/errors.json · https://agents.openweathermap.org/llms.txt.
- Your balance: GET https://agents.openweathermap.org/v1/account/usage or GET https://agents.openweathermap.org/v1/account/balance (your secret), any time; on the data plane, GET https://data.openweathermap.org/account/balance with your data key — the one route there that takes a data key and is not data. The balance route answers two figures: remaining_credits, the credits you bought, and product_credits, a slug-to-credits map of the free credits each product has left for you today. The usage view reports the bought balance alone. No response header carries a balance.

## Products

- onecall: One Call weather data — active, proxied; routes: current, timeline/1min, timeline/15min, timeline/1h, timeline/1day; licence ODbL-1.0 (OpenWeather).
- onecall3: One Call 3.0 weather data — active, proxied; routes: forecast, timemachine, day_summary, overview; licence ODbL-1.0 (OpenWeather).
- Free credits belong to a product, not to the account: https://agents.openweathermap.org/v1/products carries each product's credit_account block. One Call 4.0 — the onecall product — gives every account 1,000 credits a day; One Call 3.0 gives none.

## Over MCP

- MCP endpoint: https://mcp.openweathermap.org/mcp — streamable HTTP, plain JSON answers, stateless.
  Six tools: list_products, get_product, sign_up (no key); account_status, get_topup_link,
  fetch_data. fetch_data uses your DATA KEY as Authorization: Bearer <data key> in the client
  configuration, or as the data_key argument right after sign_up; account_status and
  get_topup_link take your SECRET as the secret argument. The same public calls, the same
  walls, the same envelope; no tool pays. Server card: https://mcp.openweathermap.org/mcp/server-card

## Paying

- Credits are the unit of account: 1 credit = $0.001. Prices in credits, and the free credits each product gives: https://agents.openweathermap.org/v1/products — the quoted price is the charged price.
- One Call 4.0 gives every account 1,000 credits a day, replaced each night: whatever is unspent at midnight UTC is discarded, and the new day starts at 1,000 again. No card, no verification, no human step. Other feeds are paid from the first call — One Call 3.0 gives no free credits, so an account that has bought nothing cannot call it at all.
- A product's credits pay for that product and nothing else, and the platform spends them before the credits you bought. Bought credits pay for any product.
- Nothing is ever served on credit, and the data plane has two walls. A key the platform does not authorize at all — unknown, revoked, expired, blocked, or its account suspended — answers 401 invalid_key with action_url, the account page: a data server holds the key list and cannot tell those reasons apart, only the platform host can. A key that IS authorized but is not funded for the product it asked for answers 402 payment_required with next_action top_up and the payment page in action_url — top up, or call a product this key is still funded for.
- No response carries a cost or a balance. Read the balance yourself (above) and top up before you reach zero: the wall gives no warning.
- To top up: POST https://agents.openweathermap.org/v1/account/topup {"amount_minor": <cents>, "currency": "USD"} with your secret; no header. Minimum 1000 (=$10), USD only. Asking again while the page is open returns the same page. It answers with a one-time provider page for a HUMAN to pay on; an agent may open the payment but never completes it. Card details never touch the Forum. The payment page and the receipt are in The Bot Forum's name: OpenWeather for agents is operated and sold by Extreme Electronics Ltd, trading as The Bot Forum, a company under common ownership with OpenWeather.
- Every money wall also carries action_url — the stable page to send that human to: https://console.forum.bot/. It never expires and never changes.
- Credits land about 15 seconds after the payment completes. Poll https://agents.openweathermap.org/v1/account/usage; never open a second payment because the first has not landed. The SAME data key then serves again once the data servers pull the next key list — under seven minutes at the platform's defaults; nothing is reissued. A product's fresh credits at midnight UTC reach your key by the same route and on the same clock.

## Not on this surface

- No per-intent payment-status route: after a top-up, poll https://agents.openweathermap.org/v1/account/usage until bought credits rise.
- No budget, allowance or trial endpoints, and no spending caps anywhere — budget_cap_reached is a reserved code nothing raises. Free credits are not a route either: they belong to a product, https://agents.openweathermap.org/v1/products publishes what each product gives, and GET https://agents.openweathermap.org/v1/account/balance says what is left today.
- No batch query parameters: unknown params are ignored, and one call = one charge.

## Rules of conduct

- Every error carries a code and, where a next step exists, a machine-readable next_action.
- Only 2xx data responses are billed; upstream failures are never charged.
- No credential ever appears in a URL. The secret and the data keys are opaque bearers in the Authorization header; you never generate or parse one — the platform mints them.