<!-- Source: https://docs.geopera.com/developer-platform · Markdown for LLMs -->

# 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](/api-reference)**.
> This page is a map of what's available and where to start.

## Start here

- **[Quickstart](/api-reference/quickstart)** — get a token, make your first call, and
  place an order, end to end.
- **[Authentication](/api-reference/authentication)** — OIDC tokens, API keys, scopes,
  and the principal model.
- **[Core Concepts](/api-reference/concepts)** — operations, side-effect tiers,
  idempotency, and provenance.
- **[Operations Reference](/api-reference/operations)** — every operation, grouped by
  domain, with its scope and side-effect.
- **[Errors](/api-reference/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}
```

```bash
# 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](/api-reference/sdks/python)** — a high-level `geopera` client
  (`client.catalog`, `client.orders`, `client.processing`, `client.billing`) plus a
  generated lower-level client for finer control.
- **[TypeScript SDK](/api-reference/sdks/typescript)** — fully-typed, generated from the
  OpenAPI document.
- **[AI agents (MCP)](/api-reference/sdks/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](/api-reference/guides/ordering)**
- **[Tasking new acquisitions](/api-reference/guides/tasking)**
- **[Uploading your own data](/api-reference/guides/uploads)**
- **[Processing & analytics](/api-reference/guides/processing)**
- **[Billing & credits](/api-reference/guides/billing)**
- **[Webhooks](/api-reference/guides/webhooks)**
- **[Provenance & lineage](/api-reference/guides/provenance)**

## 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`](/api-reference/errors).
- Spend operations accept an `Idempotency-Key` header for safe retries.