# 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](/api-reference/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](/developer-platform) 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.