Ground Stasis API
A small REST API over your monitoring data — sites, their satellite observation history, and one-off activity-check results. Read-only today; it’s the same data that powers your dashboard. Create a key under your account.
Base URL
https://groundstasis.com/api/v1
Machine-readable spec: /api/v1/openapi.json (OpenAPI 3.1).
Authentication
Send your key as a bearer token. Keys are shown once at creation and stored only as a hash — rotate by revoking and minting a new one. Never ship a key in client-side code.
curl https://groundstasis.com/api/v1/sites \ -H "Authorization: Bearer gs_live_YOUR_KEY"
The X-API-Key: gs_live_… header works too.
Scopes
A key carries only the scopes you grant it:
sites:read— read sites, observations, and check resultsusage:read— read your usage and rate-limit headroomchecks:write,sites:write,webhooks:manage— reserved for write and webhook endpoints as they ship
Rate limits
The developer tier allows 60 requests/minute per key. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; over the limit you get 429 with { "error": { "code": "rate_limited" } }.
Pagination
List endpoints that can grow are cursor-paginated. Pass ?limit= (1–100) and the next_cursor from the previous response as ?cursor=. A null next_cursor means the last page.
Errors
Every error shares one shape, with a stable machine-readable code:
{ "error": { "code": "not_found", "message": "Site not found." } }401 unauthorized · 403 forbidden (missing scope) · 404 not_found · 429 rate_limited · 500 server_error
Endpoints
/sitesscope: sites:readEvery site on your account.
{
"data": [
{
"id": "ckv…",
"name": "Lot 7 — Maple Ridge",
"address": "100 Main St",
"status": "ACTIVE",
"stasis_score": 82,
"confidence": "HIGH",
"last_evaluated_at": "2026-10-20T06:00:00.000Z"
}
]
}/sites/{id}scope: sites:readFull detail for one site, including geometry and loan metadata.
{
"data": {
"id": "ckv…",
"name": "Lot 7 — Maple Ridge",
"status": "ACTIVE",
"stasis_score": 82,
"confidence": "HIGH",
"latitude": 40.76, "longitude": -111.89,
"area_acres": 2.4,
"loan_amount": 1250000, "loan_number": "LN-2291",
"construction_start": "2026-01-15T00:00:00.000Z",
"construction_end": null,
"draw_intelligence": true,
"last_evaluated_at": "2026-10-20T06:00:00.000Z",
"created_at": "2026-01-10T…", "updated_at": "2026-10-20T…"
}
}/sites/{id}/observationsscope: sites:readSatellite observation history, newest first, with per-observation vegetation/built-up metrics.
curl "https://groundstasis.com/api/v1/sites/ckv…/observations?limit=50" \
-H "Authorization: Bearer gs_live_YOUR_KEY"
{
"data": [
{
"id": "obs…",
"observation_date": "2026-10-18T00:00:00.000Z",
"provider": "sentinel-2",
"cloud_percent": 3.1,
"usable_pixel_percent": 96.9,
"quality_status": "OK",
"metrics": { "mean_ndvi": 0.41, "site_change_percent": 12.5, "confidence": "HIGH" }
}
],
"next_cursor": "obs…"
}/checks/{id}scope: sites:readResult of a one-off activity check. Returned only when the check’s email matches your account email.
{
"data": {
"id": "chk…",
"paid": true,
"site_name": "Lot 7",
"status": "STASIS",
"stasis_score": 20,
"confidence": "MEDIUM",
"provider": "sentinel-2",
"analyzed_at": "2026-10-19T12:00:00.000Z",
"created_at": "2026-10-19T…"
}
}/usagescope: usage:readMonth-to-date request total and current rate-limit headroom.
{
"period": { "start": "2026-10-01T00:00:00.000Z", "interval": "month_to_date" },
"usage": { "total_requests": 1420 },
"rate_limit": { "per_minute": 60, "remaining": 59 }
}Webhooks
Register an endpoint under your account and Ground Stasis POSTs a signed JSON event when a site changes — stasis detected, activity resumed, a data gap, a new observation, or any status change. Endpoints must be https; each has its own secret, shown once.
Delivery is at-least-once with retries (exponential backoff, up to ~6 hours). Deduplicate on the X-GroundStasis-Delivery id. Payload:
{
"id": "dlv_…", // stable delivery id — dedupe on this
"event": "stasis.detected",
"created_at": "2026-10-27T…Z",
"data": {
"site_id": "ckv…",
"site_name": "Lot 7 — Maple Ridge",
"status": "STASIS",
"stasis_score": 20,
"confidence": "MEDIUM",
"observed_at": "2026-10-27T…Z"
}
}Verify the X-GroundStasis-Signature header (t=<unix>,v1=<hmac>) against the raw request body before trusting it:
const crypto = require("crypto");
function verify(secret, header, rawBody) {
const p = Object.fromEntries(header.split(",").map((s) => s.trim().split("=")));
const expected = crypto
.createHmac("sha256", secret)
.update(`${p.t}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(p.v1 || "");
const fresh = Math.abs(Date.now() / 1000 - Number(p.t)) < 300; // 5-min window
return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}Write endpoints are on the roadmap. Need something specific? Create a key and tell us what you’re building.