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

# 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](/api-reference/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](/api-reference/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](/api-reference/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](/api-reference/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](/api-reference/quickstart)** — token → first call → place an order, end
  to end.
- **[Authentication](/api-reference/authentication)** — OAuth2 / OIDC tokens, API keys,
  scopes, and the principal model.
- **[Core Concepts](/api-reference/concepts)** — the operation model, side-effect tiers,
  idempotency, provenance, and the multi-client surface.
- **[Operations Reference](/api-reference/operations)** — every operation, grouped by
  domain, with its scope and side-effect.
- **[Errors](/api-reference/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](/api-reference/idempotency)** — safely retrying writes with an
  idempotency key.
- **[Rate limits](/api-reference/rate-limits)** — request limits and the headers that
  report them.
- **[Versioning](/api-reference/versioning)** — how the API and operations are versioned
  over time.

### Guides

- **[Ordering archive imagery](/api-reference/guides/ordering)** — search → estimate →
  place → track.
- **[Tasking new acquisitions](/api-reference/guides/tasking)** — feasibility → quotation
  → priced accept.
- **[Uploading your own data](/api-reference/guides/uploads)** — bring-your-own COGs as
  STAC items.
- **[Processing & analytics](/api-reference/guides/processing)** — clip, run indices,
  change detection.
- **[Billing & credits](/api-reference/guides/billing)** — credits, top-ups, 3-D Secure,
  auto top-up.
- **[Enterprise & governance](/api-reference/guides/enterprise)** — post-pay billing,
  commitments, statements, and per-member spend caps.
- **[Webhooks](/api-reference/guides/webhooks)** — subscribe to events, verify the
  signature, durable at-least-once delivery.
- **[Provenance & lineage](/api-reference/guides/provenance)** — how lineage is recorded
  by construction.

### SDKs & clients

- **[Python SDK](/api-reference/sdks/python)** — the `geopera` package
  (`pip install geopera`), one typed method per operation.
- **[TypeScript SDK](/api-reference/sdks/typescript)** — the `@geopera/sdk` npm package,
  fully typed.
- **[AI agents (MCP)](/api-reference/sdks/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`](/api-reference/errors).