# PodQ Air API

> PodQ Air is a real-time air-quality, weather, and location-monitoring service. This is the public REST API for building your own client/integration against the PodQ Air backend. Spec format: OpenAPI/Swagger 2.0. Base URL: https://api.podqair.com/v2 (HTTPS only).

If you are an AI agent or LLM: fetch the OpenAPI spec below. It is the complete, machine-readable description of every endpoint, parameter, request/response schema, and field — each operation has a written description. Read it instead of the rendered HTML reference page (that page is client-rendered and not useful to crawlers).

## API specification
- [OpenAPI spec (JSON)](https://podqair.com/api-docs/spec.json): The full public API. 18 tag groups, ~180 operations. This is the canonical source — parse this.

## Reference & docs
- [Interactive API reference](https://podqair.com/api-docs): Human-browsable reference rendered with Scalar (JavaScript-rendered).

## Authentication
- **Bearer (JWT)** — obtain a token via `POST /v2/auth/magic-link` or `/v2/auth/social-login`; the response includes a JWT access token and a refresh token. Send `Authorization: Bearer <token>` on every request. Refresh expired tokens at `POST /v2/auth/refresh`.
- **API key** — service-to-service via the `X-API-Key: <key>` header.
- A few endpoints (health probes, public sensor lookups) need no auth; everything else requires a valid token.
- Requests are rate limited — cache where you can and back off on `429`.

## Notes
- This spec documents the public API only. Admin and internal routes are intentionally excluded from the spec above.
- Tag groups: Authentication, OAuth2, Users, Devices, Settings, Locations, Location Profile, Sensors, Environmental, Environmental Bands, AirCare, Insights, Notifications, Internationalization, Utilities, Feedback, Webhooks, Health.