# OpenAPI

> Where the machine-readable OpenAPI 3.1 document for /api/v1 lives, what it covers, and how to generate a typed client from it.

The OpenAPI document is generated from the same schemas the API parses requests and serializes responses with, so it can not drift from what the API does.

## Where it is

`GET /api/v1/openapi.json` returns an OpenAPI 3.1 document. It needs no key and is cached for a day.

```bash
curl 'https://opensnotel.com/api/v1/openapi.json'
```

## What it describes

Every endpoint under `/api/v1`: stations and one station, its latest conditions, observations over a range, its Snowpack Context and water year against its history, rankings, and the weather around it, the nearest stations to a point, the ski resort registry, and the registry's downloadable datasets. Query parameters, their defaults and bounds, and the shape of success and error bodies are all in it.

## Using it

Point a generator at the document to produce a typed client. The API is read-only and public, so the generated client needs no authentication.

## Versioning

The path carries the version. A change that could break a client, such as removing a field or changing its meaning, ships as a new version under a new path, and `/api/v1` keeps working. New optional fields and endpoints can appear in `/api/v1` without a version change, so clients should ignore fields they do not know.

## Next

- [Overview](https://opensnotel.com/docs/api.md): Use the REST API at /api/v1: every endpoint, the conventions all responses follow (UTC times, null for missing, the source's units and flags), request bounds and caching.

Canonical page: https://opensnotel.com/docs/reference/openapi
