Quickstart

Go from zero to a placed order: authenticate, search the catalog, preview a price, and place an archive order — all against the live API. Every call here is a real operation; nothing is a mock or a sandbox stand-in.

You will need:

  • A Geopera organization and an API key (an org admin mints one with api_keys.create; the secret is shown once). See Authentication.
  • A project id (the workspace that owns your data and scopes access).

Throughout, the base URL is https://api.geopera.com and every call carries a Bearer token.

1. Authenticate

Your API key is your bearer token — send it directly as Authorization: Bearer <key>. There is no token-exchange step.

bash 
export TOKEN="gpra_..."

A browser sign-in to Geopera yields a session token that you use the same way. See Authentication for both credential types.

2. Make your first call

Every capability is reachable at a resource path — POST /v1/{resource}/{action} with the operation’s typed input as the JSON body. Start with a read: search a host’s catalog.

bash 
curl -s -X POST https://api.geopera.com/v1/catalog/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host_name": "earthsearch-aws",
    "collections": ["sentinel-2-l2a"],
    "bbox": [151.10, -33.92, 151.30, -33.78],
    "datetime": "2024-01-01T00:00:00Z/2024-03-31T23:59:59Z",
    "limit": 10
  }'

Every operation is also reachable at its canonical id-addressed path, POST /v1/op/{operation_id} — same body, same auth, same response. Use it when you want to drive operations dynamically by id:

bash 
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"],
    "limit": 10
  }'

Both forms are published in the OpenAPI; pick whichever reads better for your code. The response is a STAC-style FeatureCollection; each feature is a capture you can order, with pricing enrichment where the host is commercial. A read like this never touches the spend, approval, or provenance machinery — it’s cheap and safe to call freely.

3. Preview a price

Before spending anything, preview the server-authoritative price for a cart of captures. Pricing is computed by the backend — never the client — so the number you see is the number you pay.

bash 
curl -s -X POST https://api.geopera.com/v1/orders/archive/estimate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "captures": [
      { "id": "scene-abc", "host": "...", "geometry": { "type": "Polygon", "coordinates": [[[151.1,-33.9],[151.2,-33.9],[151.2,-33.8],[151.1,-33.8],[151.1,-33.9]]] } }
    ]
  }'
json 
{
	"groups": [{ "...": "per-AOI price breakdown" }],
	"errors": [],
	"total_aud": 42.0,
	"total_credits": 4200
}

total_credits is an integer credit count (100 credits = A$1); total_aud is the dollar-equivalent. estimate is a read — it persists nothing.

4. Place the order

Placing the order is an external_spend operation: it reserves credits and creates the order, recording its provenance in the same transaction.

Important — Send an Idempotency-Key so a network retry never charges twice.

bash 
curl -s -X POST https://api.geopera.com/v1/orders/archive/place \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9d1f...-your-unique-key" \
  -d '{
    "projectId": "your-project-id",
    "captures": [
      { "id": "scene-abc", "host": "...", "geometry": { "type": "Polygon", "coordinates": [[[151.1,-33.9],[151.2,-33.9],[151.2,-33.8],[151.1,-33.8],[151.1,-33.9]]] } }
    ]
  }'
json 
{
	"id": "f2b1c0de-...",
	"status": "processing",
	"orderType": "archive",
	"billingMode": "credit",
	"currency": "AUD",
	"totalAud": 42.0,
	"totalCredits": 4200,
	"groups": [{ "...": "the priced groups, as ordered" }]
}

If your org has no credits and no card, this returns 402 Payment Required — top up first (see Billing & credits). If the card needs 3-D Secure, the 402 carries a client_secret to complete the challenge, then retry with the same Idempotency-Key.

5. Track the order

Poll the order until it reaches a terminal state, then fetch its delivered items:

bash 
curl -s -X POST https://api.geopera.com/v1/orders/get \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "f2b1c0de-..."}'

Every operation is a POST — orders.get is POST /v1/orders/get (or its canonical POST /v1/op/orders.get) with the id in the JSON body; there are no GET routes. When the order is delivered, its items appear in the project and carry a provenance edge back to this order — see Provenance & lineage.

Where to go next