This section explains how to manage the delivery of your imagery to cloud and download your purchased images via our APIs. Using these endpoints, you can initiate delivery requests, monitor their status, and finally, download the delivered imagery.


Overview

Once imagery is processed and delivered to your catalog, you can automate its delivery to your configured cloud stores and retrieve it using download resources. The process involves two main steps:

  • Delivery: Creating a delivery request that moves images from our system to your designated store (cloud bucket).
  • Download: Generating a download resource to obtain a secure URL for retrieving your images.

Delivery Workflow

1. Create a Delivery Request

Initiates an asynchronous delivery request. You can specify either a catalog ID or an order item to deliver. Only one of these should be populated per request.

  • Endpoint: POST /v0/catalogs/deliveries
  • Key Fields:
    • catalog_ids or order_item_ids: Reference to the imagery to be delivered.
    • cloud_delivery: The store configuration (includes config and optional path).
  • Sample Request:
{
    "deliveries": [
      {
        "catalog_ids": ["<CATALOG_ID>"],
        "order_item_ids" : ["ORDER_ITEM_ID"],
        "cloud_info": {
          "config": "<STORE_ID>",
          "path": "/path/to/destination"
        }
      }
    ]
  }

Note: The delivery process is asynchronous; you will receive status updates as the process completes.

2. List Delivery Requests

Retrieve a list of all delivery requests for your organization, along with their current status.

  • Endpoint: GET /v0/catalogs/deliveries
  • Query Parameters:
    You can filter by delivery_idcatalog_id, or task_id to narrow down results.

Download Workflow

1. Create a Download Resource

Initiates a request to create a download resource. This resource will eventually be populated with a signed URL for retrieving the delivered imagery.

  • Endpoint: POST /v0/catalogs/download
  • Key Fields:
    • catalog_ids or order_item_ids: Specify the images you wish to download.
  • Note:
    Note down the download ID which you will receive from this endpoint’s response because that will be used later for tracking.

2. Get Download Status

Check the status of your download resource. Once the download is ready, a signed URL will be included in the response.

  • Endpoint: GET /v0/catalogs/download/{download_id}
  • Path Parameter:
    • download_id: The unique identifier for the download resource.
  • Note:
    Poll this endpoint until the signed_url field is populated, indicating that the image is ready for download.