Create delivery

POST /delivery/v1/deliveries

The createDelivery operation is used to request delivery of licensed imaging products to your storage. You can request delivery of any STAC items that you own (including images you have previously tasked with PRIVATE exclusivity) using this operation, including:

  • Products you have purchased from the public catalog,

  • Products you have previously tasked.

You have the option of explicitly specifying the delivery location (for example, an AWS S3 endpoint).

To discover when the products are delivered, you can use a notifications object to register a webhook (or you could poll the getDelivery operation to check the delivery status).

Currently, AWS S3 is the only supported delivery location.

Required parameters

Contract ID

The contractID parameter specifies the contract associated with this delivery request.

Item IDs

The itemIDs parameter specifies the products for delivery, formatted as an array of STAC item IDs. Each STAC item ID identifies a product of a particular type (for example, GRD) generated from a particular image frame.

You must already own a STAC item in order to include it in a delivery request. You can obtain the STAC item IDs you own in either of the following ways:

  • Products you have purchased from the public catalog:

    1. Get the list of purchased frames and their purchase IDs by invoking the listPurchasedItems operation.

    2. List the STAC items associated with a particular purchase ID by invoking the listPurchasedItemProducts operation.

  • Products you have previously tasked:

    1. Get the list of historical tasks associated with your contract, by invoking the listTasks operation.

    2. List the STAC items associated with a particular task ID by invoking the taskProducts operation (only for tasks whose status is FULFILLED or DONE).

Delivery locations

The deliveryLocations parameter is an array of delivery locations, where each delivery location is defined by the following properties:

Property Description

configID

A config ID that references a delivery location config object previously created on your behalf by the COSP team. You can discover the currently available location configs by invoking the listDeliveryLocationConfigs operation.

path

Specifies the delivery location, using the appropriate URL format for the chosen delivery method. This value must match one of the location paths in your contract.

subpath (optional)

Specifies a subfolder of the delivery location. This value can be freely chosen.
Delivered files are placed directly into the folder specified by path (optionally extended by subpath) — the Delivery API does not create an additional folder to group delivered files together.

For example, to specify delivery to AWS S3, in the folder1/folder2/ subpath of the DOC-EXAMPLE-BUCKET1 bucket:

"deliveryLocations": [
  {
    "configID": "XXXXXXXXXXXX",
    "path": "DOC-EXAMPLE-BUCKET1",
    "subPath": "folder1/folder2/"
  },
],
You can also specify a nested folder in the path, for example DOC-EXAMPLE-BUCKET1/folderA/folderB.

Optional parameters

Notifications

You can optionally use a webhook to receive a notification whenever the delivery status changes — for example, to be notified when the requested data products are available at the delivery location (delivery status transitions to SUCCESS).

To use a webhook (which must already be registered with the Notifications API), provide the id of the registered webhook in the notifications parameter, as follows:

"notifications": {
  "webhook": {
    "id": "XXXXXX-XXXXXX-XXXXXX",
  },
},

The notifications flow works as follows:

  1. The webhook (identified by its webhook ID) must already be registered with the Notifications API. To receive the notification callbacks, you must implement a callback HTTPS server.

  2. When you invoke the createDelivery operation, specify the webhook ID in the notifications parameter.

  3. When the status of the delivery changes, the notification service sends a callback message containing the delivery requst ID to your callback HTTPS server.

  4. Call the getDelivery operation with the provided delivery request ID to check the updated delivery status.

For more details, see Notifications.

Delivery object

The delivery object is returned in an API response to give the current status of the specified delivery request.

Property Description

id

ID of the delivery request.

status

A string value that provides the current status of the bundle request (PENDING, SUCCESS, or FAILED).

url

Delivery location in URL format (for example, https://bucket-name.s3.region.amazonaws.com/file-name).

itemIDs

An array of STAC item IDs, which specifies the products included in the delivery.

deliveryLocations

An array of delivery locations where the products are delivered.

notifications

(Optional) A notifications object for receving callbacks through a Webhook.

Example

Request

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/delivery/v1/deliveries" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data '{
  "itemIDs": [
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  ],
  "contractID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "deliveryLocations": [
    {
      "configID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "path": "path",
      "subpath": "subpath"
    }
  ],
  "notifications": {
    "webhook": {
      "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
  }
}'

Response

On success, returns a 200 status code and a JSON object containing the delivery object, which includes the bundle request ID, the delivery status, and a reference to a notifications object.

{
  "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "status": "PENDING",
  "url": "https://bucket-name.s3.region.amazonaws.com/file-name",
  "itemIDs": [
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  ],
  "deliveryLocations": [
    {
      "configID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "path": "path",
      "subpath": "subpath"
    }
  ],
  "notifications": {
    "webhook": {
      "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
  }
}