Skip to main content

Bring Your Own COG API Reference

API docs by Redocly

API Reference (1.0.0)

Download OpenAPI specification:Download

This page contains the documentation on how to use sentinel hub services through API calls.

Note: This documentation is not complete

Collection

Create a collection

Authorizations:
OAuth2
Request Body schema: application/json
name
required
string
s3Bucket
required
string
isConfigured
boolean

It's set to true, if the collection has bands.

noData
number
object (BYOCCollectionAdditionalData)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "s3Bucket": "string",
  • "isConfigured": true,
  • "noData": 0,
  • "additionalData": {
    }
}

Response samples

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

Query collections

Authorizations:
OAuth2
query Parameters
count
integer <int32> [ 1 .. 100 ]

Number of items to retrieve.

viewtoken
string

When 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
string

Optional 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

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get a collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Responses

Response samples

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

Update a collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
Request Body schema: application/json
name
required
string
s3Bucket
required
string

Can only be changed if the collection is empty.

noData
number

If the value is not provided, the old one gets deleted.

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

Request samples

Content type
application/json
{
  • "name": "string",
  • "s3Bucket": "string",
  • "noData": 0,
  • "additionalData": {
    }
}

Response samples

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

Delete a collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Responses

Response samples

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

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
collectionId
required
string <uuid>
query Parameters
toCollection
required
string <uuid>

Responses

Response samples

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

Tile

Create a tile

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
Request Body schema: application/json
path
required
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.

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 <date-time>

The sensing time of the tile in ISO 8601 but without sub-millisecond precision.

object (BYOCTileAdditionalData)

Responses

Request samples

Content type
application/json
{
  • "path": "folder/prefix_(BAND)",
  • "tileGeometry": {
    },
  • "coverGeometry": {
    },
  • "sensingTime": "2019-08-24T14:15:22Z",
  • "additionalData": {
    }
}

Response samples

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

Get collection tiles

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
query Parameters
count
integer <int32> [ 1 .. 100 ]

Number of items to retrieve.

viewtoken
string

When 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
string
Enum: "created:asc" "created:desc"

Sort the tiles by created date in ascending or descending order.

path
string

Get 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

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get a tile

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>

Responses

Response samples

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

Update a tile

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>
Request Body schema: application/json
object or object (Geometry)
sensingTime
string or null <date-time>

The sensing time of the tile in ISO 8601 but without sub-millisecond precision.

Responses

Request samples

Content type
application/json
{
  • "coverGeometry": {
    },
  • "sensingTime": "2019-08-24T14:15:22Z"
}

Response samples

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

Delete a tile

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>

Responses

Response samples

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

Reingest a tile

Initiates reingestion of a tile.

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>

Responses

Response samples

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

List files of a tile in your Planet collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "0": "20241230_100706_56_24fd.json",
  • "1": "20241230_100706_56_24fd_metadata.json",
  • "2": "20241230_100706_56_24fd_ortho_analytic_4b_sr.tif",
  • "3": "20241230_100706_56_24fd_ortho_udm2.tif"
}

Retrieve a file from your Planet collection tile

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>
path
required
string

Filename with path as returned by the "List files of a tile" endpoint.

header Parameters
Range
string <RFC 7223>
Example: bytes=16384-23473

Optional byte range to retrieve part of a file according to RFC 7233. Typically used with large files to resume interrupted downloads.

Responses

Get size of a file from your Planet collection tile

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>
path
required
string

Filename with path as returned by the "List files of a tile" endpoint.

Responses

Last updated on