Operations Reference
Every capability is an operation. Each is invoked at the operation endpoint with its typed input as the request body:
POST /v1/op/{operation_id}(see Core Concepts). The tables below list each operation
with its side-effect tier and the scope it requires. Read operations also have
idiomatic GET routes; the spend operations (marked spend) accept an Idempotency-Key header.
The exact request/response schema for every operation is published in the OpenAPI document, from which the Python and TypeScript SDKs are generated — so the types here never drift from the live API.
Catalog & search
Browse and search commercial + public satellite imagery.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
catalog.search | read | catalog:read | Search a commercial-imagery host’s catalog (STAC, price-enriched) |
catalog.search_stream | read | catalog:read | Streaming (NDJSON) variant of catalog.search for large result sets |
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 | Place an archive order for a cart of captures (reserves credits; accepts Idempotency-Key) |
orders.cancel | spend | orders:write | Cancel an order (policy-gated), refunding/voiding its reservation |
orders.tasking.estimate | read | orders:read | Preview the server-authoritative price for an AOI-priced tasking request |
orders.tasking.place | spend | orders:write | Place a tasking (new-acquisition) order over an AOI (reserves credits; accepts Idempotency-Key) |
Items, collections & assets
Manage STAC items, the collections that organize them, and their file assets.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
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.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.update | compute | items:write | Update an item’s mutable metadata (editor/admin on its project) |
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.update | compute | collections:write | Update a collection’s metadata (editor/admin required) |
assets.delete | destructive | items:write | Delete an asset (file) from an item (item access required) |
Uploads
Bring your own data into a project as STAC items + assets.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
uploads.complete | compute | uploads:write | Finalize an upload session — ingest the uploaded file(s) into items + assets |
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 |
Processing
Create, dispatch, and register the outputs of processing jobs (incl. clipping).
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
processing.create | spend | processing:process | Create a processing job (reserves credits; dispatch separately) |
processing.create_and_dispatch | spend | processing:process | Create and immediately dispatch a processing job (atomic; reserves credits) |
processing.dispatch | spend | processing:process | Dispatch an existing pending processing job to its registered worker |
clip.create_from_item | spend | processing:process | Clip a source item to an AOI as a processing job |
Visualization & band formulas
Saved visualization profiles and reusable band-math formulas.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
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.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) |
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.update | compute | band_formulas:write | Update a custom band-math formula (write scope; org-scoped) |
Reports
Generate exportable reports.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
reports.generate | read | reports:read | Generate a rendered, exportable report |
Billing & payments
Credits, top-ups, payment methods, and large-purchase approvals.
| 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.reject | compute | billing:write | Reject a pending credit-purchase approval |
billing.approvals.request | compute | billing:write | Request approval for a large credit purchase |
billing.set_auto_topup | compute | billing:write | Configure automatic top-up (requires a default card when enabling) |
billing.topup | spend | billing:write | Top up the org’s credit balance via an off-session card charge (accepts Idempotency-Key) |
payment_methods.attach | compute | billing:write | Persist a confirmed Stripe PaymentMethod for the org |
payment_methods.create_setup_intent | compute | billing:write | Create a Stripe SetupIntent to attach a card to the org (off-session) |
payment_methods.detach | destructive | billing:write | Detach (remove) a saved payment method from the org |
payment_methods.set_default | compute | billing:write | Make a saved payment method the org’s default (used by off-session charges) |
Projects
Projects (the access + storage boundary) and their membership.
| 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 (provisions storage) |
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) |
Sharing & API keys
External share links and organization API keys.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
share.link.create | share/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) |
api_keys.create | share/export | api_keys:write | Mint an organization API key (the secret is returned once) |
api_keys.revoke | destructive | api_keys:write | Revoke an organization API key |
Alerts, notifications & subscriptions
Standing alert rules, in-app notifications, and event/webhook subscriptions.
| 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.update_rule | compute | alerts:write | Update an alert rule (org-scoped) |
notifications.dismiss | compute | notifications:write | Dismiss one of the caller’s notifications (hide it from the list) |
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 |
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.test | compute | event_subscriptions:write | Send a test event to a webhook subscription and return the real delivery result |
event_subscriptions.update | compute | event_subscriptions:write | Update a webhook subscription (org-scoped) |
Analytics
Analytics runs through a single operation, analytics.execute, which dispatches to
a registered analytics method by name and validates the parameters against that
method’s own schema. Built-in methods include zonal statistics, spectral
indices, time series, and change detection (which compares a before and after item). Each method takes one or many items as input, and new methods can be
added without changing the API surface — they become available through the same analytics.execute operation.
Provenance & lineage
Walk the by-construction lineage graph.
| Operation | Side-effect | Scope | Description |
|---|---|---|---|
provenance.get | read | provenance:read | Walk the lineage graph for an entity (ancestors / descendants), org-scoped to a root you own |
STAC & resource-style routes
Beyond the operation endpoints above, the platform exposes a STAC-compatible API
(/assets/stac/search, collections, items) and resource-style order routes (/v2/orders, /v2/tasking/...) that mirror common geospatial conventions, so
existing STAC clients and SDKs work unmodified. These run the same operations
underneath, with the same auth, scopes, and provenance.
Reads
In addition to the write operations listed above, every domain exposes typed read operations (e.g. orders.get, orders.list, items.get, billing.balance, processing.jobs.list, catalog/glossary lookups). Reads require the corresponding :read scope, never touch the spend or provenance machinery, and are also reachable on
idiomatic GET routes.