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.

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.

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.

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
}

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

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": [
    ]
}