# The Bot Forum

> A fast, transparent path from an agent needing data to receiving and controlling it.

## From needing data to using it. One smooth agent-led flow.

Give an agent one address. It discovers available data, activates access, receives a key and starts using live weather data. Cost stays visible, the account's one budget bounds every call, and the owner joins only when financial authority must change.

## Available data

### One Call weather data

- **Delivery:** Proxied through the Forum gateway
- **Agent access:** Bearer key
- **Consumption:** Successful responses only
- **Data licence:** ODbL-1.0; attribution required

One real feed, presented with the rules an owner and an agent both need to understand. [Browse the data catalogue](/data) · [Read the product page](/data/onecall) · [Machine catalogue](https://api.forum.bot/v1/products).

## The agent handles the ordinary path

The Forum turns discovery, activation, access, data and cost awareness into one continuous flow. The owner appears only when new financial authority is required.

1. **Discover data.** Begin at the public machine surface and find the available feed, terms and usage contract.
2. **Activate access.** Create an account with the accepted terms version.
3. **Receive a key.** Get one immediately usable credential.
4. **Receive data.** Call the feed and begin ordinary operation.
5. **Understand spending.** Ask for the balance whenever it matters — one call, with the same data key.
6. **Stay inside budget.** Continue autonomously inside the available line.
7. **Request owner authority.** Forward a clear funding or budget-change checkpoint only when more authority is needed.

## The balance is a call, not a header

~~~http
GET https://data.forum.bot/account/balance
Authorization: Bearer <data key>

{ "account_id": "acc_…", "remaining_credits": 739, "as_of": "2026-09-07T10:04:31Z" }
~~~

No response header reports a cost or a balance: a data server holds the list of keys it may serve and nothing else. An agent that wants the number asks for it, with the key it already has.

## A wall tells the agent what to do next

| Wall | HTTP | Correct move |
|---|---:|---|
| `invalid_key` | 401 | Don't retry; check the account at the address in action_url. On the data plane this is the one refusal for a key a data server cannot serve — a spent balance is the usual reason — and a human clears it there. |
| `upstream_error` | 502 | Retry with backoff; the call was not charged. |
| `key_revoked` | 401 | Stop and escalate as a possible incident. The platform host only: a data call answers invalid_key. |
| `rate_limited` | 429 | Wait for the supplied retry interval, then resume. |

[Read the human recovery guide](/errors) or [open the machine-readable dictionary](/errors.json).

## A transparent funding handoff

When funding or a larger budget is required, the agent receives a structured checkpoint it can explain and forward. The owner reviews and approves the financial decision once. Ordinary operation then returns to the agent.

## When direct access is the better choice

If one agent can stay inside a supplier's direct free allowance, use the supplier directly. It is cheaper.

The Forum earns its place when multiple agents need separate credentials, boundaries, spending evidence and independent revocation.

**Direct is cheaper in dollars and more expensive in blast radius** — the reach of one leaked or runaway credential.

## One service, two reading modes

Humans get explanation and context. Agents get deterministic routes, versioned terms and closed dictionaries. Both surfaces describe the same service.

## Machine resources

- [Agent quickstart](/llms.txt)
- [Machine manifest](/index.json)
- [Platform contract](https://api.forum.bot/openapi.json)
- [Current terms](/tos)