API Reference

The Geopera API is the programmatic surface of the satellite-imagery data platform — browse and order imagery, run processing and analytics, manage projects and STAC items, and handle billing — where every capability is one typed operation, reachable identically from REST, the SDKs, and AI agents.

Operations

Every capability the platform exposes — from catalog.search to orders.archive.place to processing.create — is a single typed operation. There is exactly one way to invoke any of them, the inputs and outputs are strongly typed, and the same set of operations is reachable from the REST API, the SDKs, and the AI/agent (MCP) interface — so every client can call the same capability.

Base URL

http 
https://api.geopera.com

All requests are HTTPS. Authentication is a Bearer token on every request (see Authentication).

The shape of the API

Every operation is reachable two equivalent ways, and both share the same body, the same auth, the same validation, and the same errors. Both are published in the OpenAPI document.

1. The canonical operation endpoint — every operation is reachable at:

http 
POST /v1/op/{operation_id}

For example, POST /v1/op/catalog.search. The request body is the operation’s typed input; the response is its typed output:

bash 
curl -X POST https://api.geopera.com/v1/op/catalog.search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "collections": ["..."], "bbox": [150.5, -34.0, 151.0, -33.5], "limit": 20 }'

2. The resource path — the same operation is also exposed at a readable resource-style route:

http 
POST /v1/{resource}/{action}

So catalog.search is also POST /v1/catalog/search, and orders.archive.place is also POST /v1/orders/archive/place. The operation id maps directly to the path — each dot becomes a path segment. Both forms take the identical body, run the identical operation underneath, and return the identical response and errors:

bash 
curl -X POST https://api.geopera.com/v1/catalog/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "collections": ["..."], "bbox": [150.5, -34.0, 151.0, -33.5], "limit": 20 }'

Why operations

Modelling every capability as one typed operation gives you several guarantees:

  • Strong typing. Each operation declares a typed input and output. The REST schema, the Python SDK, the TypeScript SDK, and the agent tool catalog all share the same typed contract.
  • One auth model. Every operation declares the scope it needs; the same check runs no matter how you call it. See Authentication.
  • Honest side-effects. Every operation declares whether it is a read, a compute, spends money (external_spend), exports/shares data (share_export), or is destructive. That classification is visible in the API and drives safety behaviour. See Core Concepts.
  • Provenance by construction. Operations that produce data (an item, an order, a processing job) record their lineage at write time — every output can be traced back to what produced it. See Core Concepts.
  • Agent-ready. Every operation is also exposed as an MCP tool, so AI agents can drive the same capabilities with the same guarantees as any other client.

Sections

  • Quickstart — token → first call → place an order, end to end.
  • Authentication — OAuth2 / OIDC tokens, API keys, scopes, and the principal model.
  • Core Concepts — the operation model, side-effect tiers, idempotency, provenance, and the multi-client surface.
  • Operations Reference — every operation, grouped by domain, with its scope and side-effect.
  • Errors — the problem+json error model and status codes.

Core reference

The cross-cutting rules that apply to every operation, no matter which client you call it from:

  • Idempotency — safely retrying writes with an idempotency key.
  • Rate limits — request limits and the headers that report them.
  • Versioning — how the API and operations are versioned over time.

Guides

SDKs & clients

  • Python SDK — the geopera package (pip install geopera), one typed method per operation.
  • TypeScript SDK — the @geopera/sdk npm package, fully typed.
  • AI agents (MCP) — the MCP gateway exposes every operation as an MCP tool.

Conventions

  • All payloads are JSON (Content-Type: application/json).
  • Identifiers are UUIDs unless noted.
  • Geometry is GeoJSON in WGS84 (EPSG:4326).
  • Timestamps are RFC 3339 / ISO 8601 (UTC).
  • Errors follow RFC 7807 application/problem+json.