§ 1

Quickstart

Four steps. Get a token, register one sensor, ask recall for the last hour, and read the receipt that comes back. The same four calls scale from one camera to a fleet.

1 · Get a token

Create a tenant at geo.qa, then mint a key under Settings → Keys. The secret is shown once. A tenant key writes and reads; for agents, issue a scoped recall-only key instead (see § 3).

2 · Register a sensor

curl -X POST https://api.geo.qa/v1/sensors \
  -H "Authorization: Bearer $GEOQA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "camera",
    "name": "south-yard",
    "uri": "rtsp://192.0.2.10/stream",
    "place": { "lat": 27.485, "lng": 51.531 }
  }'

The video pipeline accepts RTSP, RTMP, WebRTC, and HLS. geo.qa resolves the place to its ground cell, encodes each frame to a latent on a custom capture device, and files it against that cell on the UltraFast (hourly) tempo tier. The raw frame stays on the device; only the latent lands in your memory.

3 · Ask a question

curl -X POST https://api.geo.qa/v1/recall \
  -H "Authorization: Bearer $GEOQA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "place": "south-yard", "window": "PT1H" }'

4 · Read the receipt

Every response carries a top-level receipt block. The hash is BLAKE3 over the canonical-CBOR payload; the signature is ed25519 over that hash. Nothing about it depends on us being online.

# the receipt block on every /v1/recall response
{
  "facts": [ /* fused, dated observations */ ],
  "receipt": {
    "cid": "bafy2bz…q7m4",        // base32 of BLAKE3, 26 chars
    "hash": "blake3:71d40a90…",
    "signer": "org_acme.ops",
    "sig": "ed25519:9f3c1a…"     // 64 bytes
  }
}

Verify it with the CLI or any ed25519 library. See § 10.

§ 2

Concepts

The whole API is one algebra: (cell, band, tslot) → Fact. Where, what, when, resolves to a value you can quote. Learn these five nouns and the rest is shape.

§ 3

Authentication

Bearer tokens, scoped to a tenant. Rotate them from the dashboard or over the API. A key never leaves your organisation, and writes are capability-bound: facts land under /memories/by_attester/<pubkey>/ and carry the signer’s public key.

Authorization: Bearer $GEOQA_KEY

Agent keys

For agents, issue a separate agent key. Agent keys are recall-only by default and can be pinned to a polygon, a time window, and a list of sensors: the same scope a tenant key would have, minus the right to write or to read outside the fence. This is what you hand an MCP client.

# mint a recall-only agent key, scoped to one corridor
curl -X POST https://api.geo.qa/v1/keys \
  -H "Authorization: Bearer $GEOQA_KEY" \
  -d '{
    "role": "recall",
    "scope": {
      "polygon": "corridor-04A",
      "window": "P30D",
      "sensors": ["cam.18", "cam.21"]
    }
  }'

§ 4

Recall

The endpoint your agents hit most. Give it a place and a window; it returns the dated facts that ground an answer, each tagged with the modality and source it came from, plus one receipt over the whole set.

Request

{
  "place": "south-yard",            // name, GeoJSON polygon, or cell id
  "window": "PT1H",                  // ISO-8601 duration or interval
  "bands": ["indices.ndvi", "sar.vv"], // optional band filter
  "k": 12,                           // top-k facts, default 12
  "include_public": true             // also cite the emem.dev ledger
}

Response

{
  "facts": [
    {
      "cell":     "8a1f0b27a4dffff",
      "band":     "flood_extent",
      "tslot":    "2026-05-04T03:14:09Z",
      "type":     "primary",
      "value":    0.0,
      "modality": "sar",
      "source":   "sentinel-1"
    }
    /* … 3 more, 2 modalities … */
  ],
  "receipt": { "cid": "bafy2bz…q7m4", "signer": "org_acme.ops", "sig": "ed25519:…" }
}

Pass place as a GeoJSON polygon to read a whole catchment or corridor in one call, the same operation as emem_recall_polygon on the MCP surface.

§ 5

Sensors

A sensor is anything that writes to your memory: a camera stream, a drone tasking, a satellite product subscription, a webhook of field reports.

§ 6

Alerts & loops

A loop is a saved query that runs on a cadence. When its condition holds, geo.qa emits an alert and attaches a receipt for the facts that fired it. The alert is auditable weeks later, not just a notification you have to trust.

# watch a corridor for SAR-derived vegetation loss, daily
{
  "name":      "corridor-04A-veg",
  "place":     "corridor-04A",
  "condition": "sar_delta > 3.0",    // a DerivativeFact threshold
  "cadence":   "PT24H",
  "notify":    ["webhook:my-pager", "mailto:ops@acme.ops"]
}

Conditions read like band algebra. Built-in event hunters cover deforestation, wildfire, flood extent, and algal bloom, and map to the emem_hunt tool on the MCP surface.

§ 7

Webhooks

Every payload is signed in the X-Geoqa-Signature: ed25519=… header over the raw body. Verify it before you act on it. Delivery retries with exponential backoff for up to 24 hours; failed attempts are visible in the dashboard, and the body is identical on every retry so the signature stays valid.

// POST to your endpoint, headers then body
X-Geoqa-Signature: ed25519=9af2…be21
X-Geoqa-Delivery:  d_0d1f… (stable across retries)

{
  "event":    "alert.fired",        // alert.fired · change.detected · memory.created
  "loop":     "corridor-04A-veg",
  "tslot":    "2026-05-04T03:14:09Z",
  "facts":    [ /* the observations that fired it */ ],
  "receipt":  { "cid": "bafy2bz…", "sig": "ed25519:…" }
}

§ 8

MCP server

Every tenant is also a Model Context Protocol server. Point your agent at https://mcp.geo.qa and authenticate with a recall-only agent key (§ 3). Read tools carry readOnlyHint; the open ledger at emem.dev is exposed as cite_public, so an agent reads your private memory and the public commons in one answer.

The tool surface

The 81-tool surface speaks the open emem protocol. The core reads, domain shortcuts, and physics solvers you will reach for most:

Client config

Drop this into your MCP client (Claude Desktop, Cursor, any agent runtime). The key is a scoped agent key, not your tenant key.

{
  "mcpServers": {
    "geoqa": {
      "url": "https://mcp.geo.qa",
      "headers": {
        "Authorization": "Bearer $GEOQA_AGENT_KEY"
      }
    }
  }
}

§ 9

SDKs

First-party clients for Python and TypeScript. Both are thin: they wrap the REST API, handle retries, and verify every receipt before handing you the facts.

pip install geoqa
npm install @geoqa/client

# the friendly verbs map onto the same protocol
import os
from geoqa import Client

g = Client(key=os.environ["GEOQA_KEY"])

cell = g.locate(lat=27.485, lon=51.531)
ans  = g.recall(place="south-yard", window="PT1H")

assert ans.verify()        # offline ed25519 check
print(ans.facts, ans.receipt.cid)

The TypeScript client mirrors it: await g.recall({ place, window }), then ans.verify(). Both also expose ask(), watch(), and verify() over the same endpoints.

§ 10

Verify a receipt

Verification needs no account and no network. Every receipt checks out from the receipt plus the signer’s public key, with no callback to geo.qa. Canonical CBOR makes the payload byte-deterministic, BLAKE3 hashes it to 32 bytes, and ed25519 signs the hash. A batch verifies against its BLAKE3 Merkle root, so you can check ten thousand facts against one signature.

# the public key lives at a well-known path
geoqa verify receipt.cbor \
  --pubkey https://geo.qa/.well-known/emem.json

→ ok · signer org_acme.ops · blake3 71d40a90… · ed25519 valid

The format is identical to emem.dev, so a single verifier handles your private receipts and the public ledger. On the MCP surface this is emem_verify_receipt.

§ 11

Errors

Standard HTTP status codes with a machine-readable code and a human message in the body.

A NegativeFact is not an error. If a place was outside coverage or a GPU was unavailable, you get a signed 200 with type: "negative" and a reason, not a 404.

§ 12

Rate limits

Daily caps follow your plan on the pricing page, with a hard burst ceiling on top. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset; we email at 80% and 95% of a daily cap. On 429, honour Retry-After. The SDKs do this for you.

§ 13

Changelog