Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/byoc/reference/) # Bring Your Own COG API Reference * BYOC * Collection * postCreate a collection * getQuery collections * getGet a collection * putUpdate a collection * delDelete a collection * postCopy collection tiles * Tile * postCreate a tile * getGet collection tiles * getGet a tile * putUpdate a tile * delDelete a tile * postReingest a tile * getList files of a tile in your Planet collection * getRetrieve a file from your Planet collection tile * headGet size of a file from your Planet collection tile [API docs by Redocly](https://redocly.com/redoc/) # API Reference (1.0.0) Download OpenAPI specification:[Download](https://docs.planet.com/redocusaurus/sh-prod-byoc-api-spec.yaml) ## [](#tag/byoc_collection)Collection ## [](#tag/byoc_collection/operation/createByocCollection)Create a collection ##### Authorizations: *OAuth2* ##### Request Body schema: application/json | | | | ---------------- | ----------------------------------------------------- | | namerequired | string | | s3Bucketrequired | string | | isConfigured | booleanIt's set to true, if the collection has bands. | | noData | number | | additionalData | object (BYOCCollectionAdditionalData) | ### Responses **201** Collection created **400** Bad request **401** Unauthorized **403** Insufficient permissions **409** Conflict in the request post/byoc/v1/collections https\://services.sentinel-hub.com/byoc/v1/collections ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "name": "string", "s3Bucket": "string", "isConfigured": true, "noData": 0, "additionalData": { "bands": { "band1": { "source": "string", "bandIndex": 1, "bitDepth": 8, "sampleFormat": "UINT", "noData": 0 }, "band2": { "source": "string", "bandIndex": 1, "bitDepth": 8, "sampleFormat": "UINT", "noData": 0 } }, "extent": { "type": "Polygon", "coordinates": [ [ [ 0.1, 0.1 ] ] ] } } }` ### Response samples * 201 * 400 * 409 Content type application/json Copy Expand all Collapse all `{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9", "name": "string", "s3Bucket": "string", "isConfigured": true, "created": "2019-08-24T14:15:22Z", "noData": 0, "requiresMetadataUpdate": true, "additionalData": { "bands": { "band1": { "source": "string", "bandIndex": 1, "bitDepth": 8, "sampleFormat": "UINT", "noData": 0, "aliases": [ "string" ] }, "band2": { "source": "string", "bandIndex": 1, "bitDepth": 8, "sampleFormat": "UINT", "noData": 0, "aliases": [ "string" ] } }, "maxMetersPerPixel": 0, "extent": { "type": "Polygon", "coordinates": [ [ [ 0.1, 0.1 ] ] ] }, "hasSensingTimes": "YES", "fromSensingTime": "2019-08-24T14:15:22Z", "toSensingTime": "2019-08-24T14:15:22Z" } } }` ## [](#tag/byoc_collection/operation/getByocCollections)Query collections ##### Authorizations: *OAuth2* ##### query Parameters | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | count | integer \ \[ 1 .. 100 ]Number of items to retrieve. | | viewtoken | stringWhen the total number of items is larger than *count*, the response contains *viewtoken*. This *viewtoken* can be used in the next request to retrieve the next page of items.The next page can be retrieved by repeating the query. However, replace your URL with the next URL in the returned links object. | | search | stringOptional search query. Either a single word to search for or multiple words separated by the `\|` (or) and `&` (and) operators. If omitted, all items are returned. | ### Responses **200** Successful response **401** Unauthorized **403** Insufficient permissions get/byoc/v1/collections https\://services.sentinel-hub.com/byoc/v1/collections ### Response samples * 200 Content type application/json Copy Expand all Collapse all `{ "data": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9", "name": "string", "s3Bucket": "string", "isConfigured": true, "created": "2019-08-24T14:15:22Z", "noData": 0, "requiresMetadataUpdate": true, "additionalData": { "bands": { "band1": { "source": "string", "bandIndex": 1, "bitDepth": 8, "sampleFormat": "UINT", "noData": 0, "aliases": [ "string" ] }, "band2": { "source": "string", "bandIndex": 1, "bitDepth": 8, "sampleFormat": "UINT", "noData": 0, "aliases": [ "string" ] } }, "maxMetersPerPixel": 0, "extent": { "type": "Polygon", "coordinates": [ [ [ 0.1, 0.1 ] ] ] }, "hasSensingTimes": "YES", "fromSensingTime": "2019-08-24T14:15:22Z", "toSensingTime": "2019-08-24T14:15:22Z" } } ], "links": { "currentToken": "string", "nextToken": "string", "previousToken": "string", "@id": "http://example.com", "next": "http://example.com", "previous": "http://example.com" } }` ## [](#tag/byoc_collection/operation/getByocCollectionById)Get a collection ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | ### Responses **200** Successful response **401** Unauthorized **403** Insufficient permissions **404** Not found get/byoc/v1/collections/{collectionId} https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId} ### Response samples * 200 * 404 Content type application/json Copy Expand all Collapse all `{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9", "name": "string", "s3Bucket": "string", "isConfigured": true, "created": "2019-08-24T14:15:22Z", "noData": 0, "requiresMetadataUpdate": true, "additionalData": { "bands": { "band1": { "source": "string", "bandIndex": 1, "bitDepth": 8, "sampleFormat": "UINT", "noData": 0, "aliases": [ "string" ] }, "band2": { "source": "string", "bandIndex": 1, "bitDepth": 8, "sampleFormat": "UINT", "noData": 0, "aliases": [ "string" ] } }, "maxMetersPerPixel": 0, "extent": { "type": "Polygon", "coordinates": [ [ [ 0.1, 0.1 ] ] ] }, "hasSensingTimes": "YES", "fromSensingTime": "2019-08-24T14:15:22Z", "toSensingTime": "2019-08-24T14:15:22Z" } } }` ## [](#tag/byoc_collection/operation/updateByocCollectionById)Update a collection ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | ##### Request Body schema: application/json | | | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | namerequired | string | | s3Bucketrequired | stringCan only be changed if the collection is empty. | | noData | numberIf the value is not provided, the old one gets deleted. | | additionalData | object (BYOCCollectionAdditionalData)If provided, overwrites the current bands property of the collection:- to rename band(s), provide the current value of the "bands" property with only the name(s) of one or more bands changed
- to set noData value(s), provide the current value of the "bands" property with only the noData value(s) of one or more bands changed
- to remove band(s), provide the current value of the "bands" property but leave out the band(s) you wish to remove
- to remove all bands, you must first empty the collection, then provide "additionalData" without the "bands" property or with an empty "bands" property.Keep in mind that:- bands cannot be added nor their other properties ("bitDepth", "bandIndex", etc) changed once you add a tile. - once sample format is set you cannot change it, and tiles ingested from then on need be in the set sample format.If "additionalData" is omitted, the bands will not be changed. | ### Responses **204** Collection updated **400** Bad request **401** Unauthorized **403** Insufficient permissions **404** Not found **409** Conflict in the request put/byoc/v1/collections/{collectionId} https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId} ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "name": "string", "s3Bucket": "string", "noData": 0, "additionalData": { "bands": { "band1": { "source": "string", "bandIndex": 1, "bitDepth": 8, "sampleFormat": "UINT", "noData": 0 }, "band2": { "source": "string", "bandIndex": 1, "bitDepth": 8, "sampleFormat": "UINT", "noData": 0 } }, "extent": { "type": "Polygon", "coordinates": [ [ [ 0.1, 0.1 ] ] ] } } }` ### Response samples * 400 * 404 * 409 Content type application/json Copy Expand all Collapse all `{ "error": { "status": 0, "reason": "string", "message": "string", "code": "COMMON_BAD_PAYLOAD", "errors": { } } }` ## [](#tag/byoc_collection/operation/deleteByocCollectionById)Delete a collection ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | ### Responses **204** Collection deleted **401** Unauthorized **403** Insufficient permissions **404** Not found delete/byoc/v1/collections/{collectionId} https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId} ### Response samples * 404 Content type application/json Copy Expand all Collapse all `{ "error": { "status": 0, "reason": "string", "message": "string", "code": "COMMON_BAD_PAYLOAD", "errors": { } } }` ## [](#tag/byoc_collection/operation/copyByocCollectionTiles)Copy collection tiles Copies ingested tiles from one collection to another, but only those whose path isn't present in the target collection. You need to have access to both source and target collections, and target collection needs to have either the same band names and types, or it should have no bands. ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | ##### query Parameters | | | | -------------------- | -------------- | | toCollectionrequired | string \ | ### Responses **204** Tiles copied **401** Unauthorized **403** Insufficient permissions **404** Not found post/byoc/v1/collections/{collectionId}/copyTiles https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId}/copyTiles ### Response samples * 404 Content type application/json Copy Expand all Collapse all `{ "error": { "status": 0, "reason": "string", "message": "string", "code": "COMMON_BAD_PAYLOAD", "errors": { } } }` ## [](#tag/byoc_tile)Tile ## [](#tag/byoc_tile/operation/createByocCollectionTile)Create a tile ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | ##### Request Body schema: application/json | | | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pathrequired | string^(\[^/]\(/?\[^/])\*)?$The path within the bucket where the files are. Can also use the '(BAND)' placeholder when the file names contain more than just the band name. | | coverGeometry | Polygon (object) or MultiPolygon (object)The geometry as GeoJSON which outlines the area that has data.If it isn't specified, it is automatically set to the intersection of all file bounding boxes.You may specify this in any CRS, however it will be converted to CRS84.After ingestion is complete, this stays in CRS84 on our system, however, for you convenience, we convert and return this in the CRS of the tile. | | sensingTime | string or null \The sensing time of the tile in ISO 8601 but without sub-millisecond precision. | | additionalData | object (BYOCTileAdditionalData) | ### Responses **201** Tile created **400** Bad request **401** Unauthorized **403** Insufficient permissions **409** Conflict in the request post/byoc/v1/collections/{collectionId}/tiles https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId}/tiles ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "path": "folder/prefix_(BAND)", "tileGeometry": { "type": "Polygon", "coordinates": [ [ [ 0.1, 0.1 ] ] ] }, "coverGeometry": { "type": "Polygon", "coordinates": [ [ [ 14.000701904296873, 46.23685258143992 ], [ 13.822174072265625, 46.09037664604301 ], [ 14.113311767578125, 45.85080395917834 ], [ 14.55963134765625, 46.038922598236 ], [ 14.441528320312498, 46.28717293114449 ], [ 14.17236328125, 46.29191774991382 ], [ 14.000701904296873, 46.23685258143992 ] ] ] }, "sensingTime": "2019-08-24T14:15:22Z", "additionalData": { "failedIngestionCause": "string", "warnings": "string" } }` ### Response samples * 201 * 400 * 409 Content type application/json Copy Expand all Collapse all `{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "path": "folder/prefix_(BAND)", "tileGeometry": { "type": "Polygon", "coordinates": [ [ [ 0.1, 0.1 ] ] ] }, "coverGeometry": { "type": "Polygon", "coordinates": [ [ [ 14.000701904296873, 46.23685258143992 ], [ 13.822174072265625, 46.09037664604301 ], [ 14.113311767578125, 45.85080395917834 ], [ 14.55963134765625, 46.038922598236 ], [ 14.441528320312498, 46.28717293114449 ], [ 14.17236328125, 46.29191774991382 ], [ 14.000701904296873, 46.23685258143992 ] ] ] }, "sensingTime": "2019-08-24T14:15:22Z", "status": "WAITING", "additionalData": { "failedIngestionCause": "string", "warnings": "string" }, "created": "2019-08-24T14:15:22Z" } }` ## [](#tag/byoc_tile/operation/getByocCollectionTiles)Get collection tiles ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | ##### query Parameters | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | count | integer \ \[ 1 .. 100 ]Number of items to retrieve. | | viewtoken | stringWhen the total number of items is larger than *count*, the response contains *viewtoken*. This *viewtoken* can be used in the next request to retrieve the next page of items.The next page can be retrieved by repeating the query. However, replace your URL with the next URL in the returned links object. | | sort | stringEnum: "created:asc" "created:desc"Sort the tiles by created date in ascending or descending order. | | path | stringGet the tile with the exact path. Returns a single tile or no tile, if there's none with given path. | | status | string (BYOCTileStatus)Enum: "WAITING" "QUEUED" "INGESTING" "INGESTED" "FAILED"Get only the files with the given status. | ### Responses **200** Successful response **401** Unauthorized **403** Insufficient permissions get/byoc/v1/collections/{collectionId}/tiles https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId}/tiles ### Response samples * 200 Content type application/json Copy Expand all Collapse all `{ "data": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "path": "folder/prefix_(BAND)", "tileGeometry": { "type": "Polygon", "coordinates": [ [ [ 0.1, 0.1 ] ] ] }, "coverGeometry": { "type": "Polygon", "coordinates": [ [ [ 14.000701904296873, 46.23685258143992 ], [ 13.822174072265625, 46.09037664604301 ], [ 14.113311767578125, 45.85080395917834 ], [ 14.55963134765625, 46.038922598236 ], [ 14.441528320312498, 46.28717293114449 ], [ 14.17236328125, 46.29191774991382 ], [ 14.000701904296873, 46.23685258143992 ] ] ] }, "sensingTime": "2019-08-24T14:15:22Z", "status": "WAITING", "additionalData": { "failedIngestionCause": "string", "warnings": "string" }, "created": "2019-08-24T14:15:22Z" } ], "links": { "currentToken": "string", "nextToken": "string", "previousToken": "string", "@id": "http://example.com", "next": "http://example.com", "previous": "http://example.com" } }` ## [](#tag/byoc_tile/operation/getByocCollectionTileById)Get a tile ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | | tileIdrequired | string \ | ### Responses **200** Successful response **401** Unauthorized **403** Insufficient permissions **404** Not found get/byoc/v1/collections/{collectionId}/tiles/{tileId} https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId}/tiles/{tileId} ### Response samples * 200 * 404 Content type application/json Copy Expand all Collapse all `{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "path": "folder/prefix_(BAND)", "tileGeometry": { "type": "Polygon", "coordinates": [ [ [ 0.1, 0.1 ] ] ] }, "coverGeometry": { "type": "Polygon", "coordinates": [ [ [ 14.000701904296873, 46.23685258143992 ], [ 13.822174072265625, 46.09037664604301 ], [ 14.113311767578125, 45.85080395917834 ], [ 14.55963134765625, 46.038922598236 ], [ 14.441528320312498, 46.28717293114449 ], [ 14.17236328125, 46.29191774991382 ], [ 14.000701904296873, 46.23685258143992 ] ] ] }, "sensingTime": "2019-08-24T14:15:22Z", "status": "WAITING", "additionalData": { "failedIngestionCause": "string", "warnings": "string" }, "created": "2019-08-24T14:15:22Z" } }` ## [](#tag/byoc_tile/operation/updateByocCollectionTileById)Update a tile ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | | tileIdrequired | string \ | ##### Request Body schema: application/json | | | | ------------- | ---------------------------------------------------------------------------------------------------------- | | coverGeometry | object or object (Geometry) | | sensingTime | string or null \The sensing time of the tile in ISO 8601 but without sub-millisecond precision. | ### Responses **204** Tile updated **400** Bad request **401** Unauthorized **403** Insufficient permissions **404** Not found **409** Conflict in the request put/byoc/v1/collections/{collectionId}/tiles/{tileId} https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId}/tiles/{tileId} ### Request samples * Payload Content type application/json Copy Expand all Collapse all `{ "coverGeometry": { "type": "Polygon", "coordinates": [ [ [ 14.000701904296873, 46.23685258143992 ], [ 13.822174072265625, 46.09037664604301 ], [ 14.113311767578125, 45.85080395917834 ], [ 14.55963134765625, 46.038922598236 ], [ 14.441528320312498, 46.28717293114449 ], [ 14.17236328125, 46.29191774991382 ], [ 14.000701904296873, 46.23685258143992 ] ] ] }, "sensingTime": "2019-08-24T14:15:22Z" }` ### Response samples * 400 * 404 * 409 Content type application/json Copy Expand all Collapse all `{ "error": { "status": 0, "reason": "string", "message": "string", "code": "COMMON_BAD_PAYLOAD", "errors": { } } }` ## [](#tag/byoc_tile/operation/deleteByocCollectionTileById)Delete a tile ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | | tileIdrequired | string \ | ### Responses **204** Tile deleted **401** Unauthorized **403** Insufficient permissions **404** Not found delete/byoc/v1/collections/{collectionId}/tiles/{tileId} https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId}/tiles/{tileId} ### Response samples * 404 Content type application/json Copy Expand all Collapse all `{ "error": { "status": 0, "reason": "string", "message": "string", "code": "COMMON_BAD_PAYLOAD", "errors": { } } }` ## [](#tag/byoc_tile/operation/reingestByocCollectionTileById)Reingest a tile Initiates reingestion of a tile. ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | | tileIdrequired | string \ | ### Responses **204** Reingestion initiated. **400** Bad request **401** Unauthorized **403** Insufficient permissions **404** Not found post/byoc/v1/collections/{collectionId}/tiles/{tileId}/reingest https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId}/tiles/{tileId}/reingest ### Response samples * 400 * 404 Content type application/json Copy Expand all Collapse all `{ "error": { "status": 0, "reason": "string", "message": "string", "code": "COMMON_BAD_PAYLOAD", "errors": { } } }` ## [](#tag/byoc_tile/operation/listByocTileFiles)List files of a tile in your Planet collection ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | -------------- | | collectionIdrequired | string \ | | tileIdrequired | string \ | ### Responses **200** Successful response **401** Unauthorized **403** Insufficient permissions **404** Collection or tile does not exists, or collection was not created by a Planet Subscription/Order. get/byoc/v1/collections/{collectionId}/tiles/{tileId}/files https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId}/tiles/{tileId}/files ### Response samples * 200 Content type application/json Copy `[ "20241230_100706_56_24fd.json", "20241230_100706_56_24fd_metadata.json", "20241230_100706_56_24fd_ortho_analytic_4b_sr.tif", "20241230_100706_56_24fd_ortho_udm2.tif" ]` ## [](#tag/byoc_tile/operation/getByocTileFile)Retrieve a file from your Planet collection tile ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | ---------------------------------------------------------------------------- | | collectionIdrequired | string \ | | tileIdrequired | string \ | | pathrequired | stringFilename with path as returned by the "List files of a tile" endpoint. | ##### header Parameters | | | | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Range | string \Example: bytes=16384-23473Optional byte range to retrieve part of a file according to [RFC 7233](https://datatracker.ietf.org/doc/html/rfc7233#section-3.1). Typically used with large files to resume interrupted downloads. | ### Responses **200** Successful response **206** Partial response in case partial retrieval was requested with the `Range` request header **401** Unauthorized **403** Insufficient permissions **404** Collection, tile, or file does not exists, or collection was not created by a Planet Subscription/Order. get/byoc/v1/collections/{collectionId}/tiles/{tileId}/files/{path} https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId}/tiles/{tileId}/files/{path} ## [](#tag/byoc_tile/operation/headByocTileFile)Get size of a file from your Planet collection tile ##### Authorizations: *OAuth2* ##### path Parameters | | | | -------------------- | ---------------------------------------------------------------------------- | | collectionIdrequired | string \ | | tileIdrequired | string \ | | pathrequired | stringFilename with path as returned by the "List files of a tile" endpoint. | ### Responses **200** Successful response **401** Unauthorized **403** Insufficient permissions **404** Collection, tile, or file does not exists, or collection was not created by a Planet Subscription/Order. head/byoc/v1/collections/{collectionId}/tiles/{tileId}/files/{path} https\://services.sentinel-hub.com/byoc/v1/collections/{collectionId}/tiles/{tileId}/files/{path}