Operations Reference
Every capability in Geopera is an operation, callable two equivalent ways — by operation id or by a resource path (same body, auth, scopes, and errors):
http
POST /v1/op/{operation_id} # e.g. /v1/op/catalog.search
POST /v1/{resource}/{action} # e.g. /v1/catalog/searchThere are 205 operations across 28 domains (see Core Concepts for the invocation model). Each row lists the operation’s side-effect tier and the scope it requires (see Scopes & authorization). Operations in the spend tier accept an Idempotency-Key header.
Every operation has a fully typed request and response. The Python SDK, TypeScript SDK, and CLI expose these same operations under the same names.
Catalog & search
Browse and search commercial and public satellite imagery.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
catalog.federated_search | read | catalog:read | Search every data source covering the AOI in one query (merged, type-tagged) |
catalog.granule_points | read | catalog:read | Extract a 3D point cloud (lon/lat/elev/attribute) from a GEDI or ICESat-2 granule |
catalog.image.quicklook | read | catalog:read | Resolve + 307-redirect to a scene’s quicklook (external host) |
catalog.image.thumbnail | read | catalog:read | Resolve + 307-redirect to a scene’s thumbnail (external host) |
catalog.info.landsat | read | tiles:read | Landsat scene metadata (parsed id fields + available visualizations) |
catalog.info.naip | read | tiles:read | NAIP item metadata from the Element84 STAC |
catalog.info.sample | read | tiles:read | Sample scene metadata (sensor + on-disk STAC + bands + thumbnail) |
catalog.info.sentinel | read | tiles:read | Sentinel-2 scene metadata (parsed id + live COG info + available visualizations) |
catalog.provider.samples | read | tiles:read | List sample scenes for a provider (paged) |
catalog.providers.list | read | tiles:read | List on-disk sample-data providers (+ registered sensors) |
catalog.search | read | catalog:read | Search a commercial-imagery host’s catalog (STAC, price-enriched) |
catalog.search_stream | read | catalog:read | Invoke Catalog Search Stream |
catalog.sources.list | read | catalog:read | List every searchable data source + its collections (the dataset registry) |
catalog.tile.render | read | tiles:read | Render a public satellite XYZ tile (sentinel/landsat/naip/sample) — unbilled, unauthenticated |
catalog.vendors.list | read | catalog:read | List catalog vendors + host⇄pricing-vendor identifiers |
catalog.viz.landsat | read | tiles:read | List available Landsat visualizations |
catalog.viz.naip | read | tiles:read | List available NAIP visualizations |
Full Catalog & search reference — request & response fields →
STAC
STAC-compliant item and search endpoints.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
stac.collections.list | read | items:read | List STAC Collections owned by the caller’s organization (provider-compatible) |
stac.search | read | items:read | Cross-collection STAC search (CQL2-JSON / bbox / intersects), org-scoped |
Full STAC reference — request & response fields →
Orders & tasking
Place and manage archive orders and new-acquisition (tasking) orders.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
orders.archive.estimate | read | orders:read | Preview the server-authoritative AOI price for a cart of archive captures |
orders.archive.place | spend | orders:write | Invoke Archive Place |
orders.cancel | spend | orders:write | Cancel an order (policy-gated), refunding/voiding its reservation |
orders.coverage.get | read | orders:read | Covered-vs-remainder coverage for a fulfilled/fulfilling tasking order |
orders.coverage.groups.list | read | orders:read | Per-AOI delivered-vs-requested coverage for a tasking order (any status) |
orders.estimate | read | items:read | Price-preview an order without committing (provider-compatible) |
orders.get | read | orders:read | Get a single order (org-scoped) |
orders.get_schema | read | items:read | Get the dynamic order-form schema for a data product (reference) |
orders.list | read | orders:read | List the org’s orders (filtered, paged, provider-compatible) |
orders.list_assets | read | items:read | List the items + assets delivered for an order (STAC FeatureCollection) |
orders.place | spend | orders:write | Place order(s) from a FeatureCollection (archive reserves; tasking queues feasibility) |
orders.tasking.decisions.pending | read | orders:read | Unified inbox of the org’s pending tasking decisions (feasibility + quotation) |
orders.tasking.estimate | read | orders:read | Preview the server-authoritative price for an AOI-priced tasking request |
orders.tasking.feasibility_check | read | orders:read | Predict whether a tasking order needs a feasibility study (per-feature) |
orders.tasking.feasibility_decide | spend | orders:write | Accept a feasibility-study option (one-step priced accept reserves/post-pays) |
orders.tasking.feasibility_studies.list | read | orders:read | List the org’s feasibility studies (+ their options, paged) |
orders.tasking.opportunities_list | read | orders:read | Predicted satellite passes for a tasking AOI (manual-feasibility: empty) |
orders.tasking.place | spend | orders:write | Invoke Tasking Place |
orders.tasking.quotation_decide | spend | orders:write | Accept or reject a tasking quotation (accept reserves/post-pays) |
orders.tasking.quotations.list | read | orders:read | List the org’s tasking quotations (paged) |
orders.tasking.sensors | read | orders:read | List the tasking sensor catalog (ids, resolution, bands, pricing inputs) |
orders.tasking.templates.delete | compute | orders:write | Soft-delete a tasking template (org-scoped) |
orders.tasking.templates.list | read | orders:read | List the caller organization’s active tasking templates |
orders.tasking.templates.save | compute | orders:write | Save a reusable tasking acquisition template for the caller’s organization |
orders.update | compute | orders:write | Patch an order’s tags (metadata only; provider merge-patch) |
Full Orders & tasking reference — request & response fields →
Items
Work with delivered imagery items and their assets.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
items.asset.download | export | items:read | Issue a signed, egress-tracked download URL for an item’s asset |
items.create | compute | items:write | Create an item within a project (editor/admin on the project) |
items.delete | destructive | items:write | Soft-delete an item (admin/editor on the item’s project required) |
items.detect_asset_bands | compute | items:read | Auto-detect band names for an asset from its reflectance statistics |
items.duplicate | compute | items:write | Duplicate an item with its assets + viz profiles (admin/editor on the project) |
items.get | read | items:read | Fetch a single catalog item by id |
items.get_stac | read | items:read | Get an item as a full STAC 1.0.0 Feature with embedded assets + links |
items.lineage | read | items:read | Get the lineage tree (parents + children) for an item |
items.list | read | items:read | List a project’s items (optionally filtered by collection) |
items.list_assets | read | items:read | List all assets (files) attached to an item |
items.list_by_collection | read | items:read | List items in a collection (access via the collection’s project) |
items.search | read | items:read | Search a project’s items with STAC-compatible filters (project member access) |
items.search_org | read | items:read | Search all items across the caller’s organization (STAC-compatible) |
items.set_asset_band_names | compute | items:write | Rename the bands on an item’s asset (project member access) |
items.tile.render | read | items:read | Render a map tile for one of our catalog items (profile or direct-param) |
items.tile.statistics | read | items:read | Global expression statistics (p2/p98 rescale) from the smallest COG overview |
items.tile.tilejson | read | items:read | TileJSON metadata for one of our catalog items |
items.tile.wmts_capabilities | read | items:read | OGC WMTS 1.0.0 GetCapabilities XML for one of our items |
items.tile.wmts_get_tile | read | items:read | OGC WMTS GetTile (KVP) for one of our items |
items.update | compute | items:write | Update an item’s mutable metadata (editor/admin on its project) |
Full Items reference — request & response fields →
Assets
Access the files attached to an item.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
assets.delete | destructive | items:write | Delete an asset (file) from an item (item access required) |
Full Assets reference — request & response fields →
Collections
Group items into collections.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
collections.create | compute | collections:write | Create an organizing collection within a project (editor/admin required) |
collections.delete | destructive | collections:write | Soft-delete a collection, unlinking its items (project admin required) |
collections.get | read | collections:read | Get a collection by id within a project |
collections.list | read | collections:read | List a project’s collections (with item counts) |
collections.update | compute | collections:write | Update a collection’s metadata (editor/admin required) |
Full Collections reference — request & response fields →
Uploads
Bring-your-own-data upload sessions.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
uploads.complete | compute | uploads:write | Invoke Uploads Complete |
uploads.fail | compute | uploads:write | Mark an upload session failed, releasing its storage reservation |
uploads.initiate | compute | uploads:write | Start an upload session, reserving storage quota (editor/admin on the project) |
uploads.progress | compute | uploads:write | Update an upload session’s progress |
uploads.signed_url | compute | uploads:write | Mint a signed URL for uploading a file into an upload session |
Full Uploads reference — request & response fields →
Processing
Run processing jobs over imagery.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
processing.catalog.estimate | read | processing:read | Estimate the cost of running a process with the given inputs |
processing.catalog.get | read | processing:read | Get one process description (public) |
processing.catalog.list | read | processing:read | List available processes (OGC process catalog, public) |
processing.catalog.validate | read | processing:read | Validate process inputs (provider returns empty body on success) |
processing.create | spend | processing:process | Invoke Processing Create |
processing.create_and_dispatch | spend | processing:process | Invoke Create And Dispatch |
processing.dispatch | spend | processing:process | Dispatch an existing pending processing job to its registered worker |
processing.execute | spend | processing:process | Execute a process (reserve credits + dispatch a job) |
processing.job_types.list | read | processing:read | List available processing job types (optionally by category) |
processing.job.delete | destructive | clip:destroy | Delete any processing job by id (org-scoped) |
processing.job.get | read | processing:read | Get a processing job by id (provider facade, org-scoped) |
processing.job.register | spend | processing:process | Register a completed job’s outputs + settle its credit reservation |
processing.job.tile_info | read | clip:read | Tile rendering info for any completed processing job (clip/bathy outputs) |
processing.jobs.list | read | processing:read | List the org’s processing jobs (provider facade, org-scoped) |
processing.project_job.get | read | processing:read | Get a processing job by id (org match + project access) |
processing.project_jobs.list | read | processing:read | List a project’s processing jobs (project member access) |
Full Processing reference — request & response fields →
Clipping
Clip imagery to an area of interest.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
clip.area.metadata | read | clip:read | Capture-date metadata for a clip area |
clip.area.mosaics | read | clip:read | List mosaic types for a clip area |
clip.areas.list | read | clip:read | List delivery-bucket clip areas |
clip.create_from_area | spend | clip:write | Create + dispatch an area-bucket COG clip job |
clip.create_from_item | spend | processing:process | Invoke Clip Create From Item |
clip.job.delete | destructive | clip:destroy | Delete a clip job and its GCS files |
clip.job.download | read | clip:read | Stream a clip file from GCS (egress-enforced) |
clip.job.downloads | read | clip:read | List downloadable clip files for a job |
clip.job.get | read | clip:read | Get a single clip job by id |
clip.job.tile_info | read | clip:read | Tile rendering params for a completed clip job |
clip.jobs.list | read | clip:read | List clip jobs for an organization |
Full Clipping reference — request & response fields →
COG & tiles
Cloud-optimized GeoTIFF tiling and rendering.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
cog.colormaps | read | tiles:read | Curated colormap groups for the frontend picker (bare-dict) |
cog.formulas | read | tiles:read | Predefined spectral-index formula templates (bare-dict, keyed by index id) |
cog.statistics | read | tiles:read | AOI-scoped percentile statistics for a COG — drives per-AOI colormap rescale |
cog.thumbnail | read | tiles:read | Generate a JPEG thumbnail from the smallest COG overview |
cog.tile.render | read | tiles:read | Render an XYZ tile from a COG (bands or band-math expression) |
cog.tile.terrain | read | tiles:read | Render a Mapbox Terrain-RGB tile from a single-band elevation/depth COG |
Full COG & tiles reference — request & response fields →
Visualization
Visualization profiles and rendered layers.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
visualization.list_for | read | tiles:read | The visualizations available for an item — RGB/index/elevation — backend-owned + resolved |
visualization.profile.create | compute | items:write | Create a visualization profile for an item (editor/admin) |
visualization.profile.delete | destructive | items:write | Delete a visualization profile (editor/admin) |
visualization.profile.get | read | items:read | Get a single visualization profile for an item |
visualization.profile.set_default | compute | items:write | Set a profile as the item’s default (editor/admin) |
visualization.profile.update | compute | items:write | Update a visualization profile (editor/admin) |
visualization.profiles.list | read | items:read | List all visualization profiles for an item (ordered by sort_order, created_at) |
Full Visualization reference — request & response fields →
Band formulas
Spectral index and band-math formulas.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
band_formulas.create | compute | band_formulas:write | Create a custom band-math formula for the caller’s organization (write scope) |
band_formulas.delete | destructive | band_formulas:write | Delete a custom band-math formula (write scope; templates are protected) |
band_formulas.get | read | band_formulas:read | Get a single custom band-math formula by id (org-scoped; cross-org → 404) |
band_formulas.list | read | band_formulas:read | List the caller-org’s custom band-math formulas (optional category/template filters) |
band_formulas.update | compute | band_formulas:write | Update a custom band-math formula (write scope; org-scoped) |
Full Band formulas reference — request & response fields →
Analytics
Analytics over your data and usage.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
analytics.band_math | compute | analytics:process | Apply a custom band-math formula to a COG (statistics JSON or rendered PNG) |
analytics.calculate_index | compute | analytics:process | Calculate a named spectral index (NDVI, NDWI, …) on a COG (stats JSON or PNG) |
analytics.execute | read | analytics:process | Run a registered analytics operation (zonal_stats / time_series / change_detection) |
analytics.index.get | read | analytics:read | Detailed info about a single spectral index (+ compatible sensors) |
analytics.indices.list | read | analytics:read | List spectral indices (optionally filtered by category / sensor compatibility) |
analytics.operations.get | read | analytics:read | Detailed capabilities of a single analytics operation |
analytics.operations.list | read | analytics:read | List all registered analytics operations + their input schemas (discovery) |
analytics.sensors.list | read | analytics:read | List supported sensors and their band mappings |
analytics.validate_formula | read | analytics:read | Validate a band-math formula (syntax + required bands) without executing it |
Full Analytics reference — request & response fields →
Reports
Generated reports.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
reports.generate | read | reports:read | Invoke Reports Generate |
Full Reports reference — request & response fields →
Provenance
Lineage and provenance of derived data.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
provenance.get | read | provenance:read |
Full Provenance reference — request & response fields →
Alerts
Alert rules.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
alerts.acknowledge_event | compute | alerts:write | Mark an alert event acknowledged (org-scoped) |
alerts.create_rule | compute | alerts:write | Create an alert rule for the caller’s organization |
alerts.delete_rule | destructive | alerts:write | Delete an alert rule (org-scoped) |
alerts.events.list | read | alerts:read | List the caller’s organization’s alert events (org-scoped, triggered_at desc) |
alerts.rule.get | read | alerts:read | Get a single alert rule by id (org-scoped; 404 cross-org) |
alerts.rules.list | read | alerts:read | List the caller’s organization’s alert rules (org-scoped) |
alerts.test_rule | read | alerts:read | Test-evaluate an alert rule against an item without persisting |
alerts.update_rule | compute | alerts:write | Update an alert rule (org-scoped) |
Full Alerts reference — request & response fields →
Notifications
In-product notifications.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
notifications.dismiss | compute | notifications:write | Dismiss one of the caller’s notifications (hide it from the list) |
notifications.list | read | notifications:read | List the caller’s notifications, newest first (user-scoped inbox) |
notifications.mark_all_read | compute | notifications:write | Mark all of the caller’s unread notifications as read |
notifications.mark_read | compute | notifications:write | Mark one of the caller’s notifications as read |
notifications.unread_count | read | notifications:read | Count the caller’s unread, undismissed notifications (lightweight poll) |
Full Notifications reference — request & response fields →
Event subscriptions
Subscribe to platform events.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
event_subscriptions.create | compute | event_subscriptions:write | Create a webhook subscription for the caller’s organization |
event_subscriptions.delete | destructive | event_subscriptions:write | Delete a webhook subscription (org-scoped) |
event_subscriptions.get | read | event_subscriptions:read | Get a single webhook subscription (org-scoped; secret redacted) |
event_subscriptions.list | read | event_subscriptions:read | List the caller’s organization’s webhook subscriptions (secret redacted) |
event_subscriptions.test | compute | event_subscriptions:write | Send a test event to a webhook subscription and return the delivery result |
event_subscriptions.update | compute | event_subscriptions:write | Update a webhook subscription (org-scoped) |
Full Event subscriptions reference — request & response fields →
Sharing
Share data via links.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
share.link.create | export | shares:write | Create a password-protected share link for an item or collection |
share.link.revoke | destructive | shares:write | Revoke a share link (editor/admin on the shared target’s project) |
share.link.validate | read | shares:read | Validate a share link (token + password) and return the shared target |
share.tile.render | read | shares:read | Render a map tile for a publicly-shared item (sharer-billed) |
share.tilejson | read | shares:read | TileJSON for a publicly-shared item (token + password) |
Full Sharing reference — request & response fields →
Projects
Organize work into projects.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
projects.add_member | compute | projects:write | Add a member to a workspace (project admin/owner) |
projects.archive | compute | projects:write | Archive a workspace, hiding it from the default list (project admin/owner) |
projects.create | compute | projects:write | Create a workspace in the caller’s organization |
projects.delete | destructive | projects:write | Permanently delete a workspace and all its data (project admin/owner) |
projects.remove_member | destructive | projects:write | Remove a member from a workspace (project admin/owner) |
projects.update | compute | projects:write | Update a workspace’s metadata (project admin/owner) |
projects.update_member | compute | projects:write | Change a member’s role in a workspace (project admin/owner) |
Full Projects reference — request & response fields →
Organizations
Manage organizations.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
organizations.commitments.list | read | orders:read | List the org’s minimum commitments with server-computed burn-down + take-or-pay |
organizations.commitments.statement | read | billing:read | Monthly enterprise statement: all activity (commitment lines flagged) + burn-down + settlement reconciliation |
organizations.create | compute | organizations:write | Create an organization and enroll the caller as its owner (self-serve onboarding) |
organizations.members.list | read | organizations:read | List an organization’s members with their roles and spend caps (organization admin) |
organizations.members.set_spend_limit | compute | organizations:write | Set a member’s per-order and rolling-window credit spend caps (organization admin) |
Full Organizations reference — request & response fields →
API keys
Mint and manage API keys.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
api_keys.create | export | api_keys:write | Mint an organization API key (the secret is returned once) |
api_keys.list | read | api_keys:read | List an organization’s API keys (metadata only — never the secret) |
api_keys.revoke | destructive | api_keys:write | Revoke an organization API key |
Full API keys reference — request & response fields →
EULAs
End-user licence agreements.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
eulas.document.accept | compute | eulas:write | Record an organization’s acceptance of a EULA document (idempotent) |
eulas.document.get | read | eulas:read | Get a single EULA document enriched with the caller’s org acceptance |
eulas.documents.list | read | eulas:read | List an EULA’s documents (paged), each enriched with the caller’s org acceptance |
eulas.get | read | eulas:read | Get a single EULA enriched with the caller’s org acceptance |
eulas.list | read | eulas:read | List EULAs (paged), each enriched with the caller’s org acceptance |
Full EULAs reference — request & response fields →
Glossary
Reference glossary and collections metadata.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
glossary.collections.get | read | catalog:read | Get a single catalog collection by name |
glossary.collections.list | read | catalog:read | List catalog collections (provider-compatible, paged) |
glossary.data_products.get | read | catalog:read | Get a single catalog data product by name |
glossary.data_products.list | read | catalog:read | List catalog data products (provider-compatible, paged) |
glossary.providers.get | read | catalog:read | Get a single catalog provider by name |
glossary.providers.list | read | catalog:read | List catalog providers (PRODUCER/HOST, paged) |
Full Glossary reference — request & response fields →
Usage
Usage metering.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
usage.current | read | usage:read | Usage stats for the current billing period (storage, tiles, credits, jobs) |
usage.history | read | usage:read | Historical usage (tile requests + peak storage) for the past N months |
usage.recalculate_storage | compute | usage:write | Recalculate an org’s storage from actual stored assets (org admin) |
Full Usage reference — request & response fields →
Billing
Credits, top-ups, invoices, and payment.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
billing.approvals.approve | spend | billing:write | Approve a credit purchase and charge the saved card (human approver only) |
billing.approvals.get | read | billing:read | Get one credit-purchase approval (org-scoped) |
billing.approvals.list | read | billing:read | List the org’s credit-purchase approvals (optionally by status) |
billing.approvals.reject | compute | billing:write | Reject a pending credit-purchase approval |
billing.approvals.request | compute | billing:write | Request approval for a large credit purchase |
billing.auto_topup.get | read | billing:read | Read the org’s auto-topup settings (enabled=false if unset) |
billing.credits.balance | read | billing:read | The org’s current credit balance |
billing.credits.transactions | read | billing:read | The org’s credit ledger (paged, optionally filtered by reason) |
billing.invoices.list | read | billing:read | The org’s enterprise invoices (grouped from settled orders) |
billing.plans.list | read | billing:read | List all available plans with their quota/feature limits (public catalog) |
billing.run_monthly_for_org | spend | billing:write | Run monthly billing for one org (manual; org admin) |
billing.set_auto_topup | compute | billing:write | Configure automatic top-up (requires a default card when enabling) |
billing.status.get | read | billing:read | An org’s billing status + current usage (org membership required) |
billing.stripe_invoices.list | read | billing:read | List the org’s Stripe invoices (never 500s — empty on a Stripe hiccup) |
billing.topup | spend | billing:write | Invoke Billing Topup |
Full Billing reference — request & response fields →
Payment methods
Manage payment methods.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
payment_methods.attach | compute | billing:write | Persist a saved card (Airwallex Payment Consent) for the org |
payment_methods.create_setup_intent | compute | billing:write | Start saving a card to the org (off-session) — returns the Airwallex client_secret + env |
payment_methods.detach | destructive | billing:write | Detach (remove) a saved payment method from the org |
payment_methods.list | read | billing:read | List the org’s saved payment methods |
payment_methods.set_default | compute | billing:write | Make a saved payment method the org’s default (used by off-session charges) |
Full Payment methods reference — request & response fields →
Mosaic
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
mosaic.register | compute | items:write | Register a pipeline-produced mosaic as a first-class STAC item with provenance |