Quickstart

This guide takes you from zero to a placed order: get a token, 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. Get an access token

Exchange your API key for a short-lived JWT using the standard OIDC client_credentials grant:

bash 
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"
json 
{
  "access_token": "eyJhbGciOiJIUzI1Ni...",
  "token_type": "Bearer",
  "expires_in": 300,
  "refresh_token": "...",
  "refresh_expires_in": 1800
}

Capture the access_token and send it on every subsequent request:

bash 
export TOKEN="eyJhbGciOiJIUzI1Ni..."

Tokens last 5 minutes; refresh with the refresh_token (30 minutes) rather than re-sending credentials. For interactive scripts you can use the password grant instead — both are covered in Authentication.

2. Make your first call

Every capability is invoked the same way — POST /v1/op/{operation_id} 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/op/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
  }'

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/op/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.00,
  "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. Send an Idempotency-Key so a network retry never charges twice.

bash 
curl -s -X POST https://api.geopera.com/v1/op/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.00,
  "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 https://api.geopera.com/v1/op/orders.get \
  -H "Authorization: Bearer $TOKEN" \
  -G --data-urlencode 'id=f2b1c0de-...'

Reads also have idiomatic GET routes, so orders.get is reachable as shown above. 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