API docs by Redocly

Cesium ion Self-Hosted (v1)

Overview

The REST API enables you to to integrate Cesium ion into your own applications and workflows.

Authentication

When single sign-on authentication is disabled, endpoints work without an access token.

When single sign-on authentication is enabled, all Cesium ion endpoints require an access token provided as a query parameter named access_token or in the Authorization header of the request. ion uses the OAuth 2.0 Bearer <access_token> format and supports the following scopes:

Public Scopes

Scope Description
assets:read Read metadata and access the tiled data for individual assets in the account.

Private Scopes

The following scopes provide potentially sensitive information or otherwise allow changes to be made to your account. They should only be used in cases where the token can be kept secret and unavailable to public clients.

Scope Description
assets:list List the metadata for all assets available to the account.
assets:write Create, modify, and delete assets in the account.
profile:read Read your username, email address, avatar, and storage quota.
tokens:read Read token metadata and list all tokens for the account.
tokens:write Create, modify, and delete tokens in the account.
exports:read List asset exports.
exports:write Export assets.
archives:read List and download asset archives.
archives:write Create and delete asset archives.

Cesium ion also supports OAuth 2.0 authorizationCode flow if you want to allow users to bring their own ion account into your application.

Assets

Whether you have imagery, terrain, 3D buildings, point clouds, photogrammetry, or one of the many other types of data we support, ion creates what we refer to as an asset.

There are seven types of assets:

Value Description
3DTILES A 3D Tiles tileset
GLTF A glTF model
IMAGERY An TMS and WMTS compatible imagery layer
TERRAIN A quantized-mesh-1.0 terrain tileset
CZML A CZML dataset
KML A KML or KMZ dataset
GEOJSON A GeoJSON dataset

The Assets API provides a mechanism to discover, create, and stream these assets into your own applications.

List assets

Retrieves all available assets, splitting the result across multiple requests using pagination.

After receiving the initial page of assets, you can request the next and previous pages using the RFC 5988 formatted strings contained in the Link header with the next and prev relations. The process of fetching the next page of assets can be repeated until the client receives a response with no link header or no next relation in the link header, which means all assets have been returned. The link urls should be treated as an opaque link as the actual format may change at any time.

Authorizations:
OAuth2
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

The maximum numbers of assets to return. Receiving fewer assets should not be interpreted as the end of the collection. The end of the collection is reached when the response does not contain a link header.

page
integer >= 1
Default: 1
Example: page=3

The page number.

search
string
Example: search=roads

One or more keywords separated by whitespace by which to filter the list of assets. The assets returned will contain each keyword of the search strings in either the name, description, or attribution.

sortBy
string
Default: "id"
Enum: "ID" "NAME" "DESCRIPTION" "BYTES" "TYPE" "STATUS" "DATE_ADDED"
Example: sortBy=NAME

The property by which to sort the results. If undefined, assets are sorted by id.

sortOrder
string
Default: "ASC"
Enum: "ASC" "DESC"
Example: sortOrder=ASC

The order in which to sort the results. If undefined, assets are sorted ascending.

status
Array of strings (AssetStatus)
Items Enum: "AWAITING_FILES" "NOT_STARTED" "IN_PROGRESS" "COMPLETE" "ERROR" "DATA_ERROR"
Example: status=COMPLETE

One or more asset statuses by which to filter the list of assets. If undefined, returns assets with any status.

type
Array of strings (AssetType)
Items Enum: "3DTILES" "GLTF" "IMAGERY" "TERRAIN" "KML" "CZML" "GEOJSON"
Example: type=3DTILES

One ore more asset types by which to filter the list of assets. If undefined, returns assets of any type.

Responses

Response Headers
link
string

An RFC 5988 formatted string with a relation type of next which points to the next page of data on the server, if it exists, and a relation type of prev which points to the previous page of data on the server, if it exists. This url should be treated as an opaque link as the actual format may change at any time.

Response Schema: application/json
Array of objects (Asset Metadata)

A page of assets.

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a new asset

Uploading data to ion is a four step process:

  1. Provide ion information about your data.
  2. Upload your data to the provided ion URL.
  3. Notify ion that you are finished uploading data so that it can begin tiling.
  4. Optionally monitor the tiling status until the asset is ready for use.
Authorizations:
OAuth2
Request Body schema: application/json
required
name
required
string (AssetName)

The name of this asset.

description
string (AssetDescription)

A Markdown string describing this asset.

attribution
string (AssetAttribution)

A Markdown compatible string containing any required attribution for this asset. Clients will be required to display this attribution to end users.

type
required
string (AssetType)
Enum: "3DTILES" "GLTF" "IMAGERY" "TERRAIN" "KML" "CZML" "GEOJSON"

This asset's type.

percentComplete
integer [ 0 .. 100 ]

The percentage progress of the tiling pipeline preparing this asset.

required
object (AssetOptions)

Contains options specific to the type of source data being uploaded.

object (AssetFrom)

When supplied, contains options for tiling source files hosted by external services. AWS S3 functionality must be enabled on the server for this option to be available.

Responses

Response Schema: application/json
object

Contains information required for uploading source data to ion's storage.

object

Contains information required for notifying ion once all source data has been uploaded. This property is undefined when importing source files from third-party sources.

object (Asset Metadata)

Request samples

Content type
application/json
{
  • "name": "The Earth At Night",
  • "description": "The Earth at night, also known as [The Black Marble](https://earthobservatory.nasa.gov/Features/NightLights/).",
  • "attribution": "[NASA](https://earthobservatory.nasa.gov/image-use-policy)",
  • "type": "3DTILES",
  • "options": {
    }
}

Response samples

Content type
application/json
{}

Get info about an asset

Retrieves metadata information about a specific asset.

Authorizations:
OAuth2
path Parameters
assetId
required
integer (AssetIdentifier)
Example: 3812

The asset identifier on which to perform the operation.

Responses

Response Schema: application/json
id
integer (AssetIdentifier)

The unique identifier for this asset.

name
required
string (AssetName)

The name of this asset.

description
string (AssetDescription)

A Markdown string describing this asset.

attribution
string (AssetAttribution)

A Markdown compatible string containing any required attribution for this asset. Clients will be required to display this attribution to end users.

type
required
string (AssetType)
Enum: "3DTILES" "GLTF" "IMAGERY" "TERRAIN" "KML" "CZML" "GEOJSON"

This asset's type.

bytes
integer >= 0

The number of bytes this asset occupies in the user's account.

dateAdded
string <date-time>

The date and time that this asset was created in RFC 3339 format.

status
string (AssetStatus)
Enum: "AWAITING_FILES" "NOT_STARTED" "IN_PROGRESS" "COMPLETE" "ERROR" "DATA_ERROR"

Describes the state of the asset during the upload and tiling processes:

Value Description
AWAITING_FILES The asset has been created but the server is waiting for source data to be uploaded.
NOT_STARTED The server was notified that all source data was uploaded and is waiting for the tiling process to start.
IN_PROGRESS The source data is being tiled, see percentComplete to monitor progress.
COMPLETE The asset was tiled successfully.
DATA_ERROR The uploaded source data was invalid or unsupported.
ERROR An internal error occurred during the tiling process. Please contact support@cesium.com.
percentComplete
integer [ 0 .. 100 ]

The percentage progress of the tiling pipeline preparing this asset.

exportable
boolean

true if this asset can be used with the exports API, false otherwise.

Response samples

Content type
application/json
{
  • "id": 3812,
  • "name": "The Earth At Night",
  • "description": "The Earth at night, also known as [The Black Marble](https://earthobservatory.nasa.gov/Features/NightLights/).",
  • "attribution": "[NASA](https://earthobservatory.nasa.gov/image-use-policy)",
  • "type": "3DTILES",
  • "bytes": 8675309,
  • "dateAdded": "2019-03-19T13:17:02.838Z",
  • "status": "COMPLETE",
  • "percentComplete": 100,
  • "exportable": true
}

Modify asset info

Updates the name, description, or attribution of an asset. Does not support assets subscribed to from the Asset Depot.

Authorizations:
OAuth2
path Parameters
assetId
required
integer (AssetIdentifier)
Example: 3812

The asset identifier on which to perform the operation.

Request Body schema: application/json
required
name
string (AssetName)

The name of this asset.

description
string (AssetDescription)

A Markdown string describing this asset.

attribution
string (AssetAttribution)

A Markdown compatible string containing any required attribution for this asset. Clients will be required to display this attribution to end users.

Responses

Request samples

Content type
application/json
{
  • "name": "The Earth At Night",
  • "description": "The Earth at night, also known as [The Black Marble](https://earthobservatory.nasa.gov/Features/NightLights/).",
  • "attribution": "[NASA](https://earthobservatory.nasa.gov/image-use-policy)"
}

Delete an asset

Deletes an asset. Does not support assets subscribed to from the Asset Depot.

Authorizations:
OAuth2
path Parameters
assetId
required
integer (AssetIdentifier)
Example: 3812

The asset identifier on which to perform the operation.

Responses

Access tiles

Retrieves information and credentials that allow you to access the tiled asset data for visualization and analysis.

If you're using ion assets in CesiumJS, there's no need to use this endpoint directly. The CesiumJS API has built in support for ingesting ion assets. Check out the below CesiumJS code examples:

If you're implementing ion asset visualization in a non-CesiumJS rendering engine or application, you'll find the below specifications links useful:

Authorizations:
OAuth2
path Parameters
assetId
required
integer (AssetIdentifier)
Example: 3812

The asset identifier on which to perform the operation.

Responses

Archives

Archives allow you to make downloadable versions of your assets for offline use or hosting outside of Cesium ion.

With archives you can:

  • Create a full copy of an asset as a zip file
  • Clip out a subset of a 3D Tiles, terrain, or imagery asset as a glTF model or 3D Tiles 1.1 zip file

Full asset downloads do not support Asset Depot assets or terrain assets which use a base terrain. Check the archivable property of the asset to detect availability. Full archives are turned off by default and require you to opt into the feature in your values.yaml file.

Clips support both your assets and most Asset Depot assets, but have additional restrictions:

  • Clips can only be made from 3D Tiles or terrain and imagery assets.
  • Clips have a geographic size limit of 200 km^2
  • The number of Clips you can make with Asset Depot assets within a billing period is limited by your plan. See Cesium ion pricing plans for specific limits.

Individual archives count against your account storage quota. If your account goes over storage quota, additional archives will not be possible without upgrading your plan or deleting existing archives or assets to free up space.

List archives

Retrieves all archives

Authorizations:
OAuth2
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

The maximum numbers of archives to return. Receiving fewer archives should not be interpreted as the end of the collection. The end of the collection is reached when the response does not contain a link header.

page
integer >= 1
Default: 1
Example: page=3

The page number.

search
string
Example: search=roads

One or more keywords separated by whitespace by which to filter the list of archives. The assets returned will contain each keyword of the search strings in either the archive name, or the asset names.

sortBy
string
Default: "ID"
Enum: "ID" "BYTES" "STATUS" "DATE_ADDED"
Example: sortBy=BYTES

The property by which to sort the results. If undefined, archives are sorted by id.

sortOrder
string
Default: "ASC"
Enum: "ASC" "DESC"
Example: sortOrder=ASC

The order in which to sort the results. If undefined, assets are sorted ascending.

assetId
integer (AssetIdentifier)
Example: assetId=3812

The asset to find archives for. The returned archives will contain the given asset id.

clipped
boolean
Example: clipped=true

Limit to only clipped or unclipped archives. If undefined, include all archives.

Responses

Response Headers
link
string

An RFC 5988 formatted string with a relation type of next which points to the next page of data on the server, if it exists, and a relation type of prev which points to the previous page of data on the server, if it exists. This url should be treated as an opaque link as the actual format may change at any time.

Response Schema: application/json
Array of objects (Archive Metadata)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create an archive

Creates a new archive.

Authorizations:
OAuth2
Request Body schema: application/json
required
type
string (ArchiveType)

Describes the type of clip region for this archive:

Value Description
FULL The archive contains the full data of the asset. Only valid for use with a single asset. You must also enable to opt in to full archives in your values.yaml file
CLIP_LATITUDE_LONGITUDE_RECTANGLE Archive contains data around a rectangle defined by latitude and longitude.
assetIds
Array of integers (AssetIdentifier)

If creating a clipped archive this may be a single 3D Tiles asset, or IMAGERY and TERRAIN asset pair. All assets must be clippable. See the requirements for clipping.

For a full archive of a single asset the asset must be marked as archivable.

format
string (ArchiveFormat)
Enum: "ZIP" "TILESET" "GLTF"

Specifies the format of the archive:

Value Description
ZIP Create a .zip archive containing a full copy of the asset as-hosted on ion. Used only type FULL
TILESET Create a .zip archive containing a 3D Tiles 1.1 tileset. Used only with type CLIP_LATITUDE_LONGITUDE_RECTANGLE
GLTF Create a GLB file. Used only with type CLIP_LATITUDE_LONGITUDE_RECTANGLE

Responses

Response Schema: application/json
id
integer (ArchiveIdentifier)

The unique identifier of this archive.

name
string
assetIds
Array of integers (AssetIdentifier)
format
string (ArchiveFormat)
Enum: "ZIP" "TILESET" "GLTF"

Specifies the format of the archive:

Value Description
ZIP Create a .zip archive containing a full copy of the asset as-hosted on ion. Used only type FULL
TILESET Create a .zip archive containing a 3D Tiles 1.1 tileset. Used only with type CLIP_LATITUDE_LONGITUDE_RECTANGLE
GLTF Create a GLB file. Used only with type CLIP_LATITUDE_LONGITUDE_RECTANGLE
status
string (ArchiveStatus)
Enum: "NOT_STARTED" "IN_PROGRESS" "COMPLETE" "ERROR"

Describes the state of the asset during the archival processes:

Value Description
NOT_STARTED The server was notified that the asset is to be archived and is waiting for the archival process to start.
IN_PROGRESS The asset is being archived, see bytesArchived to monitor progress.
COMPLETE The asset was archived successfully.
ERROR An error occurred during the archival process. Please retry the archival process again.
bytesArchived
integer >= 0

The total number of bytes of the archive that has been processed.

type
string (ArchiveType)

Describes the type of clip region for this archive:

Value Description
FULL The archive contains the full data of the asset. Only valid for use with a single asset. You must also enable to opt in to full archives in your values.yaml file
CLIP_LATITUDE_LONGITUDE_RECTANGLE Archive contains data around a rectangle defined by latitude and longitude.

Request samples

Content type
application/json
Example
{
  • "assetIds": [
    ],
  • "format": "ZIP",
  • "type": "FULL"
}

Response samples

Content type
application/json
{
  • "id": 12,
  • "name": "Courtyard",
  • "assetIds": [
    ],
  • "type": "FULL",
  • "format": "ZIP",
  • "status": "IN_PROGRESS",
  • "bytesArchived": 17
}

Get info about an archive

Retrieves the metadata information about a specific asset archive.

Authorizations:
OAuth2

Responses

Response Schema: application/json
id
integer (ArchiveIdentifier)

The unique identifier of this archive.

name
string
assetIds
Array of integers (AssetIdentifier)
format
string (ArchiveFormat)
Enum: "ZIP" "TILESET" "GLTF"

Specifies the format of the archive:

Value Description
ZIP Create a .zip archive containing a full copy of the asset as-hosted on ion. Used only type FULL
TILESET Create a .zip archive containing a 3D Tiles 1.1 tileset. Used only with type CLIP_LATITUDE_LONGITUDE_RECTANGLE
GLTF Create a GLB file. Used only with type CLIP_LATITUDE_LONGITUDE_RECTANGLE
status
string (ArchiveStatus)
Enum: "NOT_STARTED" "IN_PROGRESS" "COMPLETE" "ERROR"

Describes the state of the asset during the archival processes:

Value Description
NOT_STARTED The server was notified that the asset is to be archived and is waiting for the archival process to start.
IN_PROGRESS The asset is being archived, see bytesArchived to monitor progress.
COMPLETE The asset was archived successfully.
ERROR An error occurred during the archival process. Please retry the archival process again.
bytesArchived
integer >= 0

The total number of bytes of the archive that has been processed.

type
string (ArchiveType)

Describes the type of clip region for this archive:

Value Description
FULL The archive contains the full data of the asset. Only valid for use with a single asset. You must also enable to opt in to full archives in your values.yaml file
CLIP_LATITUDE_LONGITUDE_RECTANGLE Archive contains data around a rectangle defined by latitude and longitude.

Response samples

Content type
application/json
Example
{
  • "id": 10,
  • "name": "string",
  • "assetIds": [
    ],
  • "format": "ZIP",
  • "status": "COMPLETE",
  • "bytesArchived": 1024,
  • "type": "FULL"
}

Update an archive name

Updates the name of a clipped archive. This is not valid for an archive without a clipRegion.

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

The new name of the archive

Responses

Request samples

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

Delete an archive

Deletes an asset archive.

Authorizations:
OAuth2

Responses

Download an archive

Fetches the asset archive as an octet stream. The archive is available to be downloaded once ion finishes archiving processing.

Authorizations:
OAuth2

Responses

Response Schema: application/octet-stream
any <binary>

Tokens

The Tokens API provides a mechanism to create and manage access tokens. Access tokens are used to give applications access to your ion account, including access to stream your ion assets.

Every account has a single default token with the assets:read scope. This token cannot be modified or deleted, and provides read access to all assets associated with that user's ion account.

List tokens

Retrieves all available tokens, splitting the result across multiple requests using pagination.

After receiving the initial page of tokens, you can request the next and previous pages using the RFC 5988 formatted strings contained in the Link header with the next and prev relations. The process of fetching the next page of tokens can be repeated until the client receives a response with no link header or no next relation in the link header, which means all tokens have been returned. The link urls should be treated as an opaque link as the actual format may change at any time.

Authorizations:
OAuth2
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

The maximum numbers of tokens to return. Receiving fewer tokens should not be interpreted as the end of the collection. The end of the collection is reached when the response does not contain a link header.

page
integer >= 1
Default: 1
Example: page=3

The page number.

search
string
Example: search=roads

One or more keywords separated by whitespace by which to filter the list of tokens. The token name will contain each keyword of the search string.

sortBy
string
Enum: "NAME" "LAST_USED"
Example: sortBy=NAME

The property by which to sort the results.

sortOrder
string
Default: "ASC"
Enum: "ASC" "DESC"
Example: sortOrder=ASC

The order in which to sort the results. If undefined, tokens are sorted ascending.

Responses

Response Headers
link
string

An RFC 5988 formatted string with a relation type of next which points to the next page of data on the server, if it exists, and a relation type of prev which points to the previous page of data on the server, if it exists. This url should be treated as an opaque link as the actual format may change at any time.

Response Schema: application/json
Array of objects (Token Metadata)

A page of tokens.

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a new token

Add a new token which can be used for making ion API requests.

Authorizations:
OAuth2
Request Body schema: application/json
required
name
string (TokenName)

The name of this token.

assetIds
Array of integers (TokenAssetIds)

The ids of the assets that can be accessed using this token. If undefined, the token can access all assets associated with the account.

scopes
required
string (TokenScopes)
Enum: "assets:list" "assets:read" "assets:write" "profile:read" "tokens:read" "tokens:write"

Defines the scope of this particular token.

allowedUrls
Array of arrays (TokenAllowedUrls)

The URLs from which this token can be accessed. If undefined, the token can be accessed from any URL.

Responses

Response Schema: application/json
object (Token Metadata)

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "3171672f-b6a3-43ae-90d5-0d559a7bf73b",
  • "name": "Token",
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIzMTcxNjcyZi1iNmEzLTQzYWUtOTBkNS0wZDU1OWE3YmY3M2IiLCJpZCI6MSwiaWF0IjoxNjM0Njc1OTU0fQ.cRbNs2IKXbvZjVpjWIId3YB3CeppiIQgbR7mZTKC1UI",
  • "isDefault": false,
  • "dateLastUsed": "2021-10-19T20:39:14.372Z",
  • "dateAdded": "2021-10-19T20:39:14.372Z",
  • "dateModified": "2021-10-19T20:39:14.372Z",
  • "scopes": [
    ],
  • "assetIds": [
    ]
}

Get info about a token

Retrieves metadata for a specific token.

Authorizations:
OAuth2
path Parameters
tokenId
required
string (TokenIdentifier)
Example: a4538dc7-f583-4d9e-889e-35e2db4de534

The unique identifier of the token on which to perform the operation.

Responses

Response Schema: application/json
id
string (TokenIdentifier)

The unique identifier of this token.

name
string (TokenName)

The name of this token.

token
string (Token)

The access token.

dateAdded
string <date-time>

The date and time that this token was created in RFC 3339 format.

dateModified
string <date-time>

The date and time that this token was last modified in RFC 3339 format.

dateLastUsed
string <date-time>

The date and time that this token was last used in RFC 3339 format.

assetIds
Array of integers (TokenAssetIds)

The ids of the assets that can be accessed using this token. If undefined, the token can access all assets associated with the account.

isDefault
boolean

True if this token is the default token, else false.

allowedUrls
Array of arrays (TokenAllowedUrls)

The URLs from which this token can be accessed. If undefined, the token can be accessed from any URL.

scopes
required
string (TokenScopes)
Enum: "assets:list" "assets:read" "assets:write" "profile:read" "tokens:read" "tokens:write"

Defines the scope of this particular token.

Response samples

Content type
application/json
{
  • "id": "a4538dc7-f583-4d9e-889e-35e2db4de534",
  • "name": "New Token",
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1OGQ5MTdhYi1mNWRmLTQ5NGMtTEwOS02NmJlM2M1MzIxOWQiLCJpZCI6MiwiaWF0IjoxNjM0NTcyNTQzfQ.Cf055OJ6fdxw5NIBT0-JwD4aD9HjYQt9bf6CpadOGM",
  • "dateAdded": "2019-03-19T13:17:02.838Z",
  • "dateModified": "2019-03-19T13:17:02.838Z",
  • "dateLastUsed": "2019-03-19T13:17:02.838Z",
  • "assetIds": [
    ],
  • "isDefault": false,
  • "allowedUrls": [],
  • "scopes": [
    ]
}

Modify token info

Updates the name, scope, or asset ids associated with the token.

Authorizations:
OAuth2
path Parameters
tokenId
required
string (TokenIdentifier)
Example: a4538dc7-f583-4d9e-889e-35e2db4de534

The unique identifier of the token on which to perform the operation.

Request Body schema: application/json
required
name
string (TokenName)

The name of this token.

assetIds
Array of integers (PatchTokenAssetIds)

The ids of the assets that can be accessed using this token. Set to null if you want your token to access all of your assets.

scopes
string (TokenScopes)
Enum: "assets:list" "assets:read" "assets:write" "profile:read" "tokens:read" "tokens:write"

Defines the scope of this particular token.

allowedUrls
Array of arrays (PatchTokenAllowedUrls)

The URLs from which this token can be accessed. Set to null if you want your token to be accessed from any URL.

Responses

Request samples

Content type
application/json
{}

Delete a token

Deletes a token. Does not support deleting the default token.

Authorizations:
OAuth2
path Parameters
tokenId
required
string (TokenIdentifier)
Example: a4538dc7-f583-4d9e-889e-35e2db4de534

The unique identifier of the token on which to perform the operation.

Responses

Get the default token

Retrieves metadata for the user's default token.

Authorizations:
OAuth2

Responses

Response Schema: application/json
id
string (TokenIdentifier)

The unique identifier of this token.

name
string (TokenName)

The name of this token.

token
string (Token)

The access token.

dateAdded
string <date-time>

The date and time that this token was created in RFC 3339 format.

dateModified
string <date-time>

The date and time that this token was last modified in RFC 3339 format.

dateLastUsed
string <date-time>

The date and time that this token was last used in RFC 3339 format.

assetIds
Array of integers (TokenAssetIds)

The ids of the assets that can be accessed using this token. If undefined, the token can access all assets associated with the account.

isDefault
boolean

True if this token is the default token, else false.

scopes
required
string (TokenScopes)
Enum: "assets:list" "assets:read" "assets:write" "profile:read" "tokens:read" "tokens:write"

Defines the scope of this particular token.

Response samples

Content type
application/json
{
  • "id": "a4538dc7-f583-4d9e-889e-35e2db4de534",
  • "name": "New Token",
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1OGQ5MTdhYi1mNWRmLTQ5NGMtTEwOS02NmJlM2M1MzIxOWQiLCJpZCI6MiwiaWF0IjoxNjM0NTcyNTQzfQ.Cf055OJ6fdxw5NIBT0-JwD4aD9HjYQt9bf6CpadOGM",
  • "dateAdded": "2019-03-19T13:17:02.838Z",
  • "dateModified": "2019-03-19T13:17:02.838Z",
  • "dateLastUsed": "2019-03-19T13:17:02.838Z",
  • "assetIds": [
    ],
  • "isDefault": true,
  • "scopes": [
    ]
}

User

Routes related to the currently authenticated account.

Get profile information

Retrieves profile information for the access token currently being used to make API calls.

This route works with any valid token, but additional information is returned if the token use the profile:read scope.

Authorizations:
OAuth2

Responses

Response Schema: application/json
id
required
number

The unique identifier for this account.

scopes
required
Array of arrays

The array of scopes available with this token.

username
string

The account username.

email
string

The primary email address associated with this account.

emailVerified
boolean

If true, the email address has been verified for this account.

avatar
string

A url to the profile image associated with this account.

object

Information about the amount of storage available in the user's account.

Response samples

Content type
application/json
Example
{}

Get server defaults

Retrieves default imagery, terrain and building assets along with quick add assets that can be useful to use within other applications.

This route will always return data, but user subscription information is only returned if there is a token with assets:list scope.

Authorizations:
OAuth2

Responses

Response Schema: application/json
required
object

The default assets

required
Array of objects (Quick Add Assets)

The quick add assets

Response samples

Content type
application/json
Example
{
  • "defaultAssets": {
    },
  • "quickAddAssets": [
    ]
}

Exports

Allows you to export the files for a particular asset to an Amazon S3 bucket of your choice. These files can then be hosted through a custom server or downloaded for local/offline use.

The number of bytes exported counts against your monthly streaming quota. If your account goes over streaming quota, additional exports will not be possible until the next billing cycle.

Exports are not supported for certain assets, such as from the Asset Depot or terrain assets which use a base terrain. Check the exportable property of the asset to detect availability.

List exports for an asset

Retrieves the list of exports for the specified asset.

After receiving the initial page of exports, you can request the next and previous pages using the RFC 5988 formatted strings contained in the Link header with the next and prev relations. The process of fetching the next page of tokens can be repeated until the client receives a response with no link header or no next relation in the link header, which means all tokens have been returned. The link urls should be treated as an opaque link as the actual format may change at any time.

Authorizations:
OAuth2
path Parameters
assetId
required
integer (AssetIdentifier)
Example: 3812

The asset identifier on which to perform the operation.

Responses

Response Headers
link
string

An RFC 5988 formatted string with a relation type of next which points to the next page of data on the server, if it exists, and a relation type of prev which points to the previous page of data on the server, if it exists. This url should be treated as an opaque link as the actual format may change at any time.

Response Schema: application/json
Array of objects (Export Metadata)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Export an asset

Creates a new export. Since this feature requires providing Cesium ion with write access to an S3 bucket in a separate account, we strongly recommend using Temporary security credentials. For security purposes, Cesium ion does not provide a way to retrieve previously specified credentials

Authorizations:
OAuth2
path Parameters
assetId
required
integer (AssetIdentifier)
Example: 3812

The asset identifier on which to perform the operation.

Request Body schema: application/json
required
type
required
string
Value: "S3"

Selects which provider the asset is exported to. Only "S3" is currently supported.

bucket
required
string

The destination bucket.

prefix
required
string

The destination prefix.

accessKeyId
required
string

The access key id of the destination bucket.

secretAccessKey
required
string

The secret access key of the destination bucket.

sessionToken
string

The session token. Only required when using STS temporary credentials.

Responses

Response Schema: application/json
id
integer (ExportIdentifier)

The unique identifier of this export.

assetId
integer (AssetIdentifier)

The unique identifier for this asset.

status
string
Enum: "NOT_STARTED" "QUEUED" "IN_PROGRESS" "COMPLETE" "ERROR"

Describes the state of the export process:

Value Description
NOT_STARTED The server recevied the export request but has not started the export process yet, usually because it is waiting for asset to complete tiling.
QUEUED The server has queued the asset for exporting.
IN_PROGRESS The asset is being exported, see bytesExported to monitor progress.
COMPLETE The asset was exported successfully.
ERROR An error occurred during the export process.
bytesExported
integer >= 0

The total number of bytes that have been exported.

dateAdded
string <date-time>

The date and time at which this export was added in RFC 3339 format.

object

Contains information about the type and destination of the export.

Request samples

Content type
application/json
{
  • "format": "S3",
  • "bucket": "destinationBucket",
  • "prefix": "destinationPrefix",
  • "accessKeyId": "access-key",
  • "secretAccessKey": "secret-access-key",
  • "sessionToken": "FynJcbN5N//////////wEaDIEDvhx6N7x4Rd4+wiKtAht78S1zVze89DICpOxfnl/7kn7ox75U5hCv+UHlynJcbN5N7roU7iOz0SLbp9RrTrXPlUP0agskLV/5DUKcDId9FnZknDLVW03ajCeJMlzQK7vcxXK359OHp9l6OwLofVkkXH5Pd78vNcLEzqkLytoMRA0BK4wM2bFJySbfo89oUSxpwHXgslmlZtwHYOcVIyEQX1DmtNVi7Jsx6btgaqt+taLScYCWFsOrK+mpJX8vhe9NTd3gXiQ2BG01L9spfYP9iwt8eyjq9UAD9HCaQZrYvhK9JKAwBD81dkpkxpg2PL68d5B+yRBt90NgLgJc31raArGvurz9IAf034znL0IZntK56sKLcIYKEg0OzpybP0a4IqSLtHQDAYlHe7Z66ogDWmRMxLW+g4yiGtwovq3k5QU="
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "assetId": 3812,
  • "dateAdded": "2022-09-16T04:06:48.897Z",
  • "status": "NOT_STARTED",
  • "bytesExported": 0,
  • "to": {
    }
}

Get the status of an export

Authorizations:
OAuth2
path Parameters
assetId
required
integer (AssetIdentifier)
Example: 3812

The asset identifier on which to perform the operation.

Responses

Response Schema: application/json
id
integer (ExportIdentifier)

The unique identifier of this export.

assetId
integer (AssetIdentifier)

The unique identifier for this asset.

status
string
Enum: "NOT_STARTED" "QUEUED" "IN_PROGRESS" "COMPLETE" "ERROR"

Describes the state of the export process:

Value Description
NOT_STARTED The server recevied the export request but has not started the export process yet, usually because it is waiting for asset to complete tiling.
QUEUED The server has queued the asset for exporting.
IN_PROGRESS The asset is being exported, see bytesExported to monitor progress.
COMPLETE The asset was exported successfully.
ERROR An error occurred during the export process.
bytesExported
integer >= 0

The total number of bytes that have been exported.

dateAdded
string <date-time>

The date and time at which this export was added in RFC 3339 format.

object

Contains information about the type and destination of the export.

Response samples

Content type
application/json
{
  • "id": 1,
  • "assetId": 3812,
  • "status": "COMPLETE",
  • "bytesExported": 1024,
  • "dateAdded": "2022-09-20T16:16:02.838Z",
  • "to": {
    }
}