# Getting started

# Getting started

You need two values from your Stationworks contact: your district's **id**
(a UUID) and a **key** (starts with `pk_live_`). The key identifies your
site; it grants nothing and is safe in page source. The district's console
will show both on its API card.

## One request

```text
GET https://api.stationworks.app/v1/permits/agencies/<id>/status?key=<key>
```

```js
const id = "00000000-0000-0000-0000-000000000000";
const key = "pk_live_yourKeyHere";
const res = await fetch(
  `https://api.stationworks.app/v1/permits/agencies/${id}/status?key=${key}`,
);
if (!res.ok) throw new Error(`status ${res.status}`);
const status = await res.json();
```

## Three fields

```js
document.querySelector("#verdict").textContent = status.verdict.label;
document.querySelector("#danger").textContent = status.fireDanger ?? "not set";
document.querySelector("#more").href = status.agency.url;
```

`verdict` answers "can I have a fire today?" for the whole district.
`fireDanger` is `null` when the district has not set a level. `agency.url`
is the district's own site, where the full rules live.

## What comes back

The response also carries `statuses` (one row per thing you might burn),
`permits` (what the district sells, with prices), `season`, `airQuality` and
`fireWeather`. The [reference](/api) documents every field. Two rules keep
your page working as the API grows: ignore fields you do not recognise, and
treat an enum value you do not recognise as "unknown". The
[contract](/contract) explains why.

## Responses you will see

| Status | Meaning                                              |
| ------ | ---------------------------------------------------- |
| `200`  | The district's status.                               |
| `401`  | No key, or a key we do not recognise. Check `?key=`. |
| `404`  | Not a UUID, or a district that is not active.        |
| `429`  | Too many requests. Wait for `Retry-After` seconds.   |
| `500`  | Our fault. Show your last good response.             |

Errors are JSON: `{ "error": { "code": "invalid_api_key", "message": "…" } }`.