Skip to main content

Subscriptions API Reference

API docs by Redocly

Planet Subscriptions service API (1.0.0)

Download OpenAPI specification:Download

subscriptions

List all subscriptions

Authorizations:
ApiKeyAuthBasicAuth
query Parameters
created
string

Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.

Examples:

  • A date-time: "2018-02-12T23:20:50Z"
  • A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
  • Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

Only subscriptions or results that have a created timestamp that intersects the value of created are selected.

end_time
string

Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.

Examples:

  • A date-time: "2018-02-12T23:20:50Z"
  • A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
  • Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

Only subscriptions that have an end time that intersects the value of end_time are selected.

hosting
boolean

Only return subscriptions that contain a hosting block (e.g. SentinelHub hosting).

name__contains
string

Only return subscriptions with a name that contains the given string.

name
string

Only return subscriptions with a name that matches the given string.

page_marker
string
page_size
integer <int32> [ 0 .. 10000 ]
string or string (SourceTypesAll)
start_time
string

Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.

Examples:

  • A date-time: "2018-02-12T23:20:50Z"
  • A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
  • Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

Only subscriptions that have a start time that intersects the value of start_time are selected.

status
string
Enum: "running" "cancelled" "preparing" "pending" "completed" "suspended" "failed" "invalid"
sort_by
string

Fields to sort subscriptions by. Multiple fields can be specified, separated by commas. The sort direction can be specified by appending ' ASC' or ' DESC' to the field name. The default sort direction is ascending.

When multiple fields are specified, the sort order is applied in the order the fields are listed.

If no sort_by parameter is provided, subscriptions will be sorted by created DESC by default.

Supported fields: name, created, updated, start_time, end_time

Examples:

  • sort_by=name
  • sort_by=name DESC
  • sort_by=name,end_time DESC,start_time
updated
string

Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.

Examples:

  • A date-time: "2018-02-12T23:20:50Z"
  • A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
  • Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

Only subscriptions or results that have an updated timestamp that intersects the value of updated are selected.

user_id
string^(all|[0-9]+)$

When set to all, returns information about subscriptions created by all users in the organization.

When set to an integer that represents a user ID, only returns information about subscriptions created by that user in the organization.

Only allowed if the calling user has sufficient permissions.

geom_ref
string

URI reference to a feature collection or individual feature in the Features API.

Examples:

  • geom_ref=pl:features/my/feature-collection
  • geom_ref=pl:features/my/feature-collection/feature-id

Responses

Response samples

Content type
application/json
{
  • "_links": {
    },
  • "subscriptions": [
    ]
}

Create a subscription

Authorizations:
ApiKeyAuthBasicAuth
Request Body schema: application/json
required
GCS (object) or AWS (object) or Azure (object) or OCS (object) or GEE (object) or S3 Compatible (object)

A delivery mechanism.

Sentinel Hub (object)

Specify a data hosting location. A hosting location removes the need to specify a delivery location. Specifying both is not allowed. This location cannot be updated after a subscription has been created.

name
required
string

Name of the subscription

object

Specify notifications via webhook.

required
object (Subscription Source)

Source block to define the subscription source parameters

Array of TransformClip (object) or TransformReproject (object) or TransformBandmath (object) or TransformHarmonize (object) or TransformToar (object) or TransformFileFormat (object) or TransformCloudFilter (object)

A list of blocks for processing items obtained from 'source'.

Responses

Request samples

Content type
application/json
{
  • "delivery": {
    },
  • "hosting": {
    },
  • "name": "string",
  • "notifications": {},
  • "source": {
    },
  • "tools": [
    ]
}

Response samples

Content type
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "delivery": {
    },
  • "error_hints": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source": {
    },
  • "status": "string",
  • "tools": [
    ],
  • "updated": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Get a summary of all subscriptions

Authorizations:
ApiKeyAuthBasicAuth
query Parameters
user_id
string
Value: "all"

When set to all, returns information about subscriptions created by all users in the organization.

Only allowed if the calling user has sufficient permissions.

Responses

Response samples

Content type
application/json
{
  • "subscriptions": {
    }
}

Get a subscription

Authorizations:
ApiKeyAuthBasicAuth
path Parameters
subscriptionId
required
string <uuid>
query Parameters
user_id
string
Value: "all"

When set to all, returns information about subscriptions created by all users in the organization.

Only allowed if the calling user has sufficient permissions.

Responses

Response samples

Content type
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "delivery": {
    },
  • "error_hints": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source": {
    },
  • "status": "string",
  • "tools": [
    ],
  • "updated": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Patch a subscription

Authorizations:
ApiKeyAuthBasicAuth
path Parameters
subscriptionId
required
string <uuid>
Request Body schema: application/json
required
name
required
string

Name of the subscription

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "delivery": {
    },
  • "error_hints": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source": {
    },
  • "status": "string",
  • "tools": [
    ],
  • "updated": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Update a subscription

Authorizations:
ApiKeyAuthBasicAuth
path Parameters
subscriptionId
required
string <uuid>
Request Body schema: application/json
required
GCS (object) or AWS (object) or Azure (object) or OCS (object) or GEE (object) or S3 Compatible (object)

A delivery mechanism.

Sentinel Hub (object)

Specify a data hosting location. A hosting location removes the need to specify a delivery location. Specifying both is not allowed. This location cannot be updated after a subscription has been created.

name
required
string

Name of the subscription

required
object (Subscription Source)

Source block to define the subscription source parameters

Array of TransformClip (object) or TransformReproject (object) or TransformBandmath (object) or TransformHarmonize (object) or TransformToar (object) or TransformFileFormat (object) or TransformCloudFilter (object)

A list of blocks for processing items obtained from 'source'.

Responses

Request samples

Content type
application/json
{
  • "delivery": {
    },
  • "hosting": {
    },
  • "name": "string",
  • "source": {
    },
  • "tools": [
    ]
}

Response samples

Content type
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "delivery": {
    },
  • "error_hints": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source": {
    },
  • "status": "string",
  • "tools": [
    ],
  • "updated": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Cancel subscriptions

Permanently cancel a subscription and stop delivery. Supported when a subscription is pending, running, failed, or suspended.

Authorizations:
ApiKeyAuthBasicAuth
path Parameters
subscriptionId
required
string <uuid>

Responses

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}

results

Get results for a given subscription

Authorizations:
ApiKeyAuthBasicAuth
path Parameters
subscriptionId
required
string <uuid>
query Parameters
page_marker
string <date-time>
page_size
integer <int32> [ 0 .. 10000 ]
status
string
Enum: "created" "queued" "processing" "failed" "success"
created
string

Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.

Examples:

  • A date-time: "2018-02-12T23:20:50Z"
  • A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
  • Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

Only subscriptions or results that have a created timestamp that intersects the value of created are selected.

updated
string

Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.

Examples:

  • A date-time: "2018-02-12T23:20:50Z"
  • A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
  • Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

Only subscriptions or results that have an updated timestamp that intersects the value of updated are selected.

completed
string

Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.

Examples:

  • A date-time: "2018-02-12T23:20:50Z"
  • A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
  • Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

Only subscriptions or results that have a completed timestamp that intersects the value of completed are selected.

item_datetime
string

Either a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.

Examples:

  • A date-time: "2018-02-12T23:20:50Z"
  • A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
  • Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

Only subscriptions that have an item datetime that intersects the value of item_datetime are selected.

user_id
string
Value: "all"

When set to all, returns information about subscriptions created by all users in the organization.

Only allowed if the calling user has sufficient permissions.

Responses

Response samples

Content type
application/json
{
  • "_links": {
    },
  • "completed": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "errors": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "outputs": [
    ],
  • "properties": { },
  • "status": "string",
  • "updated": "2019-08-24T14:15:22Z"
}

Get a summary of results for a given subscription

Authorizations:
ApiKeyAuthBasicAuth
path Parameters
subscriptionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "subscription": {
    }
}
Last updated on