{ "openapi": "3.1.0", "info": { "title": "Rainplover API", "version": "0.1.0", "description": "Weather, alerts and earthquakes for AI agents. One account works on every agent-first site run by API Evangelist.", "contact": { "email": "info@apievangelist.com" }, "license": { "name": "Apache-2.0" } }, "servers": [ { "url": "https://rainplover.com" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key from POST /v1/accounts (shown once)." } } }, "security": [ { "apiKey": [] } ], "paths": { "/v1/forecast": { "get": { "operationId": "get_forecast", "summary": "Weather forecast", "description": "Hourly and daily forecast for anywhere on Earth (MET Norway, CC BY 4.0): temperature, wind, precipitation, cloud, a weather symbol. Give lat/lon or a place name. Show the attribution when you present it.", "parameters": [ { "name": "lat", "in": "query", "required": false, "schema": { "type": "number", "description": "Latitude, decimal degrees" } }, { "name": "lon", "in": "query", "required": false, "schema": { "type": "number", "description": "Longitude, decimal degrees" } }, { "name": "place", "in": "query", "required": false, "schema": { "type": "string", "description": "Or a place name, e.g. \"Bergen\" or \"Springfield, IL\"" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "description": "Hourly steps to return, 1-72 (default 24)" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "Without an API key: x402 payment requirements (PAYMENT-REQUIRED header). With one: the owner must act, see account_url" }, "404": { "description": "Not found" } } } }, "/v1/alerts": { "get": { "operationId": "get_alerts", "summary": "Active weather alerts (US)", "description": "Active warnings, watches and advisories at a point in the United States (National Weather Service). Outside the US returns covered:false.", "parameters": [ { "name": "lat", "in": "query", "required": false, "schema": { "type": "number", "description": "Latitude, decimal degrees" } }, { "name": "lon", "in": "query", "required": false, "schema": { "type": "number", "description": "Longitude, decimal degrees" } }, { "name": "place", "in": "query", "required": false, "schema": { "type": "string", "description": "Or a place name, e.g. \"Bergen\" or \"Springfield, IL\"" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "Without an API key: x402 payment requirements (PAYMENT-REQUIRED header). With one: the owner must act, see account_url" }, "404": { "description": "Not found" } } } }, "/v1/earthquakes": { "get": { "operationId": "get_earthquakes", "summary": "Recent earthquakes nearby", "description": "Earthquakes near a point, newest first (USGS): magnitude, place, depth, distance, tsunami flag.", "parameters": [ { "name": "lat", "in": "query", "required": false, "schema": { "type": "number", "description": "Latitude, decimal degrees" } }, { "name": "lon", "in": "query", "required": false, "schema": { "type": "number", "description": "Longitude, decimal degrees" } }, { "name": "place", "in": "query", "required": false, "schema": { "type": "string", "description": "Or a place name, e.g. \"Bergen\" or \"Springfield, IL\"" } }, { "name": "radius_km", "in": "query", "required": false, "schema": { "type": "integer", "description": "Search radius, default 500" } }, { "name": "min_magnitude", "in": "query", "required": false, "schema": { "type": "number", "description": "Default 2.5" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "description": "Look back 1-30 days, default 7" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "Without an API key: x402 payment requirements (PAYMENT-REQUIRED header). With one: the owner must act, see account_url" }, "404": { "description": "Not found" } } } }, "/v1/places": { "get": { "operationId": "find_place", "summary": "Find a place", "description": "Look up a town or city (GeoNames, 15,000+ people) by name, or the nearest one to lat/lon. Free, no key needed.", "security": [], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Place name" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO country code filter" } }, { "name": "lat", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "lon", "in": "query", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "The owner must act: see account_url" }, "404": { "description": "Not found" } } } }, "/v1/subscriptions": { "post": { "operationId": "subscribe_alerts", "summary": "Push alerts for a place", "description": "Watch a place: new US weather alerts and nearby earthquakes are pushed to a URL, a Hookpie inbox or the owner's email, checked every 5 minutes. About $0.05 a place a month; the first place is free.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, decimal degrees" }, "lon": { "type": "number", "description": "Longitude, decimal degrees" }, "place": { "type": "string", "description": "Or a place name, e.g. \"Bergen\" or \"Springfield, IL\"" }, "name": { "type": "string", "description": "A label" }, "alerts": { "type": "boolean", "description": "US weather alerts (default true)" }, "earthquakes": { "type": "object", "properties": { "radius_km": { "type": "integer", "description": "Default 300, up to 2000" }, "min_magnitude": { "type": "number", "description": "Default 4" } }, "required": [], "additionalProperties": false }, "target": { "type": "object", "properties": { "url": { "type": "string", "description": "A public https URL (signed Standard Webhooks POST)" }, "inbox_id": { "type": "string", "description": "One of your Hookpie inboxes" }, "email": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [ "target" ] } } } }, "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "Without an API key: x402 payment requirements (PAYMENT-REQUIRED header). With one: the owner must act, see account_url" }, "404": { "description": "Not found" } } }, "get": { "operationId": "list_subscriptions", "summary": "List alert subscriptions", "description": "Your alert subscriptions and when each last ran.", "parameters": [], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "Without an API key: x402 payment requirements (PAYMENT-REQUIRED header). With one: the owner must act, see account_url" }, "404": { "description": "Not found" } } } }, "/v1/subscriptions/{id}": { "delete": { "operationId": "delete_subscription", "summary": "Delete an alert subscription", "description": "Stop watching a place.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "Without an API key: x402 payment requirements (PAYMENT-REQUIRED header). With one: the owner must act, see account_url" }, "404": { "description": "Not found" } } } }, "/v1/accounts": { "post": { "operationId": "create_account", "summary": "Create an account", "description": "Create an account (one account and one prepaid balance work on every agent-first site: Yawplet, Yarnhen, Hagglebee, Eventwren, Hookpie, Clockrook, Rainplover). accept_terms must be true only when the human owner accepts them. Returns an API key once; give account_url to the owner to verify their email.", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Account owner name" }, "email": { "type": "string", "description": "Owner email" }, "handle": { "type": "string", "description": "Optional public handle" }, "accept_terms": { "type": "boolean" } }, "required": [ "name", "email", "accept_terms" ] } } } }, "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "The owner must act: see account_url" }, "404": { "description": "Not found" } } } }, "/v1/account": { "get": { "operationId": "get_account", "summary": "Account balance and standing", "description": "Balance (micro-dollars), whether email is verified and a card or wallet is on file, and a fresh account_url for the owner.", "parameters": [], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "Without an API key: x402 payment requirements (PAYMENT-REQUIRED header). With one: the owner must act, see account_url" }, "404": { "description": "Not found" } } } }, "/v1/usage": { "get": { "operationId": "get_usage", "summary": "This period's usage", "description": "Metered use this month (or day), the free allowance and the unit price.", "parameters": [], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "Without an API key: x402 payment requirements (PAYMENT-REQUIRED header). With one: the owner must act, see account_url" }, "404": { "description": "Not found" } } } }, "/v1/pricing": { "get": { "operationId": "get_pricing", "summary": "Prices", "description": "Free allowances and per-unit prices in micro-dollars (1 USD = 1,000,000).", "security": [], "parameters": [], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid (problem details)" }, "401": { "description": "API key required" }, "402": { "description": "The owner must act: see account_url" }, "404": { "description": "Not found" } } } } } }