Developer Platform

Bair1 Developer
Platform

Build with air quality data. Access real-time sensor readings, historical analytics, and export tools through our REST API, GraphQL, CLI, and MCP integrations.

Quick Start API Reference

Quick Start

Get up and running in seconds. The latest reading endpoint is public. Device registry, export, and write endpoints require a Bair1 API key.

Get the latest reading

curl https://www.bair1.live/api/readings/latest

List registered devices

curl https://www.bair1.live/api/v1/devices \
  -H "Authorization: Bearer $BAIR1_API_KEY"

Use the JavaScript SDK

npm install @heysalad/bair1

import { Bair1Client } from "@heysalad/bair1";

const bair1 = new Bair1Client({ apiKey: process.env.BAIR1_API_KEY });
const latest = await bair1.latest();

REST API

All endpoints return JSON. Use an API key for device registry, exports, and writes. Pass it via the Authorization header or the x-api-key header.

GET/api/v1/devices

List all registered sensors with their metadata and status.

GET/api/v1/devices/:id/readings

Retrieve historical readings for a specific device.

Params: ?limit, ?from, ?to

GET/api/v1/devices/:id/analytics

Get aggregated statistics and analytics for a device.

GET/api/v1/export

Export readings in CSV or JSON format.

Params: ?format, ?device, ?from, ?to

GET/api/readings/latest

Get the most recent reading across all devices.

POST/api/readings

Submit a new sensor reading. Requires API key authentication.

Example: Get readings with filters

curl "https://www.bair1.live/api/v1/devices/XIAO-SPS30-5EAA7A/readings?limit=10&from=2026-01-01" \
  -H "Authorization: Bearer $BAIR1_API_KEY"

GraphQL

For more flexible queries, use the GraphQL endpoint at /api/graphql. Supports introspection.

Example query

curl -X POST https://www.bair1.live/api/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{
      registeredDevices {
        deviceId
        name
        latestReading {
          pm25
          pm10
          timestamp
        }
      }
    }"
  }'

MCP Server

Connect Bair1 to AI agents like Claude Desktop or Claude Code using the Model Context Protocol. Add the following to your MCP configuration:

Claude Desktop / Claude Code — MCP config

{
  "mcpServers": {
    "bair1": {
      "command": "npx",
      "args": ["-y", "@heysalad/bair1-mcp"],
      "env": {
        "BAIR1_API_KEY": "your-api-key"
      }
    }
  }
}

Once connected, your AI agent can query air quality data, list devices, and analyze trends through natural language.

CLI

A command-line interface for quick access to Bair1 data from your terminal.

Install

npm install -g @heysalad/bair1

Usage

# Save your API key for authenticated endpoints
bair1 config set-key "$BAIR1_API_KEY"

# Get the latest reading
bair1 latest

# List all devices
bair1 devices

# Export data as CSV
bair1 export --device XIAO-SPS30-5EAA7A --format csv

Agent Guides

Agent tools can query Bair1 through MCP, the JavaScript SDK, or the REST API. MCP is the best default for coding agents because it exposes Bair1 as named tools instead of requiring custom glue code.

Codex

Use the MCP server when the environment supports MCP tools, or import the SDK in local scripts.

# MCP command
npx -y @heysalad/bair1-mcp

# SDK command
npm install @heysalad/bair1

Claude Code

claude mcp add bair1 \
  -e BAIR1_API_KEY=$BAIR1_API_KEY \
  npx -y @heysalad/bair1-mcp

Cursor

Add the Bair1 MCP server to your MCP configuration and keep the API key in the environment.

{
  "mcpServers": {
    "bair1": {
      "command": "npx",
      "args": ["-y", "@heysalad/bair1-mcp"]
    }
  }
}

Antigravity

Use the same stdio MCP command if your workspace supports custom MCP servers.

BAIR1_API_KEY=your-api-key \
  npx -y @heysalad/bair1-mcp

Firmware

Bair1 firmware can post sensor readings directly to the API or to a relay when the network path needs TLS or cellular handling.

Reading upload

POST https://www.bair1.live/api/readings
Authorization: Bearer $BAIR1_API_KEY
Content-Type: application/json

{
  "deviceId": "YOUR_DEVICE_ID",
  "deviceName": "Bair1 Sensor",
  "family": "bair1",
  "pm25": 8.4,
  "pm10": 13.2,
  "aqi": 34,
  "transport": "wifi"
}

Cellular relay target

# For SIM800L or cellular paths, send to the relay
POST https://sensor.heysalad.app/api/readings

# The relay forwards to:
https://www.bair1.live/api/readings

SDKs

Python SDK

pip install bair1

Coming Soon

JavaScript SDK

npm install @heysalad/bair1

Ready to publish

Questions? Reach out at developers@bair1.live

Bair1 DeveloperPlatform