Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/subscriptions/reference/) # Subscriptions API Reference * subscriptions * getList all subscriptions * postCreate a subscription * postCreate multiple subscriptions * postReactivate subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids * getGet a summary of all subscriptions * postSuspend subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids * getGet a subscription * patchPatch a subscription * putUpdate a subscription * postCancel subscriptions * postReactivate a subscription * postSuspend a subscription * bulk * postCreate multiple subscriptions * postReactivate subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids * postSuspend subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids * suspension/reactivation * postReactivate subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids * postSuspend subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids * postReactivate a subscription * postSuspend a subscription * results * getGet results for a given subscription * getGet a summary of results for a given subscription [API docs by Redocly](https://redocly.com/redoc/) # Planet Subscriptions service API (1.0.0) Download OpenAPI specification:[Download](https://docs.planet.com/redocusaurus/subscriptions-api-spec.yaml) ## [](#tag/subscriptions)subscriptions ## [](#tag/subscriptions/operation/listSubscriptions)List all subscriptions ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### query Parameters | | | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | created | stringEither 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 | stringEither 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 | booleanOnly return subscriptions that contain a hosting block (e.g. Planet Insights Platform hosting). | | name\_\_contains | stringOnly return subscriptions with a name that contains the given string. | | name | stringOnly return subscriptions with a name that matches the given string. | | page\_marker | string | | page\_size | integer \ \[ 0 .. 10000 ] | | source\_type | string or string (SourceTypesAll) | | start\_time | stringEither 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 | stringEnum: "running" "cancelled" "preparing" "pending" "completed" "suspended" "failed" "invalid" | | sort\_by | stringFields 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\_timeExamples:- `sort_by=name`
- `sort_by=name DESC`
- `sort_by=name,end_time DESC,start_time` | | updated | stringEither 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 | stringURI 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 **200** A paged array of subscriptions **401** Unauthenticated **403** Permission denied **500** Internal server error get/subscriptions/v1 https\://api.planet.com/subscriptions/v1 ### Response samples * 200 * 403 * 500 Content type application/json Copy Expand all Collapse all `{ "_links": { "_self": "string", "next": "string" }, "subscriptions": [ { "backfill_completed": "2019-08-24T14:15:22Z", "created": "2019-08-24T14:15:22Z", "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "error_hints": { "details": [ null ], "reason": "Unexpected error" }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "notifications": { "webhook": { "topics": [ "delivery.success" ], "url": "http://example.com" } }, "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geometry": { }, "geometry_relation": "string", "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "status": "string", "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ], "updated": "2019-08-24T14:15:22Z", "_links": { "_self": "string" } } ] }` ## [](#tag/subscriptions/operation/createSubscription)Create a subscription ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### Request Body schema: application/jsonrequired | | | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | delivery | GCS (object) or AWS (object) or Azure (object) or OCS (object) or GEE (object) or S3 Compatible (object) or Planet Destination (object)A delivery mechanism. | | hosting | Planet Insights Platform Hosting (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. | | namerequired | stringName of the subscription | | notifications | objectSpecify notifications via webhook. | | sourcerequired | object (Subscription Source)Source block to define the subscription source parameters | | tools | 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 **200** Subscription created successfully **400** Bad Request **401** Unauthenticated **403** Permission denied **500** Unexpected error post/subscriptions/v1 https\://api.planet.com/subscriptions/v1 ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "hosting": { "parameters": { "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80", "configuration_id": "af0daaf4-983e-4703-a7ed-a10f146d6684", "create_configuration": true }, "type": "sentinel_hub" }, "name": "string", "notifications": { "webhook": { "topics": [ "delivery.success" ], "url": "http://example.com" } }, "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geometry": { }, "geometry_relation": "string", "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ] }` ### Response samples * 200 * 400 * 403 * 500 Content type application/json Copy Expand all Collapse all `{ "backfill_completed": "2019-08-24T14:15:22Z", "created": "2019-08-24T14:15:22Z", "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "error_hints": { "details": [ null ], "reason": "Unexpected error" }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "notifications": { "webhook": { "topics": [ "delivery.success" ], "url": "http://example.com" } }, "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geometry": { }, "geometry_relation": "string", "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "status": "string", "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ], "updated": "2019-08-24T14:15:22Z", "_links": { "_self": "string" } }` ## [](#tag/subscriptions/operation/bulkCreateSubscriptions)Create multiple subscriptions ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### Request Body schema: application/jsonrequired | | | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | subscriptionsrequired | Array of objectsList of subscriptions to bulk create | | Arraydelivery GCS (object) or AWS (object) or Azure (object) or OCS (object) or GEE (object) or S3 Compatible (object) or Planet Destination (object) A delivery mechanism. hosting Planet Insights Platform Hosting (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 notifications object Specify notifications via webhook. source required object (Subscription Source) Source block to define the subscription source parameters tools 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 **202** Bulk create request submitted successfully **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error post/subscriptions/v1/bulk https\://api.planet.com/subscriptions/v1/bulk ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "subscriptions": [ { "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "hosting": { "parameters": { "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80", "configuration_id": "af0daaf4-983e-4703-a7ed-a10f146d6684", "create_configuration": true }, "type": "sentinel_hub" }, "name": "string", "notifications": { "webhook": { "topics": [ "delivery.success" ], "url": "http://example.com" } }, "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geometry": { }, "geometry_relation": "string", "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ] } ] }` ### Response samples * 202 * 400 * 403 * 409 * 500 Content type application/json Copy Expand all Collapse all `{ "_links": { "list": "string" } }` ## [](#tag/subscriptions/operation/bulkReactivateSubscriptions)Reactivate subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### query Parameters | | | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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. | ##### Request Body schema: application/json | | | | ------------------------- | ------------------------------------------------------------------------------------------------------- | | subscription\_idsrequired | Array of strings \ \[ 1 .. 1000 ] items \[ items \ ]List of subscription IDs to reactivate | ### Responses **202** Bulk subscriptions reactivation request received **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error **503** Service unavailable post/subscriptions/v1/reactivate https\://api.planet.com/subscriptions/v1/reactivate ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "subscription_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ] }` ### Response samples * 400 * 403 * 409 * 500 * 503 Content type application/json Copy Expand all Collapse all `{ "error": { "details": [ null ], "reason": "Reactivate request failed" } }` ## [](#tag/subscriptions/operation/getSummary)Get a summary of all subscriptions ##### Authorizations: *ApiKeyAuth**BasicAuth* ### Responses **200** A summary response **401** Unauthenticated **403** Permission denied **500** Internal server error get/subscriptions/v1/summary https\://api.planet.com/subscriptions/v1/summary ### Response samples * 200 * 403 * 500 Content type application/json Copy Expand all Collapse all `{ "subscriptions": { "cancelled": 0, "completed": 0, "failed": 0, "invalid": 0, "pending": 0, "preparing": 0, "running": 0, "suspended": 0 } }` ## [](#tag/subscriptions/operation/bulkSuspendSubscriptions)Suspend subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### query Parameters | | | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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. | ##### Request Body schema: application/json | | | | ----------------- | ---------------------------------------------------------------------------------------------------- | | details | stringDetails about the suspension reason | | subscription\_ids | Array of strings \ \[ 1 .. 1000 ] items \[ items \ ]List of subscription IDs to suspend | ### Responses **202** Bulk subscriptions suspension request received **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error **503** Service unavailable post/subscriptions/v1/suspend https\://api.planet.com/subscriptions/v1/suspend ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "details": "string", "subscription_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ] }` ### Response samples * 400 * 403 * 409 * 500 * 503 Content type application/json Copy Expand all Collapse all `{ "error": { "details": [ null ], "reason": "Suspend request failed" } }` ## [](#tag/subscriptions/operation/getSubscription)Get a subscription ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### path Parameters | | | | ---------------------- | -------------- | | subscriptionIdrequired | string \ | ### Responses **200** A subscription response **401** Unauthenticated **403** Permission denied **500** Internal server error get/subscriptions/v1/{subscriptionId} https\://api.planet.com/subscriptions/v1/{subscriptionId} ### Response samples * 200 * 403 * 500 Content type application/json Copy Expand all Collapse all `{ "backfill_completed": "2019-08-24T14:15:22Z", "created": "2019-08-24T14:15:22Z", "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "error_hints": { "details": [ null ], "reason": "Unexpected error" }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "notifications": { "webhook": { "topics": [ "delivery.success" ], "url": "http://example.com" } }, "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geometry": { }, "geometry_relation": "string", "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "status": "string", "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ], "updated": "2019-08-24T14:15:22Z", "_links": { "_self": "string" } }` ## [](#tag/subscriptions/operation/patchSubscription)Patch a subscription ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### path Parameters | | | | ---------------------- | -------------- | | subscriptionIdrequired | string \ | ##### Request Body schema: application/jsonrequired | | | | ------------ | ------------------------------ | | namerequired | stringName of the subscription | ### Responses **200** A subscription response **400** Bad Request **401** Unauthenticated **403** Permission denied **500** Internal server error patch/subscriptions/v1/{subscriptionId} https\://api.planet.com/subscriptions/v1/{subscriptionId} ### Request samples * Payload Content type application/json Copy `{ "name": "string" }` ### Response samples * 200 * 400 * 403 * 500 Content type application/json Copy Expand all Collapse all `{ "backfill_completed": "2019-08-24T14:15:22Z", "created": "2019-08-24T14:15:22Z", "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "error_hints": { "details": [ null ], "reason": "Unexpected error" }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "notifications": { "webhook": { "topics": [ "delivery.success" ], "url": "http://example.com" } }, "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geometry": { }, "geometry_relation": "string", "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "status": "string", "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ], "updated": "2019-08-24T14:15:22Z", "_links": { "_self": "string" } }` ## [](#tag/subscriptions/operation/updateSubscription)Update a subscription ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### path Parameters | | | | ---------------------- | -------------- | | subscriptionIdrequired | string \ | ##### Request Body schema: application/jsonrequired | | | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | delivery | GCS (object) or AWS (object) or Azure (object) or OCS (object) or GEE (object) or S3 Compatible (object) or Planet Destination (object)A delivery mechanism. | | hosting | Planet Insights Platform Hosting (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. | | namerequired | stringName of the subscription | | sourcerequired | object (Update Subscription Source)Source block to define the update subscription source parameters | | tools | 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 **200** A subscription response **400** Bad Request **401** Unauthenticated **403** Permission denied **500** Internal server error put/subscriptions/v1/{subscriptionId} https\://api.planet.com/subscriptions/v1/{subscriptionId} ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "hosting": { "parameters": { "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80", "configuration_id": "af0daaf4-983e-4703-a7ed-a10f146d6684", "create_configuration": true }, "type": "sentinel_hub" }, "name": "string", "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geom_ref": "string", "geometry": { }, "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ] }` ### Response samples * 200 * 400 * 403 * 500 Content type application/json Copy Expand all Collapse all `{ "backfill_completed": "2019-08-24T14:15:22Z", "created": "2019-08-24T14:15:22Z", "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "error_hints": { "details": [ null ], "reason": "Unexpected error" }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "notifications": { "webhook": { "topics": [ "delivery.success" ], "url": "http://example.com" } }, "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geometry": { }, "geometry_relation": "string", "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "status": "string", "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ], "updated": "2019-08-24T14:15:22Z", "_links": { "_self": "string" } }` ## [](#tag/subscriptions/operation/cancelSubscription)Cancel subscriptions Permanently cancel a subscription and stop delivery. Supported when a subscription is `pending`, `running`, `failed`, or `suspended`. ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### path Parameters | | | | ---------------------- | -------------- | | subscriptionIdrequired | string \ | ### Responses **200** Null response **400** Bad Request **401** Unauthenticated **403** Permission denied **500** Internal server error post/subscriptions/v1/{subscriptionId}/cancel https\://api.planet.com/subscriptions/v1/{subscriptionId}/cancel ### Response samples * 400 * 403 * 500 Content type application/json Example failedSchemaValidationfailedSchemaValidation Copy Expand all Collapse all `{ "error": { "details": [ ], "reason": "Could not find requested subscription" } }` ## [](#tag/subscriptions/operation/reactivateSubscription)Reactivate a subscription ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### path Parameters | | | | ---------------------- | -------------- | | subscriptionIdrequired | string \ | ### Responses **202** Subscription submitted for reactivation **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error post/subscriptions/v1/{subscriptionId}/reactivate https\://api.planet.com/subscriptions/v1/{subscriptionId}/reactivate ### Response samples * 400 * 403 * 409 * 500 Content type application/json Example failedSchemaValidationfailedSchemaValidation Copy Expand all Collapse all `{ "error": { "details": [ ], "reason": "Could not find requested subscription" } }` ## [](#tag/subscriptions/operation/suspendSubscription)Suspend a subscription ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### path Parameters | | | | ---------------------- | -------------- | | subscriptionIdrequired | string \ | ##### Request Body schema: application/json | | | | ------- | ----------------------------------------- | | details | stringDetails about the suspension reason | ### Responses **202** Subscription submitted for suspension **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error post/subscriptions/v1/{subscriptionId}/suspend https\://api.planet.com/subscriptions/v1/{subscriptionId}/suspend ### Request samples * Payload Content type application/json Copy `{ "details": "string" }` ### Response samples * 202 * 400 * 403 * 409 * 500 Content type application/json Copy Expand all Collapse all `{ "backfill_completed": "2019-08-24T14:15:22Z", "created": "2019-08-24T14:15:22Z", "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "error_hints": { "details": [ null ], "reason": "Unexpected error" }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "notifications": { "webhook": { "topics": [ "delivery.success" ], "url": "http://example.com" } }, "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geometry": { }, "geometry_relation": "string", "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "status": "string", "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ], "updated": "2019-08-24T14:15:22Z", "_links": { "_self": "string" } }` ## [](#tag/bulk)bulk ## [](#tag/bulk/operation/bulkCreateSubscriptions)Create multiple subscriptions ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### Request Body schema: application/jsonrequired | | | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | subscriptionsrequired | Array of objectsList of subscriptions to bulk create | | Arraydelivery GCS (object) or AWS (object) or Azure (object) or OCS (object) or GEE (object) or S3 Compatible (object) or Planet Destination (object) A delivery mechanism. hosting Planet Insights Platform Hosting (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 notifications object Specify notifications via webhook. source required object (Subscription Source) Source block to define the subscription source parameters tools 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 **202** Bulk create request submitted successfully **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error post/subscriptions/v1/bulk https\://api.planet.com/subscriptions/v1/bulk ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "subscriptions": [ { "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "hosting": { "parameters": { "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80", "configuration_id": "af0daaf4-983e-4703-a7ed-a10f146d6684", "create_configuration": true }, "type": "sentinel_hub" }, "name": "string", "notifications": { "webhook": { "topics": [ "delivery.success" ], "url": "http://example.com" } }, "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geometry": { }, "geometry_relation": "string", "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ] } ] }` ### Response samples * 202 * 400 * 403 * 409 * 500 Content type application/json Copy Expand all Collapse all `{ "_links": { "list": "string" } }` ## [](#tag/bulk/operation/bulkReactivateSubscriptions)Reactivate subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### query Parameters | | | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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. | ##### Request Body schema: application/json | | | | ------------------------- | ------------------------------------------------------------------------------------------------------- | | subscription\_idsrequired | Array of strings \ \[ 1 .. 1000 ] items \[ items \ ]List of subscription IDs to reactivate | ### Responses **202** Bulk subscriptions reactivation request received **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error **503** Service unavailable post/subscriptions/v1/reactivate https\://api.planet.com/subscriptions/v1/reactivate ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "subscription_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ] }` ### Response samples * 400 * 403 * 409 * 500 * 503 Content type application/json Copy Expand all Collapse all `{ "error": { "details": [ null ], "reason": "Reactivate request failed" } }` ## [](#tag/bulk/operation/bulkSuspendSubscriptions)Suspend subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### query Parameters | | | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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. | ##### Request Body schema: application/json | | | | ----------------- | ---------------------------------------------------------------------------------------------------- | | details | stringDetails about the suspension reason | | subscription\_ids | Array of strings \ \[ 1 .. 1000 ] items \[ items \ ]List of subscription IDs to suspend | ### Responses **202** Bulk subscriptions suspension request received **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error **503** Service unavailable post/subscriptions/v1/suspend https\://api.planet.com/subscriptions/v1/suspend ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "details": "string", "subscription_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ] }` ### Response samples * 400 * 403 * 409 * 500 * 503 Content type application/json Copy Expand all Collapse all `{ "error": { "details": [ null ], "reason": "Suspend request failed" } }` ## [](#tag/suspensionreactivation)suspension/reactivation ## [](#tag/suspensionreactivation/operation/bulkReactivateSubscriptions)Reactivate subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### query Parameters | | | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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. | ##### Request Body schema: application/json | | | | ------------------------- | ------------------------------------------------------------------------------------------------------- | | subscription\_idsrequired | Array of strings \ \[ 1 .. 1000 ] items \[ items \ ]List of subscription IDs to reactivate | ### Responses **202** Bulk subscriptions reactivation request received **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error **503** Service unavailable post/subscriptions/v1/reactivate https\://api.planet.com/subscriptions/v1/reactivate ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "subscription_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ] }` ### Response samples * 400 * 403 * 409 * 500 * 503 Content type application/json Copy Expand all Collapse all `{ "error": { "details": [ null ], "reason": "Reactivate request failed" } }` ## [](#tag/suspensionreactivation/operation/bulkSuspendSubscriptions)Suspend subscriptions for a given user ID, "all" subscriptions within the requesters organization, or specified subscription ids ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### query Parameters | | | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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. | ##### Request Body schema: application/json | | | | ----------------- | ---------------------------------------------------------------------------------------------------- | | details | stringDetails about the suspension reason | | subscription\_ids | Array of strings \ \[ 1 .. 1000 ] items \[ items \ ]List of subscription IDs to suspend | ### Responses **202** Bulk subscriptions suspension request received **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error **503** Service unavailable post/subscriptions/v1/suspend https\://api.planet.com/subscriptions/v1/suspend ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "details": "string", "subscription_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ] }` ### Response samples * 400 * 403 * 409 * 500 * 503 Content type application/json Copy Expand all Collapse all `{ "error": { "details": [ null ], "reason": "Suspend request failed" } }` ## [](#tag/suspensionreactivation/operation/reactivateSubscription)Reactivate a subscription ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### path Parameters | | | | ---------------------- | -------------- | | subscriptionIdrequired | string \ | ### Responses **202** Subscription submitted for reactivation **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error post/subscriptions/v1/{subscriptionId}/reactivate https\://api.planet.com/subscriptions/v1/{subscriptionId}/reactivate ### Response samples * 400 * 403 * 409 * 500 Content type application/json Example failedSchemaValidationfailedSchemaValidation Copy Expand all Collapse all `{ "error": { "details": [ ], "reason": "Could not find requested subscription" } }` ## [](#tag/suspensionreactivation/operation/suspendSubscription)Suspend a subscription ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### path Parameters | | | | ---------------------- | -------------- | | subscriptionIdrequired | string \ | ##### Request Body schema: application/json | | | | ------- | ----------------------------------------- | | details | stringDetails about the suspension reason | ### Responses **202** Subscription submitted for suspension **400** Bad Request **401** Unauthenticated **403** Permission denied **409** Conflict **500** Internal server error post/subscriptions/v1/{subscriptionId}/suspend https\://api.planet.com/subscriptions/v1/{subscriptionId}/suspend ### Request samples * Payload Content type application/json Copy `{ "details": "string" }` ### Response samples * 202 * 400 * 403 * 409 * 500 Content type application/json Copy Expand all Collapse all `{ "backfill_completed": "2019-08-24T14:15:22Z", "created": "2019-08-24T14:15:22Z", "delivery": { "parameters": { "bucket": "string", "credentials": "string", "path_prefix": "of-interest/" }, "type": "google_cloud_storage" }, "error_hints": { "details": [ null ], "reason": "Unexpected error" }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "notifications": { "webhook": { "topics": [ "delivery.success" ], "url": "http://example.com" } }, "source": { "parameters": { "asset_types": [ "string" ], "end_time": "2019-08-24T14:15:22Z", "filter": { }, "geometry": { }, "geometry_relation": "string", "item_types": [ "string" ], "publishing_stages": [ "standard", "finalized" ], "rrule": "FREQ=MONTHLY;BYMONTH=3,4,5,6,7", "start_time": "2019-08-24T14:15:22Z", "time_range_type": "published" }, "type": "catalog" }, "status": "string", "tools": [ { "parameters": { "aoi": { } }, "type": "clip" } ], "updated": "2019-08-24T14:15:22Z", "_links": { "_self": "string" } }` ## [](#tag/results)results ## [](#tag/results/operation/getResults)Get results for a given subscription ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### path Parameters | | | | ---------------------- | -------------- | | subscriptionIdrequired | string \ | ##### query Parameters | | | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page\_marker | string \ | | page\_size | integer \ \[ 0 .. 10000 ] | | status | stringEnum: "created" "queued" "processing" "failed" "success" | | created | stringEither 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 | stringEither 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 | stringEither 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 | stringEither 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. | | format | stringEnum: "csv" "json"The desired format for the response data. Defaults to JSON.Examples:- `format=csv`
- `format=json` | ### Responses **200** A page of results **400** Bad Request **401** Unauthenticated **403** Permission denied **500** Internal server error get/subscriptions/v1/{subscriptionId}/results https\://api.planet.com/subscriptions/v1/{subscriptionId}/results ### Response samples * 200 * 400 * 403 * 500 Content type application/json Copy Expand all Collapse all `{ "_links": { "_next": "string", "_self": "string" }, "completed": "2019-08-24T14:15:22Z", "created": "2019-08-24T14:15:22Z", "errors": { "details": [ "string" ], "reason": "string" }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "outputs": [ "string" ], "properties": { }, "status": "string", "updated": "2019-08-24T14:15:22Z" }` ## [](#tag/results/operation/getSubscriptionSummary)Get a summary of results for a given subscription ##### Authorizations: *ApiKeyAuth**BasicAuth* ##### path Parameters | | | | ---------------------- | -------------- | | subscriptionIdrequired | string \ | ### Responses **200** A subscription summary response **401** Unauthenticated **403** Permission denied **500** Internal server error get/subscriptions/v1/{subscriptionId}/summary https\://api.planet.com/subscriptions/v1/{subscriptionId}/summary ### Response samples * 200 * 403 * 500 Content type application/json Copy Expand all Collapse all `{ "results": { "created": 0, "failed": 0, "processing": 0, "queued": 0, "success": 0 }, "subscription": { "status": "string" } }`