Core Concepts

A handful of ideas explain how the whole API behaves. Understand these and every endpoint becomes predictable.

Operations

A capability is a single operation with a stable, dotted identifier (orders.archive.place, items.create, catalog.search). An operation declares:

• a typed input model and a typed output model,
• a required scope (the one permission it needs),
• a side-effect classification (below),
• and, for producers, the kind of artifact it produces (an item, an order, a job…).

Every operation runs through the same fixed pipeline on every call:

Authenticate → Authorize (scope) → Validate input → Domain checks
  → [open provenance] → Execute → Validate output → [seal provenance] → Audit

You cannot opt an operation out of any stage. That is what makes the API’s guarantees uniform: a capability cannot be added that skips authentication, scope, validation, or provenance.

Side-effect tiers

Every operation is honestly classified by what it does. The classification is part of the API contract (surfaced as x-side-effect in the OpenAPI document) and drives client-side safety hints:

Reads are cheap and never touch the spend, approval, or provenance machinery. Writes do. AI agents and SDKs use these tiers to mark operations as read-only or destructive.

Idempotency

Operations that move money or create durable resources accept an Idempotency-Key header. Replaying a request with the same key returns the original result instead of performing the action twice — safe to retry on a dropped connection. This is enforced on the spend paths (placing an order, topping up credits, creating a processing job).

Provenance

Geopera records lineage at write time. When an operation produces data — an order, a delivered item, a processing job’s outputs — it emits a provenance record linking the output to what produced it and what it was derived from, in the same transaction that created the data. Two consequences:

• It cannot be skipped. The platform refuses to return a producing operation as a success unless its output’s lineage was recorded. Provenance is a property of the write path, not an afterthought.
• It is walkable. “How was this produced?” is a query: an order traces to the product and captures it was placed for; a delivered item traces to its order; a processing output traces to the job and the inputs it ran on. Lineage survives even if a source is later archived.

This is the backbone for auditability and reproducibility — every artifact carries the record of how it came to exist.

One registry, every client

There is a single registry of operations, and every client is a projection of it, generated from the same source:

• REST / OpenAPI — one typed route per operation; the OpenAPI document is reflected from the registry, so it never drifts from the implementation.
• Python SDK and TypeScript SDK — generated from that OpenAPI document, fully typed, no hand-maintenance.
• MCP (agent) tools — the registry projects into a Model Context Protocol tool catalog, so an AI agent can call operations as tools, with read-only and destructive hints derived from the side-effect tier.

Because all of these come from one source, adding an operation makes it available to the REST API, both SDKs, and the agent surface at once — with the same typing, the same scope, and the same provenance.

Geospatial correctness

Geometry is GeoJSON in WGS84 (EPSG:4326) at the API boundary, and all rendering, re-projection, clipping, statistics, and band math are computed by the backend — the client sends parameters, the platform produces the correct result. This keeps every client (the portal, the SDKs, an agent) consistent: there is one authoritative place the computation happens.