Developer Platform

Geopera’s developer platform is the programmatic surface of the satellite-imagery data platform: search and order imagery, run processing and analytics, manage projects and STAC items, and handle billing — all through one consistent, typed interface.

It is built on a capability model: every capability is a single typed operation, and the same registry of operations drives the REST API, the SDKs, and the AI (MCP) surface. Add an operation once and every client can call it, with the same auth, validation, and provenance.

Note — The full, authoritative reference lives under API Reference. This page is a map of what’s available and where to start.

Start here

• Quickstart — get a token, make your first call, and place an order, end to end.
• Authentication — OIDC tokens, API keys, scopes, and the principal model.
• Core Concepts — operations, side-effect tiers, idempotency, and provenance.
• Operations Reference — every operation, grouped by domain, with its scope and side-effect.
• Errors — the RFC 7807 problem+json error model.

How you call it

Every capability is reached the same way — the operation’s typed input is the request body:

POST /v1/op/{operation_id}

# 1. Get a token (OIDC client_credentials with an API key)
curl -s -X POST \
  https://api.geopera.com/realms/public/protocol/openid-connect/token \
  -d grant_type=client_credentials -d client_id=geopera \
  -d client_secret="$GEOPERA_API_KEY"

# 2. Call an operation
curl -s -X POST https://api.geopera.com/v1/op/catalog.search \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "host_name": "earthsearch-aws", "collections": ["sentinel-2-l2a"], "bbox": [151,-34,152,-33], "limit": 10 }'

Common capabilities are also exposed on familiar resource-style routes (/v2/orders, the STAC /assets/stac/search) that run the identical operations underneath — so existing STAC tooling works unmodified.

SDKs & clients

• Python SDK — a high-level geopera client (client.catalog, client.orders, client.processing, client.billing) plus a generated lower-level client for finer control.
• TypeScript SDK — fully-typed, generated from the OpenAPI document.
• AI agents (MCP) — every operation as a Model Context Protocol tool, with read-only / destructive safety hints.

All three are projections of the same operation registry, so they never drift from the live API.

Guides

• Ordering archive imagery
• Tasking new acquisitions
• Uploading your own data
• Processing & analytics
• Billing & credits
• Webhooks
• Provenance & lineage

What makes it different

• Strong typing, no drift. Each operation declares typed input and output; the REST schema and every SDK are generated from one source.
• One auth model. Every operation declares the single scope it needs; the check runs identically however you call it.
• Honest side-effects. Each operation declares whether it reads, computes, spends, exports, or destroys — visible in the API and used for client safety.
• Provenance by construction. Operations that produce data record their lineage at write time; an output that doesn’t record where it came from can’t ship.
• Agent-ready. The registry projects directly into MCP tools, so AI agents get the same capabilities and guarantees as any client.

Conventions

• All payloads are JSON (Content-Type: application/json).
• Geometry is GeoJSON in WGS84 (EPSG:4326); the backend does all rendering, clipping, and band math.
• Timestamps are RFC 3339 / ISO 8601 (UTC); identifiers are UUIDs unless noted.
• Errors follow RFC 7807 application/problem+json.
• Spend operations accept an Idempotency-Key header for safe retries.