Developers

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 results
  • usage:read — read your usage and rate-limit headroom
  • checks: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

GET/sitesscope: sites:read

Every 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"
    }
  ]
}
GET/sites/{id}scope: sites:read

Full 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…"
  }
}
GET/sites/{id}/observationsscope: sites:read

Satellite 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…"
}
GET/checks/{id}scope: sites:read

Result 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…"
  }
}
GET/usagescope: usage:read

Month-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.