SibFly API — developer & agent docs

Measured ground motion (subsidence / uplift) for any US address, in mm/year and in/year, from NASA OPERA Sentinel-1 InSAR. Measured, not modeled. Flat $0.40 per covered report; misses are free; free preflight; agents can self-register. You can be making real calls in 60 seconds.

Jump to: Quickstart Auth Pricing Endpoints Params & gates Response Errors Idempotency & caching MCP Machine discovery Code snippets

Quickstart (60 seconds)

1. Get an API key — one call, no human, no captcha

curl -X POST https://sibfly.com/api/v1/autonomous/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'
# -> { "api_key":"sf_live_...", "credits_usd":1.0, ... }  (first credits free)

2. Make your first report

curl "https://sibfly.com/api/v1/motion?address=425+Fremont+St+Las+Vegas+NV" \
  -H "Authorization: Bearer sf_live_..."

3. You get JSON back (both units, uncertainty, provenance, cost)

{ "status":"ok", "velocity_vertical_mm_yr":-6, "velocity_vertical_in_yr":-0.2362,
  "velocity_uncertainty_mm_yr":1.5, "assessment_code":"notable_subsidence",
  "confidence":0.86, "data_age_days":73, "pixel_id":"F12642_1989_5771",
  "cost_usd":0.4, "credits_remaining_usd":0.6, "request_id":"req_..." }

Tip: check coverage & price for FREE first with ?dry_run=1 (nothing is charged). Out-of-coverage, too-stale, and low-confidence results are always free.

Authentication

Every paid call takes a header Authorization: Bearer <api_key>. Keys never expire. Bearer keys are not rate-limited (un-keyed calls are). Get one via the register call above, or at /signup.

Pricing & credits

$0.40 per covered report. Flat. No tiers, no subscription. Prepaid credits, never expire.
Misses are free — no coverage, no data, too stale, low confidence, fuzzy geocode, or "no new data" all return cost_usd:0.
Free preflight — /coverage, /coverage/batch, and ?dry_run=1 tell you coverage + would_cost_usd at $0.
Check balance anytime: GET /api/v1/balance. Out of credits returns 402 with a top_up_url.
Set a safety cap: POST /api/v1/account/spend_cap {"daily_usd":20} → 402 before you overspend.

Endpoints

Endpoint	What	Cost
`GET /api/v1/motion`	One report by `address=` or `lat=&lon=`	$0.40
`POST /api/v1/motion/batch`	Many addresses, one call (≤1000). Async + since + budget cap.	ok rows only
`GET /api/v1/timeseries`	Full history; `reference_date`+`reference_date2` = movement between 2 dates	$0.40
`GET /api/v1/coverage`	Is a point covered? (no args = live frame list)	free
`POST /api/v1/coverage/batch`	Size a whole job before spending	free
`GET /api/v1/frames` · `/frames/{id}/last_updated`	When data was last refreshed (poll to re-pull)	free
`GET /api/v1/balance` · `/usage`	Credits + price; per-call line-item ledger	free
`POST /api/v1/autonomous/register`	Agent self-signup → api_key + free credits	free
`POST/GET/DELETE /api/v1/keys`	Scoped, spend-capped, referer-locked child keys (safe to embed)	free
`POST /api/v1/account/spend_cap`	Set/clear a daily spend cap (`{"daily_usd":20}`)	free
`GET /api/v1/geocode`	Address → `lat,lon,matched_address,match_type,score`	free
`GET /api/v1/pixel`	The exact 30 m cell polygon (GeoJSON) covering a point	free
`GET /api/v1/me` · `/my-reports` · `/my-chats`	Your account, purchased reports, inspector chats	free
`POST /api/v1/chat`	AI-inspector Q&A about a report you already bought	narration
`POST/GET /api/v1/support`	Open + read support tickets	free
`GET /report.pdf`	Rendered PDF report (`?address=`, `&brief=1`)	$0.40
`GET /api/v1/map`	Velocity-heatmap PNG around a point (un-keyed = free teaser)	$0.40
`POST /mcp`	MCP server (5 tools) for AI agents	per tool

Params & free gates (on `/api/v1/motion`)

Param	Effect
`dry_run=1`	Free preview: coverage + confidence + `would_cost_usd`, no rate, no charge.
`max_age_days=N`	Older than N days → free miss instead of billing stale data.
`min_confidence=0..1`	Below threshold → free miss.
`min_geocode_score=0..1`	Fuzzy address match (centroid) → free miss; pass lat/lon for a confident hit.
`since=YYYY-MM-DD`	No new observation since that date → free (great for re-checks).
`include=timeseries,acceleration`	Embed full history and/or acceleration in the same paid call.
`brief=1`	Add plain-English "SibFly Inspector" narration.
`units=mm\|in` · `compact=1` · `fields=a,b,c`	Control payload size (tokens).
`mock=ok\|no_coverage\|stale_data\|...`	Free deterministic sandbox response — test every branch without spending.

Response fields

Every value carries its unit in the key name (_mm_yr + _in_yr). Key fields: velocity_vertical_mm_yr/_in_yr, velocity_uncertainty_mm_yr, assessment_code (stable enum), confidence, near_threshold, neighbor_consistent, data_age_days, data_freshness, pixel_id, pixel_polygon/pixel_geojson, provenance, cost_usd, credits_remaining_usd, request_id. Full machine-readable enums + thresholds: /api/v1/schema.

Errors & statuses

Errors are JSON: {"error":"code","message":"...","retryable":true,"doc_url":"...","request_id":"..."}. Misses are HTTP 200 with a status field (no_coverage, no_data, stale_data, low_confidence, low_geocode_precision, no_new_data) and cost_usd:0 — never 404, never billed. 402 = out of credits (carries top_up_url). 429 = rate-limited un-keyed traffic (carries Retry-After).

Idempotency, caching, safety

Idempotency: send header Idempotency-Key: <unique>; a retry replays the cached result and is not re-charged (7 days). Works on /motion and /batch.
Caching: responses carry ETag + Cache-Control: private; send If-None-Match for a free 304. Data changes only ~every 12 days.
Headers: X-Request-Id, X-Credits-Remaining, X-Spend-Today-Remaining on every call.

MCP (for AI agents)

Point any MCP client at https://sibfly.com/mcp (Streamable HTTP, JSON-RPC), auth with your Bearer key. Tools: check_ground_motion, check_portfolio, get_coverage, get_motion_history, get_account. The initialize response includes a decision-tree; tools expose the same free gates (dry_run, max_age_days, min_confidence, since).

MCP arg names differ from the REST params (also in /api/v1/schema → mcp_arg_map): check_ground_motion uses explain (not brief); get_motion_history uses from_date/to_date (→ reference_date/reference_date2); get_account maps to GET /api/v1/balance; check_portfolio takes addresses[] only. units/fields/include/mock aren't exposed over MCP — use REST for those.

Machine-readable discovery

/llms.txt — full agent-oriented docs (read this first if you're an LLM)
/openapi.json — OpenAPI spec (paths, params, examples)
/api/v1 — JSON index of endpoints · /api/v1/schema — enums, thresholds, decision-tree
/.well-known/ai-plugin.json — plugin manifest · /api/docs — interactive "try it"

Code snippets

Python

import requests
KEY = "sf_live_..."
r = requests.get("https://sibfly.com/api/v1/motion",
    params={"address": "425 Fremont St, Las Vegas NV"},
    headers={"Authorization": f"Bearer {KEY}"})
d = r.json()
print(d["velocity_vertical_mm_yr"], d["assessment_code"], d["cost_usd"])

JavaScript

const r = await fetch(
  "https://sibfly.com/api/v1/motion?address=425+Fremont+St+Las+Vegas+NV",
  { headers: { Authorization: "Bearer sf_live_..." } });
const d = await r.json();
console.log(d.velocity_vertical_mm_yr, d.assessment_code, d.cost_usd);

Batch (portfolio)

curl -X POST https://sibfly.com/api/v1/motion/batch \
  -H "Authorization: Bearer sf_live_..." -H "Content-Type: application/json" \
  -d '{"items":[{"id":"a","address":"..."},{"id":"b","lat":30.3,"lon":-97.8}]}'
# -> { "summary":{...}, "results":[ per-item ... ], "failed":[...] }