openapi: 3.0.2 info: title: Cesium ion version: v1 description: | # Overview The Cesium ion REST API allows you to leverage ion's powerful tiling and streaming capabilities from your own applications and workflows. If this is your first time using our APIs, start with the [REST API Tutorial](https://cesium.com/learn/ion/ion-upload-rest/), which covers many of the basics that are not included here. The base url of the Cesium ion API server is https://api.cesium.com. If you have questions, feedback, or run into any problem, [please reach out](https://cesium.com/contact/support/). The APIs described in this documentation are subject to Cesium's [Terms of Service](https://cesium.com/legal/terms-of-service/). # Authentication All Cesium ion endpoints require authentication in the form of an access token provided in the `Authorization` header of the request. ion uses the OAuth 2.0 `Bearer ` format and supports the following scopes: ### Public Scopes | Scope | Description | | - | - | | assets:limited-list | List the metadata for selected assets available to the account. | | assets:read | Read metadata and access the tiled data for individual assets in the account. | | geocode | Perform geocodes. Not yet available in the REST API. | ### 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. | | labels:read | List labels in the account. | | labels:write | Create, modify, and delete labels in the account. | | tokens:read | Read token metadata and list all tokens for the account. | | tokens:write | Create, modify, and delete tokens in the account. User access tokens only; not available to OAuth. | | archives:read | List and download asset archives. | | archives:write | Create and delete asset archives. | | exports:read | List asset exports. | | exports:write | Export assets. | Cesium ion also supports OAuth 2.0 `authorizationCode` flow if you want to allow users to bring their own ion account into your application. NOTE: We require [PKCE authentication](https://oauth.net/2/pkce/) with client Oauth applications. See our [OAuth 2.0 tutorial](https://cesium.com/learn/ion/ion-oauth2/) for more details. servers: - url: https://api.cesium.com description: Cesium ion API Server security: - OAuth2: [] tags: - name: Assets description: | 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](https://github.com/CesiumGS/3d-tiles) tileset | | GLTF | A [glTF](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0) model | | IMAGERY | An TMS and WMTS compatible imagery layer | | TERRAIN | A [quantized-mesh-1.0](https://github.com/CesiumGS/quantized-mesh) terrain tileset | | CZML | A [CZML](https://github.com/AnalyticalGraphicsInc/czml-writer/wiki/CZML-Guide) dataset | | KML | A [KML](https://developers.google.com/kml) or KMZ dataset | | GEOJSON | A [GeoJSON](https://geojson.org/) dataset | The Assets API provides a mechanism to discover, create, and stream these assets into your own applications. - name: Asset Elements description: | The Asset Elements API provides a mechanism to query individual elements within an asset. - name: Archives description: | 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](#operation/getAsset) property of the asset to detect availability. Clips support both your assets and most Asset Depot assets, but have additional restrictions: * Clips can only be made from 3D Tiles or terrain & imagery assets. * Clips comprised of your assets have a geographic size limit of 200 km^2 * Clips comprised of Asset Depot assets have a geographic size limit of 25 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](https://cesium.com/platform/cesium-ion/pricing/) 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. - name: Exports description: | 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](#operation/getAsset) property of the asset to detect availability. - name: Labels description: | Labels let you organize assets and stories with reusable metadata tags. The Labels API provides a mechanism to list, create, update, and delete account labels. Asset-label assignment is documented with the asset routes. - name: Tokens description: | 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` and `geocode` scopes. This token cannot be modified or deleted, and provides read access to all assets associated with that user's ion account. - name: User description: | Routes related to the currently authenticated account. - name: Oauth description: | The Oauth API provides a mechanism to allow third-party applications to access a user's ion account data through the Oauth 2.0 authorization framework. - name: Experimental description: | Experimental API lets users test emerging capabilities and help shape future improvements. These endpoints are not intended for production use and may be removed without notice. - name: Changelog # * 2023-12-05 - Added [GET /v1/defaults](#operation/getDefaults), which returns a list of default assets available on the server. description: | * 2026-09-21 - [POST /v1/assets/compare](#operation/postAssetsCompare) now creates a `CHANGE_DETECTION` report asset and queues the comparison as an asynchronous job, returning the new asset's metadata instead of the compare job status, and returns `409` when a matching report already exists. The GET and DELETE operations on `/v1/assets/compare` were removed. * 2026-09-08 - Added iModel re-uploads to [POST /v1/assets](#operation/postAssets) for `sourceType: BIM_CAD_DB`: set `baseAssetId` to an existing BIM/CAD Database asset to upload a new version of its source files into the same iModel instead of creating a new one. `existingFileBehavior` is required alongside `baseAssetId` and currently must be `KEEP`. * 2026-09-01 - The routes for compare jobs were updated. They now return mesh assets created from a BIM/CAD Database and allow you to execute compare jobs through the API. * 2026-08-31 - Updated the `sourceType` value for vector tiling from `GEOJSON` to `VECTOR_DATA` * 2026-08-18 - Added [GET /v1/coordinate-reference-system](#operation/getCoordinateReferenceSystem) for searching valid coordinate reference systems to use as the `inputCrs` option when creating assets. * 2026-08-18 - OAuth 2.0 applications can once again be granted the `tokens:read` scope. `tokens:write` remains unavailable to OAuth 2.0 applications. * 2026-08-13 - **Breaking change:** OAuth 2.0 applications can no longer be granted the `tokens:read` or `tokens:write` scopes. The [Tokens API](#tag/Tokens) (`/v2/tokens*`) now requires a Cesium ion access token instead; it is no longer reachable via OAuth 2.0. * 2026-07-16 - Added token expiration and regeneration to the [Tokens API](#tag/Tokens): tokens now include an optional `expiration`, and [PATCH /v2/tokens/{tokenId}](#operation/patchToken) accepts `expiration` and `regenerate`. Changing a token's `assetIds`, `allowedUrls`, or `expiration` now always regenerates its credentials, whether or not `regenerate` was set, since those values are signed into the token itself. * 2026-06-01 - Added GeoJSON vector tiling to [POST /v1/assets](#operation/postAssets) when creating `3DTILES` assets with `sourceType: 'GEOJSON'`. * 2026-05-05 - Added Labels API documentation for `/v1/labels`, `/v1/labels/{labelId}`, bulk asset label mutations on `/v1/assets/{assetId}/labels`, and label data on asset metadata. * 2025-03-04 - Added additional options for configuring reality modeling jobs to allow for more fine grained control. Multiple point cloud and mesh outputs can now be generated from a single job invocation now. * 2026-03-01 - Added [GET /experimental/panoramas/google](#tag/Experimental/operation/getExperimentalPanoramasGoogle) route for Google Street View imagery * 2025-12-12 - Added language for existing Oauth functionality * 2025-07-14 - Added the ability to specify the gaussian splats pipeline through the API * 2025-02-27 - Added Azure Storage support for asset import and export * 2024-11-12 - Added `BIM_CAD` option that invokes the new design tiler for `ifc` files * 2024-08-23 - Added `inputCrs` option when uploading `3D_CAPTURE` source data with `targetVersion` set to `1.1` and for `POINT_CLOUD` source data * 2024-05-15 - Added `textureFormat` option when uploading `CITYGML` and `KML` source data for 3D tiling. * 2024-05-08 - Added support for archive clips. See our [blog post](https://cesium.com/blog/2024/05/08/cesium-ion-clipping/) to learn more. * All endpoints related to `/v1/assets/{assetId}/archives` have been deprecated and will be removed on December 1st, 2024. Use `/v1/archives` instead: * `GET /v1/assets/{assetId}/archives` -> `GET /v1/archives/?assetId={assetId}`` * `GET /v1/assets/{assetId}/archives/{archiveId}` -> `GET /v1/archives/{archiveId}` * `GET /v1/assets/{assetId}/archives/{archiveId}/download` -> `GET /v1/archives/{archiveId}/download` * `DELETE /v1/assets/{assetId}/archives/{archiveId}` -> `GET /v1/archives/{archiveId}` * `POST /v1/assets/{assetId}/archives` -> `POST /v1/archives` * 2024-05-01 - `targetVersion` now defaults to `1.1`` when creating `3D_CAPTURE` assets. The ability to specify `1.0` is deprecated and will be removed on September 1st, 2024. * 2024-04-15 - Added a new `SKETCHFAB` option to `from` in [POST /v1/assets](#operation/postAssets) for importing free models from Sketchfab * 2023-12-12 - Added optional `mapLayer` return property to the [GET /v1/assets/{assetId}/endpoint](#operation/getAssetEndpoint) response for external BING assets. * 2023-11-01 - Added support for Cesium's [new Reality Tiler](https://cesium.com/blog/2023/11/01/new-reality-tiler/). Specifically: * Added new `targetVersion` option when creating `3D_CAPTURE` assets. It defaults to `1.0`, which uses the previous tiling pipeline. Setting this value to `1.1` opts into the new pipeline and generated 3D Tiles 1.1 tilesets. * Added `KTX2` option to `textureFormat` enum. Only valid when `targetVersion` is `1.1`. * Added `MESHOPT` and `QUANTIZATION` options to `geometryCompression` enum. Only valid when `targetVersion` is `1.1`. * Support for generating 3D Tiles 1.0 when using the `3D_CAPTURE` option is deprecated and will be removed on May 1st, 2024, at which point all `3D_CAPTURE` assets will use the new Reality Tiler. * 2023-10-25 - Added the ability for [GET /v1/assets/{assetId}/endpoint](#operation/getAssetEndpoint) to provide access to externally hosted 3D Tiles tileset. * 2022-11-04 - Released the [asset archives API](#tag/Archives) for creating downloadable zip archives of individual assets for offline usage. * 2022-11-04 - Released the [asset exports API](#operation/Exports) for exporting assets to an S3 bucket you control. * 2022-09-20 - Added `archivable` field to the [GET /v1/assets](#operation/getAssets) and [GET /v1/assets/{assetId}](#operation/getAsset) APIs. * 2021-11-29 - Added an `allowedUrls` property to tokens, an array of URL strings from which the token can be used. See the [Tokens API](#tag/Tokens) for more details. * 2021-11-05 - Released the [Tokens API](#tag/Tokens), adding routes for creating and managing access tokens. * 2021-10-13 - The `heightReference` and `toMeters` options for [POST /v1/assets](#operation/postAssets) with `sourceType: 'RASTER_TERRAIN'` are now optional. By default, the source data's vertical datum is used. * 2021-09-12 - Added pagination, searching, and sorting options to the [GET /v1/asset](#operation/getAssets) route * 2020-03-24 - Added the `profile:read` scope and `GET /v1/me` route for retrieving profile information. * 2020-01-22 - Added `CZML`, `KML`, and `GeoJSON` asset types to the Assets section. * 2019-09-11 - Added `GLTF` asset type. * 2019-08-07 - Added `geometryCompression` property to [POST /v1/assets](#operation/postAssets) which can be used to set the type of geometry compression used by the tiling pipeline. * 2019-07-29 - Added `from` option to [POST /v1/assets](#operation/postAssets) for tiling data from a user-provided S3 bucket. * 2019-04-22 - Initial release. paths: /v1/me: get: operationId: getMe summary: Get profile information description: | 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. tags: - User security: - OAuth2: - "profile:read" - AccessToken: - "profile:read" responses: 200: description: OK content: application/json: schema: title: Profile Information type: object properties: id: type: number description: The unique identifier for this account. scopes: type: array description: The array of scopes available with this token. username: type: string description: The account username. email: type: string description: The primary email address associated with this account. emailVerified: type: boolean description: If true, the email address has been verified for this account. avatar: type: string description: A url to the profile image associated with this account. storage: type: object description: Information about the amount of storage available in the user's account. properties: used: type: number description: The number of bytes currently being used by this account. available: type: number description: The number of bytes available for additional asset uploads to this account. total: type: number description: The total number of bytes currently allowed to be used by this account. beta: type: boolean description: if this user's account is able to access early access beta features required: - id - scopes examples: Response with profile:read scope: value: { "id": 212352, "scopes": ["assets:read", "profile:read"], "username": "mamato", "email": "matt@cesium.com", "emailVerified": true, "avatar": "https://www.gravatar.com/avatar/4f14cc6c584f41d89ef1d34c8986ebfb.jpg?d=mp", "storage": { "used": 214526475, "available": 53472564725, "total": 53687091200, }, "beta": false, } Response without profile:read scope: value: { "id": 212352, "scopes": ["assets:read", "assets:write", "assets:list"], } 401: $ref: "#/components/responses/401" # /v1/defaults: # get: # operationId: getDefaults # summary: Get server defaults # description: | # 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. # tags: # - User # responses: # 200: # description: OK # content: # application/json: # schema: # title: Default application information # type: object # properties: # defaultAssets: # type: object # description: The default assets # properties: # imagery: # type: number # description: The asset id of the default imagery asset. # terrain: # type: number # description: The asset id of the default terrain asset. # buildings: # type: number # description: The asset id of the default buildings asset. # quickAddAssets: # type: array # description: The quick add assets # items: # $ref: "#/components/schemas/QuickAddAssets" # required: # - defaultAssets # - quickAddAssets # examples: # Response with assets:list scope: # value: # { # "defaultAssets": { # "imagery": 2, # "terrain": 1, # "buildings": 62 # }, # "quickAddAssets": [ # { # "name": "Cesium World Terrain", # "objectName": "Cesium World Terrain", # "description": "High-resolution global terrain tileset curated from several data sources", # "assetId": 1, # "type": "TERRAIN", # "subscribed": true # }, # { # "name": "Bing Maps Aerial", # "objectName": "Bing Maps Aerial", # "description": "Aerial imagery", # "assetId": 2, # "type": "IMAGERY", # "subscribed": true # }, # { # "name": "Cesium OSM Buildings", # "objectName": "Cesium OSM Buildings", # "description": "A 3D buildings layer derived from OpenStreetMap covering the entire world.", # "assetId": 96188, # "type": "3DTILES", # "subscribed": true # }, # { # "name": "Cesium World Terrain + Bing Maps Aerial", # "objectName": "Cesium World Terrain", # "description": "High-resolution global terrain tileset curated from several data sources textured with Aerial imagery", # "assetId": 1, # "type": "TERRAIN", # "subscribed": true, # "rasterOverlays": [ # { # "name": "Bing Maps Aerial", # "assetId": 2, # "subscribed": true # } # ] # } # ] # } # Response without assets:list scope: # value: # { # "defaultAssets": { # "imagery": 2, # "terrain": 1, # "buildings": 62 # }, # "quickAddAssets": [ # { # "name": "Cesium World Terrain", # "objectName": "Cesium World Terrain", # "description": "High-resolution global terrain tileset curated from several data sources", # "assetId": 1, # "type": "TERRAIN" # }, # { # "name": "Bing Maps Aerial", # "objectName": "Bing Maps Aerial", # "description": "Aerial imagery", # "assetId": 2, # "type": "IMAGERY" # }, # { # "name": "Cesium OSM Buildings", # "objectName": "Cesium OSM Buildings", # "description": "A 3D buildings layer derived from OpenStreetMap covering the entire world.", # "assetId": 96188, # "type": "3DTILES" # }, # { # "name": "Cesium World Terrain + Bing Maps Aerial", # "objectName": "Cesium World Terrain", # "description": "High-resolution global terrain tileset curated from several data sources textured with Aerial imagery", # "assetId": 1, # "type": "TERRAIN", # "rasterOverlays": [ # { # "name": "Bing Maps Aerial", # "assetId": 2 # } # ] # } # ] # } /oauth/token: post: operationId: postOauthToken summary: Obtain an access token description: | Obtain an access token using the OAuth 2.0 authorization framework. This endpoint supports the `authorization_code`, and `refresh_token` grant types. For more information on how to use this endpoint, see our [OAuth 2.0 tutorial](https://cesium.com/learn/ion/ion-oauth2/). tags: - Oauth requestBody: required: true content: application/json: schema: type: object properties: grant_type: type: string description: The OAuth 2.0 grant type being used. Authorization code and refresh token are the supported grants. enum: [authorization_code, refresh_token] client_id: type: number description: The client identifier issued to the client during the registration process. code: type: string description: The authorization code received from the user login process. Required when using the `authorization_code` grant type. redirect_uri: type: string description: The redirect URI registered with the OAuth Client. refresh_token: type: string description: The refresh token previously issued by the authorization server. Required when using the `refresh_token` grant type. code_verifier: type: string description: The code verifier used in the PKCE flow. Required when using the `authorization_code` grant type. required: - grant_type - client_id - redirect_uri responses: 200: description: OK content: application/json: schema: type: object properties: access_token: type: string description: The access token issued by the authorization server. expires_in: type: number description: Number of seconds the access token is valid. Tokens are currently issued for 30 days. refresh_token_expires_in: type: number description: Number of seconds the refresh token is valid. Refresh tokens are currently valid for 90 days. token_type: type: string description: The type of token issued. This will always be `Bearer`. refresh_token: type: string description: The refresh token which can be used to obtain new access tokens using the `refresh_token` grant type. examples: Authorization code grant response: value: { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 86400, "refresh_token": "d1e8f4e5c6b7a8d9e0f1a2b3c4d5e6f7...", "refresh_token_expires_in": 259200, } 401: description: Invalid Credentials 409: description: Invalid Request /v1/labels: get: operationId: getLabels summary: List labels description: | Retrieves labels associated with an account. Use `search` to filter label names. Use `limit` and `page` to paginate the result set. tags: - Labels security: - OAuth2: - "labels:read" - AccessToken: - "labels:read" parameters: - name: search in: query required: false schema: type: string description: Filter applied to the label name. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 1000 default: 1000 description: Maximum number of labels to return. - name: page in: query required: false schema: type: integer minimum: 1 default: 1 description: 1-based page number to return. responses: 200: description: OK headers: link: $ref: "#/components/headers/link-next-prev" content: application/json: schema: title: Label List type: object properties: items: type: array description: A page of labels. items: $ref: "#/components/schemas/LabelListItem" examples: exampleResponse: value: { "items": [ { "id": 17, "name": "Priority", "color": "#404040", "assets": 3, "stories": 1, }, { "id": 23, "name": "Review", "color": "#ff0000", "assets": 0, "stories": 0, }, ], } 401: $ref: "#/components/responses/401" post: operationId: postLabels summary: Create a label description: Adds a new label to the account. tags: - Labels security: - OAuth2: - "labels:write" - AccessToken: - "labels:write" requestBody: required: true content: application/json: schema: type: object properties: name: $ref: "#/components/schemas/LabelName" color: $ref: "#/components/schemas/LabelColor" required: - name - color examples: exampleBody: value: { "name": "Priority", "color": "#404040" } responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/LabelMetadata" examples: exampleResponse: value: { "id": 17, "name": "Priority", "color": "#404040" } 401: $ref: "#/components/responses/401" /v1/labels/{labelId}: parameters: - $ref: "#/components/parameters/labelId" patch: operationId: patchLabel summary: Modify label info description: | Updates the name and/or color of a label. At least one of `name` or `color` must be supplied. tags: - Labels security: - OAuth2: - "labels:write" - AccessToken: - "labels:write" requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: name: $ref: "#/components/schemas/LabelName" color: $ref: "#/components/schemas/LabelColor" examples: exampleBody: value: { "name": "In review" } responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/LabelMetadata" examples: exampleResponse: value: { "id": 17, "name": "In review", "color": "#404040" } 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" delete: operationId: deleteLabel summary: Delete a label description: Deletes a label. tags: - Labels security: - OAuth2: - "labels:write" - AccessToken: - "labels:write" responses: 400: description: Bad Request 204: description: No Content 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /v1/assets: get: operationId: getAssets summary: List assets description: | 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](https://tools.ietf.org/html/rfc5988) 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. tags: - Assets security: - OAuth2: - "assets:list" - "assets:limited-list" - AccessToken: - "assets:list" - "assets:limited-list" parameters: - in: query name: limit schema: type: integer default: 1000 example: 50 minimum: 1 maximum: 1000 description: 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. - in: query name: page schema: type: integer default: 1 minimum: 1 example: 3 description: The page number. - in: query name: search schema: type: string example: roads description: 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, labels, description, or attribution. - in: query name: sortBy schema: type: string default: id example: NAME enum: [ID, NAME, DESCRIPTION, BYTES, TYPE, STATUS, DATE_ADDED, CREATOR] description: The property by which to sort the results. If undefined, assets are sorted by id. - in: query name: sortOrder schema: type: string default: ASC example: ASC enum: [ASC, DESC] description: The order in which to sort the results. If undefined, assets are sorted ascending. - in: query name: status schema: type: array items: $ref: "#/components/schemas/AssetStatus" description: One or more asset statuses by which to filter the list of assets. If undefined, returns assets with any status. - in: query name: type schema: type: array items: $ref: "#/components/schemas/AssetType" description: One ore more asset types by which to filter the list of assets. If undefined, returns assets of any type. responses: 200: description: OK headers: link: $ref: "#/components/headers/link-next-prev" content: application/json: schema: title: Asset Metadata type: object properties: items: type: array description: A page of assets. items: $ref: "#/components/schemas/AssetMetadata" examples: exampleResponse: value: { "items": [ { "id": 1, "type": "TERRAIN", "name": "Cesium World Terrain", "description": "High-resolution global terrain tileset curated from several data sources. See the official [Cesium World Terrain](https://cesium.com/content/cesium-world-terrain/) page for details.", "bytes": 0, "attribution": "Data available from the U.S. Geological Survey, © CGIAR-CSI, Produced using Copernicus data and information funded by the European Union - EU-DEM layers, Data available from Land Information New Zealand, Data available from data.gov.uk, Data courtesy Geoscience Australia", "dateAdded": "2019-04-14T15:25:11.030Z", "status": "COMPLETE", "percentComplete": 100, "archivable": false, "exportable": false, }, { "id": 92391, "type": "3DTILES", "name": "My House", "description": "First attempt at photogrammetry.", "bytes": 28459666, "attribution": "", "dateAdded": "2019-04-14T15:28:25.435Z", "status": "COMPLETE", "percentComplete": 100, "archivable": true, "exportable": true, "labels": [ { "id": 12, "name": "Architecture", "color": "#FF0000", }, ], "creatorId": 422, "creatorUsername": "example user", }, ], } 401: $ref: "#/components/responses/401" post: operationId: postAssets summary: Create a new asset description: | Uploading data to ion is a four step process: 1. Provide ion information about your data. 2. Upload your data to the provided Amazon S3 bucket. 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. For a complete example of using this endpoint, with full source code, see the [REST API Tutorial](https://cesium.com/learn/ion/ion-upload-rest/). For a full list of supported source data formats see [Tiler Data Types and Formats](https://cesium.com/learn/3d-tiling/tiler-data-formats/#supported-data-formats) tags: - Assets security: - OAuth2: - "assets:write" - AccessToken: - "assets:write" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AssetMetadata" examples: exampleBody: value: { "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": { "sourceType": "string" }, } responses: 200: description: OK content: application/json: schema: type: object properties: uploadLocation: description: Contains temporary credentials and location information for uploading source data to ion's S3-compatible storage. The credentials last for 12 hours. This property is undefined when importing source files from third-party sources. type: object allOf: - properties: endpoint: type: string description: The S3 endpoint where files should be uploaded. - $ref: "#/components/schemas/AwsLocation" - $ref: "#/components/schemas/AwsCredentials" onComplete: description: 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. type: object properties: url: description: The URL to request. type: string method: description: The method to use when requesting the URL. type: string fields: description: The body to include with the request. type: object assets: description: This is only returned when running reconstruction jobs. It contains the list of all assets generated from that job. It will be undefined otherwise. type: array items: $ref: "#/components/schemas/AssetMetadata" assetMetadata: $ref: "#/components/schemas/AssetMetadata" examples: exampleResponse: value: { "assetMetadata": { "id": 21111, "type": "3DTILES", "name": "Reichstag", "description": "Example Asset", "attribution": "", "bytes": 0, "dateAdded": "2019-04-19T00:30:54.111Z", "status": "AWAITING_FILES", "percentComplete": 0, "archivable": false, "exportable": true, "creatorId": 422, "creatorUsername": "example user", }, "assets": [ { "id": 21112, "type": "LAS", "name": "Reichstag LAS", "description": "Example LAS Asset", "attribution": "", "bytes": 0, "dateAdded": "2019-04-19T00:30:54.111Z", "status": "AWAITING_FILES", "percentComplete": 0, "archivable": false, "exportable": true, "creatorId": 422, "creatorUsername": "example user", }, ], "uploadLocation": { "endpoint": "https://s3.us-east-1.amazonaws.com", "bucket": "assets.cesium.com", "prefix": "sources/21111/", "accessKey": "REDACTED_AWS_ACCESS_KEY_ID", "secretAccessKey": "Hd3ZC9yq78hoCR4KYF4atHEnytfgLJMNV0KPdpz8", "sessionToken": "FQoGZXIvYXdzEIr//////////wEaDIEDvhx6N7x4Rd4+wiKtAht78S1zVze89DICpOxfnl/7kn7ox75U5hCv+UHlynJcbN5N7roU7iOz0SLbp9RrTrXPlUP0agskLV/5DUKcDId9FnZknDLVW03ajCeJMlzQK7vcxXK359OHp9l6OwLofVkkXH5Pd78vNcLEzqkLytoMRA0BK4wM2bFJySbfo89oUSxpwHXgslmlZtwHYOcVIyEQX1DmtNVi7Jsx6btgaqt+taLScYCWFsOrK+mpJX8vhe9NTd3gXiQ2BG01L9spfYP9iwt8eyjq9UAD9HCaQZrYvhK9JKAwBD81dkpkxpg2PL68d5B+yRBt90NgLgJc31raArGvurz9IAf034znL0IZntK56sKLcIYKEg0OzpybP0a4IqSLtHQDAYlHe7Z66ogDWmRMxLW+g4yiGtwovq3k5QU=", }, "onComplete": { "method": "POST", "url": "https://api.cesium.com/v1/assets/21111/uploadComplete", "fields": {}, }, } 400: description: Bad Request /v1/assets/imodel: post: operationId: postAssetsIModel summary: Import an iModel description: | This will import a mesh export from an iModel in Bentley Infrastructure Cloud. In order to use an iModel, you must be an owner of the iModel and belong to the same organization as the iModel. By default the latest changeset of the iModel is imported. Pass `changesetIndex` to import a specific iModel version instead. tags: - Assets security: - OAuth2: - "assets:write" - AccessToken: - "assets:write" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/IModelImportOptions" examples: exampleBody: value: { "name": "Roadway from Infrastructure Cloud", "iModelId": "753530df-950e-45c2-bb94-3c4da8ab2396", } responses: 200: description: OK content: application/json: schema: type: object properties: asset: $ref: "#/components/schemas/AssetMetadata" examples: exampleResponse: value: { "asset": { "id": 21111, "type": "3DTILES", "name": "Roadway from Infrastructure Cloud", "description": "", "attribution": "", "bytes": 0, "dateAdded": "2019-04-19T00:30:54.111Z", "status": "NOT_STARTED", "percentComplete": 0, "archivable": false, "exportable": true, "creatorId": 422, "creatorUsername": "example user", }, } 400: description: Bad Request 409: description: Invalid Request /v1/coordinate-reference-system: get: operationId: getCoordinateReferenceSystem summary: Search coordinate reference systems description: | Searches for coordinate reference systems (CRS) that can be used as the `inputCrs` option when creating an asset with [POST /v1/assets](#operation/postAssets). This searches the name, description, and EPSG code of known coordinate reference systems. Deprecated coordinate reference systems are excluded from results. If searching by EPSG code, use the numeric code on its own (e.g. `7856`) rather than prefixing it with `EPSG:`. tags: - Assets security: - OAuth2: - "geocode" parameters: - name: search in: query description: A search string to filter coordinate reference systems by name, description, or EPSG code. schema: type: string responses: 200: description: OK content: application/json: schema: type: array items: type: object properties: name: type: string description: The name of the coordinate reference system. description: type: string description: A description of the coordinate reference system. epsg: type: integer description: The EPSG code of the coordinate reference system, if it has one. examples: exampleResponse: value: [ { "name": "EPSG:7856", "description": "GDA2020 / MGA zone 56", "epsg": 7856, }, ] 401: $ref: "#/components/responses/401" /v1/assets/{assetId}: parameters: - $ref: "#/components/parameters/assetId" get: operationId: getAsset summary: Get info about an asset description: Retrieves metadata information about a specific asset. tags: - Assets security: - OAuth2: - "assets:read" - AccessToken: - "assets:read" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/AssetMetadata" examples: exampleResponse: value: { "id": 92391, "type": "3DTILES", "name": "My House", "description": "First attempt at photogrammetry.", "bytes": 28459666, "attribution": "", "dateAdded": "2019-04-14T15:28:25.435Z", "status": "COMPLETE", "percentComplete": 100, "archivable": true, "exportable": true, "labels": [ { "id": 12, "name": "Architecture", "color": "#FF0000", }, ], "creatorId": 422, "creatorUsername": "example user", } 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" patch: operationId: patchAsset summary: Modify asset info description: Updates the name, description, or attribution of an asset. Does not support assets subscribed to from the Asset Depot. tags: - Assets security: - OAuth2: - "assets:write" - AccessToken: - "assets:write" requestBody: required: true content: application/json: schema: properties: name: $ref: "#/components/schemas/AssetName" description: $ref: "#/components/schemas/AssetDescription" attribution: $ref: "#/components/schemas/AssetAttribution" responses: 400: description: Bad Request 204: description: No Content 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" delete: operationId: deleteAsset summary: Delete an asset description: Deletes an asset. Does not support assets subscribed to from the Asset Depot. tags: - Assets security: - OAuth2: - "assets:write" - AccessToken: - "assets:write" responses: 204: description: No Content 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /v1/assets/{assetId}/labels: parameters: - $ref: "#/components/parameters/assetId" put: operationId: putAssetLabels summary: Add labels to an asset description: | Adds labels to an asset. The label identifiers to add to an asset can be supplied through the `labelIds` property. Existing asset-label associations are ignored. tags: - Assets security: - OAuth2: - "assets:write" - AccessToken: - "assets:write" requestBody: required: true content: application/json: schema: type: object properties: labelIds: $ref: "#/components/schemas/LabelIds" required: - labelIds examples: exampleBody: value: { "labelIds": [17, 23] } responses: 400: description: Bad Request 204: description: No Content 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" delete: operationId: deleteAssetLabels summary: Remove labels from an asset description: | Removes labels from an asset. Provide the label identifiers to remove in `labelIds`. tags: - Assets security: - OAuth2: - "assets:write" - AccessToken: - "assets:write" requestBody: required: true content: application/json: schema: type: object properties: labelIds: $ref: "#/components/schemas/LabelIds" required: - labelIds examples: exampleBody: value: { "labelIds": [17, 23] } responses: 204: description: No Content 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /v1/assets/{assetId}/endpoint: parameters: - $ref: "#/components/parameters/assetId" - name: options in: query schema: type: string description: | Additional options for Google imagery assets. This is a object with settings to pass to [createSession](https://developers.google.com/maps/documentation/tile/session_tokens#session_token_request) to control styling of the imagery. get: operationId: getAssetEndpoint summary: Access tiles description: | 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: * [3D Tiles](https://sandcastle.cesium.com?src=3D%20Tiles%20Photogrammetry.html) * [Terrain](https://sandcastle.cesium.com?src=PAMAP%20Terrain.html&label=ion%20Assets) * [Imagery](https://sandcastle.cesium.com?src=Washington%20DC%202017.html&label=ion%20Assets) If you're implementing ion asset visualization in a non-CesiumJS rendering engine or application, you'll find the below specifications links useful: * [3D Tiles specification](https://github.com/CesiumGS/3d-tiles) * [quantized-mesh-1.0 terrain specification](https://github.com/CesiumGS/quantized-mesh) * [WMTS specification](https://www.opengeospatial.org/standards/wmts) * [TMS specification](https://wiki.osgeo.org/wiki/Tile_Map_Service_Specification) For external assets see each providers documentation for more information about how to use their API. * [Bing](https://learn.microsoft.com/en-us/bingmaps/rest-services/imagery/) * [Google Maps](https://developers.google.com/maps/documentation/tile/2d-tiles-overview) tags: - Assets security: - OAuth2: - "assets:read" - AccessToken: - "assets:read" responses: 200: description: OK content: application/json: schema: anyOf: - $ref: "#/components/schemas/AssetEndpoint" - $ref: "#/components/schemas/ExternalAssetEndpoint" 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /v1/archives: get: operationId: getArchives summary: List archives description: | Retrieves all archives tags: - Archives security: - OAuth2: - "archives:read" - AccessToken: - "archives:read" parameters: - name: limit in: query schema: type: integer default: 1000 example: 50 minimum: 1 maximum: 1000 description: | 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. - name: page in: query schema: type: integer default: 1 minimum: 1 example: 3 description: The page number. - name: search in: query schema: type: string example: roads description: | 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. - name: sortBy in: query schema: type: string default: ID example: BYTES enum: [ID, BYTES, STATUS, DATE_ADDED] description: The property by which to sort the results. If undefined, archives are sorted by id. - name: sortOrder in: query schema: type: string default: ASC example: ASC enum: [ASC, DESC] description: The order in which to sort the results. If undefined, assets are sorted ascending. - name: assetId in: query description: The asset to find archives for. The returned archives will contain the given asset id. schema: $ref: "#/components/schemas/AssetIdentifier" - name: clipped in: query description: Limit to only clipped or unclipped archives. If undefined, include all archives. schema: type: boolean example: true responses: 200: description: OK headers: link: $ref: "#/components/headers/link-next-prev" content: application/json: schema: title: Asset Archive Metadata type: object properties: items: type: array items: $ref: "#/components/schemas/ArchiveMetadata2" examples: exampleResponse: value: { "items": [ { "id": 10, "name": "Clip of Park", "assetIds": [3812, 4031], "format": "ZIP", "type": "CLIP_LATITUDE_LONGITUDE_RECTANGLE", "clipRegion": [ -1.3194169616700622, 0.6988112052237774, -1.319410651520469, 0.698813516991245, ], "status": "COMPLETE", "bytesArchived": 102463, }, { "id": 12, "name": "Courtyard", "assetIds": [3813], "type": "FULL", "format": "ZIP", "status": "IN_PROGRESS", "bytesArchived": 17, }, ], } 401: $ref: "#/components/responses/401" post: operationId: postArchives summary: Create an archive description: | Creates a new archive. tags: - Archives security: - OAuth2: - "archives:write" - AccessToken: - "archives:write" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AssetArchiveOptions" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/ArchiveMetadata2" examples: exampleResponse: value: { "id": 12, "name": "Courtyard", "assetIds": [3813], "type": "FULL", "format": "ZIP", "status": "IN_PROGRESS", "bytesArchived": 17, } 401: $ref: "#/components/responses/401" /v1/archives/{archiveId}: parameters: - $ref: "#/components/parameters/archiveId" get: operationId: getArchive summary: Get info about an archive description: Retrieves the metadata information about a specific asset archive. tags: - Archives security: - OAuth2: - "archives:read" - AccessToken: - "archives:read" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/ArchiveMetadata2" 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" patch: operationId: patchArchive summary: Update an archive name description: Updates the name of a clipped archive. This is not valid for an archive without a clipRegion. tags: - Archives security: - OAuth2: - "archives:write" - AccessToken: - "archives:write" requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The new name of the archive required: - name responses: 204: description: No Content 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" delete: operationId: deleteArchive summary: Delete an archive description: Deletes an asset archive. tags: - Archives security: - OAuth2: - "archives:write" - AccessToken: - "archives:write" responses: 204: description: No Content 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /v1/archives/{archiveId}/download: parameters: - $ref: "#/components/parameters/archiveId" get: operationId: getArchivesDownload summary: Download an archive description: Fetches the asset archive as an octet stream. The archive is available to be downloaded once ion finishes archiving processing. tags: - Archives security: - OAuth2: - "archives:read" - AccessToken: - "archives:read" responses: 200: description: OK content: application/octet-stream: schema: format: binary 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /v1/assets/{assetId}/archives: parameters: - $ref: "#/components/parameters/assetId" get: deprecated: true operationId: getAssetArchives summary: List archives for an asset description: | Retrieves all archives for the specified asset. tags: - Archives security: - OAuth2: - "archives:read" - AccessToken: - "archives:read" responses: 200: description: OK content: application/json: schema: title: Asset Archive Metadata type: object properties: items: type: array items: $ref: "#/components/schemas/ArchiveMetadata" examples: exampleResponse: value: { "items": [ { "id": 10, "assetId": 3812, "format": "ZIP", "status": "COMPLETE", "bytesArchived": 102463, }, { "id": 12, "assetId": 3812, "format": "ZIP", "status": "IN_PROGRESS", "bytesArchived": 17, }, ], } 401: $ref: "#/components/responses/401" post: deprecated: true operationId: postAssetArchives summary: Create an archive description: | Creates a new archive for the asset that can be downloaded for offline use. Exports are not supported for assets subscribed to from the Asset Depot or terrain assets which use a base terrain. tags: - Archives security: - OAuth2: - "archives:write" - AccessToken: - "archives:write" requestBody: required: true content: application/json: schema: type: object properties: format: $ref: "#/components/schemas/ArchiveFormat" examples: exampleBody: value: { "format": "ZIP" } responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/ArchiveMetadata" examples: exampleResponse: value: { "id": 10, "assetId": 3812, "format": "ZIP", "status": "NOT_STARTED", "bytesArchived": 0, } 401: $ref: "#/components/responses/401" 402: $ref: "#/components/responses/402" /v1/assets/{assetId}/archives/{archiveId}: parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/archiveId" get: deprecated: true operationId: getAssetArchive summary: Get info about an archive description: Retrieves the metadata information about a specific asset archive. tags: - Archives security: - OAuth2: - "archives:read" - AccessToken: - "archives:read" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/ArchiveMetadata" 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" delete: deprecated: true operationId: deleteAssetArchive summary: Delete an archive description: Deletes an asset archive. tags: - Archives security: - OAuth2: - "archives:write" - AccessToken: - "archives:write" responses: 204: description: No Content 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /v1/assets/{assetId}/archives/{archiveId}/download: parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/archiveId" get: deprecated: true operationId: getAssetArchiveDownload summary: Download an archive description: Fetches the asset archive as an octet stream. The archive is available to be downloaded once ion finishes archiving processing. tags: - Archives security: - OAuth2: - "archives:read" - AccessToken: - "archives:read" responses: 200: description: OK content: application/octet-stream: schema: format: binary 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /v1/assets/{assetId}/exports: parameters: - $ref: "#/components/parameters/assetId" get: operationId: getAssetExports summary: List exports for an asset description: | 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](https://tools.ietf.org/html/rfc5988) 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. tags: - Exports security: - OAuth2: - "exports:read" - AccessToken: - "exports:read" responses: 200: description: OK headers: link: $ref: "#/components/headers/link-next-prev" content: application/json: schema: title: Asset Export Metadata type: object properties: items: type: array items: $ref: "#/components/schemas/ExportMetadata" examples: exampleResponse: value: { "items": [ { "id": 1, "assetId": 3812, "dateAdded": "2022-09-16T04:06:48.897Z", "status": "COMPLETE", "bytesExported": 76i2347342, "to": { "type": "S3", "bucket": "myBucket", "prefix": "/", }, }, { "id": 1, "assetId": 3812, "dateAdded": "2022-09-16T04:06:48.897Z", "status": "ERROR", "bytesExported": 0, "to": { "type": "S3", "bucket": "ion-exports", "prefix": "/3812", }, }, ], } 401: $ref: "#/components/responses/401" post: operationId: postAssetExports summary: Export an asset description: | Creates a new export. This feature requires providing Cesium ion with write access to an S3 bucket or Azure storage account. For S3 we strongly recommend using [Temporary security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html). For Azure only one type credentials may be specified. Either accessKey only, sasToken only or tenantId/clientId/clientSecret. For security purposes, Cesium ion does not provide a way to retrieve previously specified credentials. tags: - Exports security: - OAuth2: - "exports:write" - AccessToken: - "exports:write" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AssetToInlineCredentials" examples: exampleBody: value: { "format": "S3", "bucket": "destinationBucket", "prefix": "destinationPrefix", "accessKeyId": "access-key", "secretAccessKey": "secret-access-key", "sessionToken": "FynJcbN5N//////////wEaDIEDvhx6N7x4Rd4+wiKtAht78S1zVze89DICpOxfnl/7kn7ox75U5hCv+UHlynJcbN5N7roU7iOz0SLbp9RrTrXPlUP0agskLV/5DUKcDId9FnZknDLVW03ajCeJMlzQK7vcxXK359OHp9l6OwLofVkkXH5Pd78vNcLEzqkLytoMRA0BK4wM2bFJySbfo89oUSxpwHXgslmlZtwHYOcVIyEQX1DmtNVi7Jsx6btgaqt+taLScYCWFsOrK+mpJX8vhe9NTd3gXiQ2BG01L9spfYP9iwt8eyjq9UAD9HCaQZrYvhK9JKAwBD81dkpkxpg2PL68d5B+yRBt90NgLgJc31raArGvurz9IAf034znL0IZntK56sKLcIYKEg0OzpybP0a4IqSLtHQDAYlHe7Z66ogDWmRMxLW+g4yiGtwovq3k5QU=", } responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/ExportMetadata" examples: exampleResponse: value: { "id": 1, "assetId": 3812, "dateAdded": "2022-09-16T04:06:48.897Z", "status": "NOT_STARTED", "bytesExported": 0, "to": { "type": "S3", "bucket": "myBucket", "prefix": "/" }, } 401: $ref: "#/components/responses/401" 402: $ref: "#/components/responses/402" /v1/assets/{assetId}/exports/{exportId}: parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/exportId" get: operationId: getAssetExport summary: Get the status of an export tags: - Exports security: - OAuth2: - "exports:read" - AccessToken: - "exports:read" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/ExportMetadata" 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /assets/{assetId}/elements: parameters: - $ref: "#/components/parameters/assetId" get: operationId: getAssetElements summary: List elements for an asset description: | Retrieves a paginated list of elements associated with a specific asset. ### Filtering Elements can be filtered using either the `filter` or `where` query parameter. **`filter`** accepts a URL-encoded JSON object using MongoDB-style operators: | Operator | Description | Example | | - | - | - | | `$eq` | Equal (also implicit) | `{ "Status": "Active" }` | | `$ne` | Not equal | `{ "Status": { "$ne": "Deleted" } }` | | `$gt` | Greater than | `{ "Height": { "$gt": 10 } }` | | `$gte` | Greater than or equal | `{ "Height": { "$gte": 10 } }` | | `$lt` | Less than | `{ "Height": { "$lt": 100 } }` | | `$lte` | Less than or equal | `{ "Height": { "$lte": 100 } }` | | `$in` | In a list of values | `{ "Category": { "$in": ["Structural", "Mechanical"] } }` | | `$like` | SQL LIKE pattern | `{ "UserLabel": { "$like": "%pipe%" } }` | | `$and` | Logical AND (array) | `{ "$and": [ ... ] }` | | `$or` | Logical OR (array) | `{ "$or": [ ... ] }` | Multiple conditions at the top level are combined with AND: ```json { "UserLabel": { "$like": "%pipe%" }, "Height": { "$gte": 10 } } ``` Use `$or` to combine conditions with OR: ```json { "$or": [ { "Category": "Structural" }, { "Category": "Mechanical" } ] } ``` Field names are validated against the asset's schema. Invalid names return a `400` error with "did you mean?" suggestions. ### DateTime Properties DateTime values are returned as ISO-8601 strings (e.g., `"2022-12-01T03:38:48.000"`). When filtering, use these strings directly — values matching `YYYY-MM-DDTHH:MM:SS` are automatically treated as DateTime literals: - **filter:** `{ "timestamp": { "$gt": "2022-01-01T00:00:00.000" } }` - **where:** `timestamp > '2022-12-01T03:38:48.000'` **`where`** accepts a raw SQL-style WHERE clause. Supported operators: | Operator | Description | | - | - | | `=` | Equal | | `!=` or `<>` | Not equal | | `>` | Greater than | | `>=` | Greater than or equal | | `<` | Less than | | `<=` | Less than or equal | | `LIKE` | Pattern match (use `%` as wildcard) | | `NOT LIKE` | Negated pattern match | | `IN (...)` | In a list of values | | `NOT IN (...)` | Not in a list of values | | `IS NULL` | Value is null | | `IS NOT NULL` | Value is not null | | `BETWEEN ... AND ...` | Value within a range | | `AND` | Logical AND | | `OR` | Logical OR | | `NOT` | Logical negation | Example: `UserLabel LIKE '%pipe%' OR Height >= 10` tags: - Asset Elements security: - OAuth2: - "assets:read" - AccessToken: - "assets:read" parameters: - in: query name: limit schema: type: integer default: 1000 example: 50 minimum: 1 maximum: 1000 description: The maximum number of elements to return. - in: query name: page schema: type: integer default: 1 minimum: 1 example: 1 description: The page number. - in: query name: filter schema: type: string example: '{"UserLabel":{"$like":"%pipe%"}}' description: A URL-encoded JSON object using MongoDB-style operators to filter elements. Cannot be combined with `where`. - in: query name: where schema: type: string example: "UserLabel LIKE '%pipe%'" description: A raw SQL-style WHERE clause to filter elements. Cannot be combined with `filter`. responses: 200: description: OK headers: Link: description: | Pagination links following [RFC 5988](https://tools.ietf.org/html/rfc5988). Contains `rel="next"` if more pages exist, and `rel="prev"` if the current page is greater than 1. schema: type: string example: '; rel="next"' content: application/json: schema: type: object properties: items: type: array description: A page of asset elements. items: $ref: "#/components/schemas/AssetElementMetadata" total: type: integer description: The total number of elements matching the query across all pages. examples: exampleResponse: value: { "items": [ { "id": "8796093022212", "location": { "center": { "longitude": -75.1652, "latitude": 39.9526, "height": 12.5, }, "radius": 5.0, }, "properties": { "className": "Wall", "userLabel": "Exterior Wall", }, }, ], "total": 1, } 400: description: Bad Request — returned when both `filter` and `where` are provided, or when either parameter is malformed. content: application/json: schema: type: object properties: code: type: string message: type: string examples: bothParams: summary: Both filter and where provided value: { "code": "BadRequest", "message": "Cannot use both 'filter' and 'where' parameters in the same request. Use one or the other.", } 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /assets/{assetId}/elements/{elementId}: parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/elementId" get: operationId: getAssetElement summary: Get info about an asset element description: | Retrieves metadata and location information for a specific element within an asset. tags: - Asset Elements security: - OAuth2: - "assets:read" - AccessToken: - "assets:read" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/AssetElementMetadata" examples: exampleResponse: value: { "id": "8796093022212", "location": { "center": { "longitude": -75.1652, "latitude": 39.9526, "height": 12.5, }, "radius": 5.0, }, "properties": { "className": "Wall", "userLabel": "Exterior Wall" }, } 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /assets/{assetId}/elements/{elementId}/snap: parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/elementId" post: operationId: postAssetElementSnap summary: Snap to an element description: | Performs a geometric snap operation on a specific element within an asset. Given a geographic test point near the element, this endpoint returns the closest snappable point on the element's geometry (e.g., a vertex, edge midpoint, or nearest point on a curve). The `snapMode` parameter controls the type of snap: | Value | Description | | - | - | | 1 | Nearest snap (default) | | 2 | Nearest key point | | 4 | Midpoint | | 8 | Center | | 16 | Origin | | 32 | Bisector | | 64 | Intersection | tags: - Experimental security: - OAuth2: - "assets:read" - AccessToken: - "assets:read" requestBody: required: true content: application/json: schema: type: object properties: testPoint: allOf: - $ref: "#/components/schemas/GeographicPoint" - description: The geographic point to snap from. closePoint: allOf: - $ref: "#/components/schemas/GeographicPoint" - description: An optional close point for the snap. Defaults to testPoint if not provided. worldToView: type: array description: A 4x4 matrix (array of 4 rows, each an array of 4 numbers) representing the world-to-view transformation. Defaults to the identity matrix. items: type: array items: type: number snapAperture: type: number description: The snap aperture (tolerance) in view coordinates. snapMode: type: integer description: The snap mode to use. Defaults to 1 (nearest). required: - testPoint examples: basicSnap: summary: Basic snap with just a test point value: { "testPoint": { "latitude": 39.9526, "longitude": -75.1652, "height": 12.5, }, } fullSnap: summary: Snap with all parameters value: { "testPoint": { "latitude": 39.9526, "longitude": -75.1652, "height": 12.5, }, "closePoint": { "latitude": 39.9527, "longitude": -75.1653, "height": 12.6, }, "snapMode": 2, } responses: 200: description: OK content: application/json: schema: type: object properties: status: type: integer description: The snap status code. 0 indicates success. example: 0 snapMode: type: integer description: The snap mode that was used. example: 1 heat: type: number description: A value indicating how close the snap point is to the test point. Lower is better. geomType: type: integer description: The geometry type of the snapped element. parentGeomType: type: integer description: The parent geometry type of the snapped element. hitPoint: allOf: - $ref: "#/components/schemas/GeographicPoint" - description: The geographic hit point on the element. snapPoint: allOf: - $ref: "#/components/schemas/GeographicPoint" - description: The snap point (the closest snappable geometry point). normal: type: object description: The surface normal at the snap point. properties: x: type: number y: type: number z: type: number curve: type: object description: The curve geometry near the snap point. required: - status examples: successfulSnap: value: { "status": 0, "snapMode": 1, "heat": 0, "geomType": 2, "snapPoint": { "latitude": 39.9526, "longitude": -75.1652, "height": 12.5, }, "hitPoint": { "latitude": 39.9526, "longitude": -75.1652, "height": 12.5, }, "normal": { "x": 0, "y": 0, "z": 1 }, } 400: description: Bad Request — returned when the request body is invalid, coordinate conversion fails, or the snap operation fails for the element. content: application/json: schema: type: object properties: code: type: string message: type: string examples: missingBody: summary: Missing request body value: { "code": "BadRequest", "message": "Request body is required", } snapFailed: summary: Snap failed value: { "code": "BadRequest", "message": "Snap failed for element 8796093022769: No snap possible for this element (element may lack snappable geometry or test point is too far)", } 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /assets/{assetId}/elements/properties: parameters: - $ref: "#/components/parameters/assetId" get: x-beta: true operationId: getAssetElementProperties summary: List element properties description: | Retrieves a paginated list of all properties that exist across elements in the asset. Each item includes the property name and its type. Only top-level primitive properties (strings, numbers, booleans) are included — nested objects and arrays are excluded. This is the same set of properties returned in the `properties` field of individual elements. The property names returned by this endpoint can be used with the [List distinct values for an element property](#tag/Experimental/operation/getAssetElementPropertyValues) endpoint to retrieve distinct values for a specific property. tags: - Experimental security: - OAuth2: - "assets:read" - AccessToken: - "assets:read" parameters: - in: query name: limit schema: type: integer default: 1000 example: 50 minimum: 1 maximum: 1000 description: The maximum number of property names to return. - in: query name: page schema: type: integer default: 1 minimum: 1 example: 1 description: The page number. responses: 200: description: OK headers: Link: description: | Pagination links following [RFC 5988](https://tools.ietf.org/html/rfc5988). Contains `rel="next"` if more pages exist, and `rel="prev"` if the current page is greater than 1. schema: type: string example: '; rel="next"' content: application/json: schema: type: object properties: items: type: array description: A page of element properties. items: type: object properties: name: type: string description: The property name. type: type: string description: The JavaScript type of the property value (e.g. `string`, `number`, `boolean`, `undefined`). required: - name - type total: type: integer description: The total number of element properties across all pages. examples: exampleResponse: value: { "items": [ { "name": "id", "type": "string" }, { "name": "classFullName", "type": "string" }, { "name": "model", "type": "string" }, { "name": "userLabel", "type": "string" }, { "name": "category", "type": "string" }, { "name": "federationGuid", "type": "string" }, ], "total": 6, } 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /assets/{assetId}/elements/properties/{propertyName}: parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/propertyName" get: x-beta: true operationId: getAssetElementPropertyValues summary: List distinct values for an element property description: | Retrieves a paginated list of distinct values for a specific property across all elements in the asset. The `propertyName` must be one of the names returned by the [List element property names](#tag/Experimental/operation/getAssetElementProperties) endpoint. If the property does not exist, a `400` error is returned. Only top-level primitive values (strings, numbers, booleans) are included. tags: - Experimental security: - OAuth2: - "assets:read" - AccessToken: - "assets:read" parameters: - in: query name: limit schema: type: integer default: 1000 example: 50 minimum: 1 maximum: 1000 description: The maximum number of values to return. - in: query name: page schema: type: integer default: 1 minimum: 1 example: 1 description: The page number. responses: 200: description: OK headers: Link: description: | Pagination links following [RFC 5988](https://tools.ietf.org/html/rfc5988). Contains `rel="next"` if more pages exist, and `rel="prev"` if the current page is greater than 1. schema: type: string example: '; rel="next"' content: application/json: schema: type: object properties: items: type: array description: A page of distinct values for the property. items: oneOf: - type: string - type: number - type: boolean total: type: integer description: The total number of distinct values across all pages. examples: exampleResponse: value: { "items": ["Exterior Wall", "Interior Wall", "Curtain Wall"], "total": 3, } 400: description: Bad Request. The property name does not exist on any element. 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /assets/{assetId}/elements/search: parameters: - $ref: "#/components/parameters/assetId" get: operationId: getAssetElementsSearch summary: Search elements of an asset description: | Searches elements within an asset by fulltext keyword search. Results are paginated with a maximum of 50 items per response. Use the `continuationToken` from the response to retrieve the next page. Only the following properties are indexed for search: | Property | Description | | - | - | | `id` | Unique instance identifier for the element. | | `userLabel` | Human-readable label for the element. | ### Tokenization Search input is split into words (tokens). Words are separated by spaces (e.g., `search phrase` becomes two tokens). Results matching more words are ranked higher. Results must match at least one word to be included. Additional word separators are applied automatically: | Rule | Example | | - | - | | Case change | `SearchPhrase` → `Search Phrase` | | Numbers | `search4phrase` → `search 4 phrase` | | Separators | `search:phrase!` → `search phrase` | ### Filters Search input is normalized before matching: | Filter | Example | | - | - | | ASCII folding | `Šęärčh Phrąšė` → `Search Phrase` | | Lowercase | `Search Phrase` → `search phrase` | ### Query syntax The search parameter supports the following operators: | Operator | Description | Example | | - | - | - | | `"…"` | Exact match (tokenization and filters still apply). | `"search phrase"` | | `+` | AND — results must contain both terms. | `search + phrase` | | `\|` | OR — results contain either term (default behavior). | `search \| phrase` | | `(…)` | Grouping. | `search + (green \| blue)` | | `*` | Prefix wildcard — matches terms starting with the prefix. | `sear*` | | `-` | NOT — excludes results containing the term. | `search + -phrase` | The characters `+ | " ( ) ' \` must be escaped by prefixing them with `\`. tags: - Experimental security: - OAuth2: - "assets:read" - AccessToken: - "assets:read" parameters: - in: query name: search required: true schema: type: string example: "Wall" description: The search term to match against indexed element properties. Supports [Lucene query syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html). - in: query name: continuationToken schema: type: string description: A token returned from a previous request to retrieve the next page of results. responses: 200: description: OK content: application/json: schema: type: object properties: items: type: array description: The matching asset elements. items: $ref: "#/components/schemas/AssetElementMetadata" total: type: integer description: The number of elements returned in this page. continuationToken: type: string description: A token to retrieve the next page of results. Absent when there are no more results. examples: exampleResponse: value: { "items": [ { "id": "8796093022212", "location": { "center": { "longitude": -75.1652, "latitude": 39.9526, "height": 12.5, }, "radius": 5.0, }, "properties": { "className": "Wall", "userLabel": "Exterior Wall", }, }, ], "total": 1, "continuationToken": "eyJza2lwIjoxMDAwfQ==", } 400: description: Bad Request. Returned when the asset does not have element indexing enabled. 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /v2/tokens: get: operationId: getTokens summary: List tokens description: | 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](https://tools.ietf.org/html/rfc5988) 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. tags: - Tokens security: - AccessToken: - "tokens:read" parameters: - in: query name: limit schema: type: integer default: 1000 example: 50 minimum: 1 maximum: 1000 description: 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. - in: query name: page schema: type: integer default: 1 minimum: 1 example: 3 description: The page number. - in: query name: search schema: type: string example: roads description: 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. - in: query name: sortBy schema: type: string example: NAME enum: [NAME, LAST_USED] description: The property by which to sort the results. - in: query name: sortOrder schema: type: string default: ASC example: ASC enum: [ASC, DESC] description: The order in which to sort the results. If undefined, tokens are sorted ascending. responses: 200: description: OK headers: link: $ref: "#/components/headers/link-next-prev" content: application/json: schema: title: Token Metadata type: object properties: items: type: array description: A page of tokens. items: $ref: "#/components/schemas/TokenMetadata" examples: exampleResponse: value: { "items": [ { "id": "58d917ab-f5df-494c-9109-66be3c53219d", "name": "An Access Token", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1OGQ5MTdhYi1mNWRmLTQ5NGMtOTEwOS02NmJlM2M1MzIxOWQiLCJpZCI6MiwiaWF0IjoxNjM0NTcyNTQzfQ.Cf055OJ96fdxw5NIBT0-JwD4aD9HjYQt9bf6CpadOGM", "isDefault": false, "dateLastUsed": "2021-10-18T15:55:43.977Z", "dateAdded": "2021-09-10T18:29:57.583Z", "dateModified": "2021-09-11T18:29:57.583Z", "scopes": [ "assets:list", "assets:read", "assets:write", "geocode", "profile:read", ], "assetIds": [], }, { "id": "8494d9bc-a0c7-46ac-b0f5-58bdd6a9724a", "name": "Another New Token", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI4NDk0ZDliYy1hMGM3LTQ2YWMtYjBmNS01OGJkZDZhOTcyNGEiLCJpZCI6MiwiaWF0IjoxNjMzOTgyNjk5fQ.JcD0nmNbO-vVQsoa5w8CudbsCeuN1d7Svmy_GzoehHg", "isDefault": false, "dateLastUsed": "2021-10-11T20:04:59.380Z", "dateAdded": "2021-09-09T18:29:57.583Z", "dateModified": "2021-09-10T18:29:57.583Z", "scopes": ["assets:read", "geocode"], "assetIds": [80, 98], }, ], } 401: $ref: "#/components/responses/401" post: operationId: postTokens summary: Create a new token description: | Add a new token which can be used for making ion API requests. tags: - Tokens security: - AccessToken: - "tokens:write" requestBody: required: true content: application/json: schema: type: object properties: name: $ref: "#/components/schemas/TokenName" assetIds: $ref: "#/components/schemas/TokenAssetIds" scopes: $ref: "#/components/schemas/TokenScopes" allowedUrls: $ref: "#/components/schemas/TokenAllowedUrls" required: - scopes examples: exampleBody: value: { "name": "Token", "scopes": ["assets:read", "geocode", "profile:read"], "assetIds": [98, 96, 94, 89], "allowedUrls": [ "https://example.com", "https://subdomain.example.com", "https://example.com/path/", "https://example.com:8080", ], } responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/TokenMetadata" examples: exampleResponse: value: { "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": ["assets:read", "geocode", "profile:read"], "assetIds": [98, 96, 94, 89], } 409: description: Invalid Request /v2/tokens/{tokenId}: parameters: - $ref: "#/components/parameters/tokenId" get: operationId: getToken summary: Get info about a token description: Retrieves metadata for a specific token. tags: - Tokens security: - AccessToken: - "tokens:read" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/TokenMetadata" 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" patch: operationId: patchToken summary: Modify token info description: | Updates the name, scopes, asset ids, allowed URLs, or expiration associated with the token. `assetIds`, `allowedUrls`, and `expiration` are signed into the token itself. Setting any of them to a value different from what the token currently has always regenerates the token's credentials, even if `regenerate` is not set: the previous encoded token stops working immediately, and the response contains the new one. `regenerate` can also be set on its own to force new credentials without changing anything else. tags: - Tokens security: - AccessToken: - "tokens:write" requestBody: required: true content: application/json: schema: type: object properties: name: $ref: "#/components/schemas/TokenName" assetIds: $ref: "#/components/schemas/PatchTokenAssetIds" scopes: $ref: "#/components/schemas/TokenScopes" allowedUrls: $ref: "#/components/schemas/PatchTokenAllowedUrls" expiration: description: The date and time after which the token is no longer valid, in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. Pass `null` to remove the expiration. Changing this value regenerates the token's credentials (see above). type: string format: date-time nullable: true example: "2027-03-19T13:17:02.838Z" regenerate: description: If true, replaces the token's credentials with newly generated ones, invalidating the previous encoded token, even if no other field is changing. type: boolean example: false responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/TokenMetadata" 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" delete: operationId: deleteToken summary: Delete a token description: Deletes a token. Does not support deleting the default token. tags: - Tokens security: - AccessToken: - "tokens:write" responses: 204: description: No Content 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /v2/tokens/default: get: operationId: getDefaultToken summary: Get the default token description: Retrieves metadata for the user's default token. tags: - Tokens security: - AccessToken: - "tokens:read" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/TokenMetadataDefaultToken" 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /experimental/panoramas/google: get: operationId: getExperimentalPanoramasGoogle summary: Access Google Street View description: | Get information about how to access to Google Street View Static API via Cesium ion. Calling this endpoint will counted as an imagery session for your Cesium ion imagery quota. See [Google Static Street View API](https://developers.google.com/maps/documentation/streetview/request-streetview). tags: - Experimental security: - OAuth2: - "assets:read" - AccessToken: - "assets:read" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/GooglePanoramasEndpoint" 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /assets/{assetId}/tileset-revisions: parameters: - $ref: "#/components/parameters/assetId" get: operationId: getTilesetRevisions summary: List 3D Tiles assets exported from the same BIM/CAD Database description: | Retrieves a paginated list of Cesium ion 3D Tiles assets that were exported from the same backing BIM/CAD Database as the specified asset. The specified asset may be either the BIM/CAD Database asset itself or any 3D Tiles asset exported from it. tags: - Experimental security: - OAuth2: - "assets:read" - AccessToken: - "assets:read" parameters: - in: query name: limit schema: type: integer default: 100 minimum: 1 maximum: 1000 description: The maximum number of assets to return. - in: query name: page schema: type: integer default: 1 minimum: 1 description: The page number. responses: 200: description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: assetId: type: integer description: The id of a Cesium ion 3D Tiles asset exported from the same BIM/CAD Database. example: 12345 creationTimestamp: type: string format: date-time description: The date and time when the BIM/CAD Database changeset the asset was exported from was created. example: "2024-01-15T12:00:00Z" 400: description: Bad Request. Returned when the asset is not backed by a BIM/CAD Database. 401: $ref: "#/components/responses/401" 404: $ref: "#/components/responses/404" /assets/compare: post: operationId: postAssetsCompare summary: Create a change detection report between two assets description: | Creates a change detection report asset comparing two Cesium ion assets exported from the same backing BIM/CAD Database and queues a job that generates the report asynchronously. The response is the metadata of the newly created report asset with a `type` of `CHANGE_DETECTION`. Use the asset's `status` and `percentComplete` to monitor progress; once the status is `COMPLETE`, the report data is available through the asset's endpoint. The `fromAssetId` asset must have been exported at an earlier BIM/CAD Database version than the `toAssetId` asset. tags: - Experimental security: - OAuth2: - "assets:write" - AccessToken: - "assets:write" requestBody: required: true content: application/json: schema: type: object required: - fromAssetId - toAssetId properties: fromAssetId: type: integer example: 12345 description: The id of the asset exported at the earlier BIM/CAD Database version. toAssetId: type: integer example: 12346 description: The id of the asset exported at the later BIM/CAD Database version. responses: 200: description: OK. The metadata of the newly created change detection report asset. The asset's `type` is `CHANGE_DETECTION`. content: application/json: schema: $ref: "#/components/schemas/AssetMetadata" 400: description: Bad Request. Returned when request body properties are missing or invalid, the assets are not backed by the same BIM/CAD Database, or the `fromAssetId` asset was not exported at an earlier BIM/CAD Database version than the `toAssetId` asset. 401: $ref: "#/components/responses/401" 404: description: Not Found. Returned when either asset does not exist. 409: description: Conflict. Returned when a change detection report already exists for the specified BIM/CAD Database versions and report type. The error message includes the id of the existing report asset. components: headers: link-next-prev: schema: type: string description: | An [RFC 5988](https://tools.ietf.org/html/rfc5988) 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. parameters: assetId: description: The asset identifier on which to perform the operation. in: path name: assetId schema: $ref: "#/components/schemas/AssetIdentifier" required: true tokenId: description: The unique identifier of the token on which to perform the operation. in: path name: tokenId schema: $ref: "#/components/schemas/TokenIdentifier" required: true labelId: description: The unique identifier of the label on which to perform the operation. in: path name: labelId schema: $ref: "#/components/schemas/LabelIdentifier" required: true archiveId: description: The unique identifier of a particular archive. in: path name: archiveId schema: $ref: "#/components/schemas/ArchiveIdentifier" required: true exportId: in: path name: exportId schema: $ref: "#/components/schemas/ExportIdentifier" required: true elementId: description: The unique identifier of the element within the asset. in: path name: elementId schema: $ref: "#/components/schemas/ElementIdentifier" required: true propertyName: description: The name of an element property, as returned by the element properties endpoint. in: path name: propertyName schema: type: string example: "userLabel" required: true schemas: AssetIdentifier: type: integer description: The unique identifier for this asset. example: 3812 TokenIdentifier: type: string description: The unique identifier of this token. example: a4538dc7-f583-4d9e-889e-35e2db4de534 readOnly: true LabelIdentifier: type: integer description: The unique identifier for this label. example: 17 ArchiveIdentifier: type: integer description: The unique identifier of this archive. example: 10 readOnly: true ElementIdentifier: type: string description: The unique identifier for an element within an asset. example: "8796093022212" readOnly: true ExportIdentifier: type: integer description: The unique identifier of this export. example: 1 readOnly: true Token: type: string description: The access token. example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1OGQ5MTdhYi1mNWRmLTQ5NGMtTEwOS02NmJlM2M1MzIxOWQiLCJpZCI6MiwiaWF0IjoxNjM0NTcyNTQzfQ.Cf055OJ6fdxw5NIBT0-JwD4aD9HjYQt9bf6CpadOGM LabelMetadata: type: object properties: id: $ref: "#/components/schemas/LabelIdentifier" name: $ref: "#/components/schemas/LabelName" color: $ref: "#/components/schemas/LabelResponseColor" required: - id - name - color LabelListItem: allOf: - $ref: "#/components/schemas/LabelMetadata" - type: object properties: assets: type: integer description: The number of assets currently using this label. example: 3 readOnly: true stories: type: integer description: The number of stories currently using this label. example: 1 readOnly: true required: - assets - stories AssetName: type: string description: The name of this asset. example: The Earth At Night TokenName: type: string description: The name of this token. example: New Token LabelName: type: string description: The name of this label. example: Priority LabelColor: type: string description: The label color encoded as a CSS hex string. example: "#404040" LabelResponseColor: type: string description: The label color encoded as a CSS hex string. example: "#404040" ArchiveFormat: type: string enum: - ZIP - TILESET - GLTF description: | 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 | example: ZIP GeographicPoint: type: object description: A geographic point defined by longitude, latitude, and height. properties: longitude: type: number description: The longitude in degrees. example: -75.1652 latitude: type: number description: The latitude in degrees. example: 39.9526 height: type: number description: The height in meters. example: 12.5 required: - longitude - latitude - height AssetElementLocation: type: object description: The geographic location and bounding sphere of an element. properties: center: $ref: "#/components/schemas/GeographicPoint" radius: type: number description: The radius of the bounding sphere in meters. example: 5.0 required: - center - radius AssetElementProperties: type: object description: A flat key-value map of element properties. Only top-level primitive values (strings, numbers, booleans) are included. additionalProperties: true example: className: "Wall" userLabel: "Exterior Wall" AssetElementMetadata: title: Asset Element type: object properties: id: $ref: "#/components/schemas/ElementIdentifier" location: allOf: - $ref: "#/components/schemas/AssetElementLocation" description: The geographic location of the element. This field is absent when the asset does not have a Geographic Coordinate System defined. properties: $ref: "#/components/schemas/AssetElementProperties" required: - id - properties GooglePanoramasEndpoint: title: "Google Panoramas Endpoint" type: object properties: type: type: string enum: - GOOGLE_STREETVIEW_STATIC options: type: object properties: url: description: The base url of the Google Maps API server to be used in place of `https://maps.googleapis.com/maps/api/streetview`. type: string example: "https://assets.cesium.com/proxy/0/maps/api/streetview" key: description: A temporary token which allows access to the Google Maps API. This token should not be cached as its value will change over time. Used as the `key` query string value. type: string example: "" TokenAssetIds: description: The ids of the assets that can be accessed using this token. If undefined, the token can access all assets associated with the account. type: array items: $ref: "#/components/schemas/AssetIdentifier" example: [90, 98, 99, 100] LabelIds: description: The ids of labels to apply to an asset. Provide an empty array to remove all labels from the asset. type: array items: $ref: "#/components/schemas/LabelIdentifier" example: [17, 23] TokenAllowedUrls: description: The URLs from which this token can be accessed. If undefined, the token can be accessed from any URL. type: array example: [ "https://example.com", "https://subdomain.example.com", "https://example.com/path/", "https://example.com:8080", ] PatchTokenAllowedUrls: description: The URLs from which this token can be accessed. Set to `null` if you want your token to be accessed from any URL. type: array example: [ "https://example.com", "https://subdomain.example.com", "https://example.com/path/", "https://example.com:8080", ] PatchTokenAssetIds: description: 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. type: array items: $ref: "#/components/schemas/AssetIdentifier" example: [90, 98, 99, 100] AssetDescription: type: string description: A Markdown string describing this asset. example: The Earth at night, also known as [The Black Marble](https://earthobservatory.nasa.gov/Features/NightLights/). AssetStatus: type: string enum: - AWAITING_FILES - NOT_STARTED - IN_PROGRESS - COMPLETE - ERROR - DATA_ERROR description: | 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. | example: COMPLETE readOnly: true ArchiveStatus: type: string enum: - NOT_STARTED - IN_PROGRESS - COMPLETE - ERROR description: | 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. | example: COMPLETE readOnly: true AssetArchiveOptions: type: object discriminator: propertyName: type mapping: FULL: "#/components/schemas/FullArchiveOptions" CLIP_LATITUDE_LONGITUDE_RECTANGLE: "#/components/schemas/LatitudeLongitudeClipArchiveOptions" properties: type: $ref: "#/components/schemas/ArchiveType" assetIds: type: array description: | 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](#archive-clip-requirements). For a full archive of a single asset the asset must be marked as archivable. items: $ref: "#/components/schemas/AssetIdentifier" required: - assetIds - type PackedLatitudeLongitudeRectangle: type: array description: | Array of four radian values: [west, south, east, north]. items: type: number example: [ -1.3194169616700622, 0.6988112052237774, -1.319410651520469, 0.698813516991245, ] LatitudeLongitudeClipArchiveOptions: type: object allOf: - $ref: "#/components/schemas/AssetArchiveOptions" - properties: format: $ref: "#/components/schemas/ArchiveFormat" clipRegion: $ref: "#/components/schemas/PackedLatitudeLongitudeRectangle" name: type: string description: Name of the archive. required: - format - name - clipRegion example: { "assetIds": [13123], "format": "GLTF", "type": "CLIP_LATITUDE_LONGITUDE_RECTANGLE", "clipRegion": [ -1.3194169616700622, 0.6988112052237774, -1.319410651520469, 0.698813516991245, ], "name": "Park", } FullArchiveOptions: type: object allOf: - $ref: "#/components/schemas/AssetArchiveOptions" - properties: format: $ref: "#/components/schemas/ArchiveFormat" required: - format example: { "assetIds": [13123], "format": "ZIP", "type": "FULL" } ArchiveType: type: string enum: - FULL - CLIP_LATITUDE_LONGITUDE_RECTANGLE description: | 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. | | CLIP_LATITUDE_LONGITUDE_RECTANGLE | Archive contains data around a rectangle defined by latitude and longitude. | example: FULL ExportStatus: type: string enum: - NOT_STARTED - QUEUED - IN_PROGRESS - COMPLETE - ERROR description: | Describes the state of the export process: | Value | Description | | - | - | | NOT_STARTED | The server received 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. | example: COMPLETE readOnly: true TokenScopes: type: array items: type: string enum: - assets:list - assets:limited-list - assets:read - assets:write - geocode - profile:read - labels:read - labels:write - tokens:read - tokens:write description: | Defines the [scope](#tag/Authentication) of this particular token. example: [profile:read] ReconstructionOutputType: type: string enum: - LAS - "3DTILES" - SPLATS_3DTILES description: The type of output to generate. Specifying `3DTILES` will generate a 3D Tiles mesh output, specifying `LAS` will generate a 3D Tiles point cloud asset, and specifying `SPLATS_3DTILES` will generate a Gaussian splats output. example: LAS AssetType: type: string enum: - "3DTILES" - GLTF - IMAGERY - TERRAIN - KML - CZML - GEOJSON description: This asset's [type](#tag/Assets). example: "3DTILES" TextureFormatBuildings: type: string enum: - AUTO - KTX2 description: | Controls the format of textures in the 3D Tiles tileset. | Value | Description | | - | - | | AUTO | Automatically select between PNG or JPG on an image-by-image basis to produce the smallest tileset compatible with all 3D Tiles clients. | | KTX2 | [KTX v2.0](https://www.khronos.org/ktx/) is an image container format that supports [Basis Universal supercompression](https://github.com/BinomialLLC/basis_universal#basis_universal). Use KTX2 compression to create a smaller tileset with better streaming performance. | default: AUTO TextureFormatCapture: type: string enum: - AUTO - WEBP - KTX2 description: | Controls the format of textures in the 3D Tiles tileset. | Value | Description | | - | - | | AUTO | Automatically select between PNG or JPG on an image-by-image basis to produce the smallest tileset compatible with all 3D Tiles clients. | | KTX2 | [KTX v2.0](https://www.khronos.org/ktx/) is an image container format that supports [Basis Universal supercompression](https://github.com/BinomialLLC/basis_universal#basis_universal). Use KTX2 compression to create a smaller tileset with better streaming performance. | default: AUTO TextureFormatModel: type: string enum: - AUTO - WEBP description: | Controls the format of textures in the 3D Tiles tileset. | Value | Description | | - | - | | AUTO | Automatically select between PNG or JPG on an image-by-image basis to produce the smallest tileset compatible with all 3D Tiles clients. | | WEBP | Use WebP images to create a smaller tileset with better streaming performance. 3D Tiles produced with this option require a client, such as CesiumJS, that supports the [EXT_texture_webp](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/EXT_texture_webp) glTF extension and a browser that supports WebP, such as Chrome or Firefox 65 and newer. | default: AUTO GeometryCompression: type: string enum: - NONE - DRACO - MESHOPT - QUANTIZATION description: | Controls the type of compression applied to geometry when creating a 3D Tiles tileset. | Value | Description | | - | - | | NONE | Disable geometry compression. | | DRACO | [Draco compression](https://google.github.io/draco/) is a type of geometric compression optimized for smaller file sizes. 3D Tiles produced with this option require a client, such as CesiumJS, that supports the [KHR_draco_mesh_compression](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_draco_mesh_compression) glTF extension. | | MESHOPT | [Meshopt](https://github.com/zeux/meshoptimizer#vertexindex-buffer-compression) geometric compression is optimized for runtime performance. 3D Tiles produced with this option require a client, such as CesiumJS, that supports the [EXT_meshopt_compression](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_meshopt_compression) glTF extension. | | QUANTIZATION | [Quantization](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_mesh_quantization/README.md) conducts vertex quantization by storing positions as integers rather than floats. 3D Tiles produced with this option require a client, such as CesiumJS, that supports the [KHR_mesh_quantization](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_mesh_quantization/README.md) glTF extension. default: DRACO AssetEndpointAttribution: type: object properties: html: description: An HTML string defining the asset's required attribution. The rendered HTML must be accessible to the end users of your application. type: string example: 'Cesium ion' collapsible: description: If true, the rendered HTML must be shown on screen as long as the associated asset is also on screen. If false, the HTML can be shown on a separate panel or page. type: boolean example: false AssetEndpoint: title: Asset Endpoint type: object properties: type: $ref: "#/components/schemas/AssetType" url: description: | The entry point url of the tileset, depending on the asset type. This url should be treated as an opaque link as the actual format may change any time. Do not cache it. Any URL manipulation should be done by parsing the URL, rather than through string manipulation. | Value | Description | Example | | - | - | - | | 3DTILES | The complete path to the tileset.json | https://assets.cesium.com/23912/tileset.json?v=4 | | TERRAIN | The base url of the terrain tileset | https://eu.assets.cesium.com/1da20c7e8-bb91-4d7f-9879-9d1bdb943422/ | | IMAGERY | The base url for both a TMS and WMTS compatible tileset | https://assets.ion.cesium.com/2194/ | | GLTF | The complete path to the model | https://assets.cesium.com/21944/model.glb | | KML | The complete path to the KML document | https://assets.cesium.com/KMLs/doc.kml | | CZML | The complete path to the CZML document | https://assets.ion.cesium.com/2367/doc.czml | | GEOJSON | The complete path to the GeoJSON document | https://assets.cesium.com/45387/doc.geojson | For terrain and imagery, simply append the desired file or tile to the base url. For example, to retrieve the capabilities file for a WMTS imagery layer using the above example: https://assets.cesium.com/2194/WMTSCapabilities.xml. This url should not be cached across application instances as it can change over time. type: string example: "https://assets.cesium.com/23912/tileset.json" accessToken: description: The token to be included with each tile request, using Bearer format. This token is different than the access token used throughout the rest of the REST API. It provides access to the asset for approximately one hour. To continue using the asset after the allotted time, simple re-request the endpoint for a new token. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyMjZmNzU0Yy02ZmVkLTQ4ODktOTUyMC0zMDRlMmNjODdiMzEiLCJpZCI6NDQsImFzc2V0cyI6eyIxIjp7InR5cGUiOiJURVJSQUlOIiwiZXh0ZW5zaW9ucyI6W3RydWUsdHJ1ZSx0cnVlXSwicHVsbEFwYXJ0VGVycmFpbiI6ZmFsc2V9fSwic3JjIjoiOGE2NjVmYmMtZDQzMy00ZmMxLWE3NDgtNjRhYWE3MjFiOTgzIiwiaWF0IjoxNTU0MTI4NTUzLCJleHAiOjE1NTQxMzIxNTN9.CWjqdF1LORmCd7nVbHupXyIjCPOfuSOpXwQoaQU_a94 attributions: type: array items: $ref: "#/components/schemas/AssetEndpointAttribution" BingAssetEndpoint: title: Bing Asset Endpoint type: object allOf: - $ref: "#/components/schemas/ExternalAssetEndpoint" - properties: options: type: object properties: url: description: The url of the Bing Maps server. type: string mapStyle: type: string description: The style of Bing imagery tiles to load. mapLayer: type: string description: If defined, contains additional map layer template parameters to be passed to the Bing API. key: description: A temporary token which allows access to the Bing Maps API. This token should not be cached as its value will change over time. type: string Google2dMapsAssetEndpoint: title: Google Maps Endpoint type: object allOf: - $ref: "#/components/schemas/ExternalAssetEndpoint" - properties: options: type: object properties: url: description: The base url of the Google Maps API server to be used in place of `https://tile.googleapis.com`. type: string key: description: A temporary token which allows access to the Google Maps API. This token should not be cached as its value will change over time. Used as the `key` query string value. type: string session: description: The session token which allows access to the Google Maps API. This token should not be cached as its value will change over time. Used as the `session` query string value. type: string tileWidth: type: number description: The width of the tiles measured in pixels. tileHeight: type: number description: The width of the tiles measured in pixels. imageFormat: type: string description: The image format, which can be either `"png"` or `"jpeg"`. External3DTilesAssetEndpoint: title: External 3D Tiles Asset Endpoint type: object allOf: - $ref: "#/components/schemas/ExternalAssetEndpoint" - properties: options: type: object properties: url: description: The url of the 3D Tiles tileset. type: string ExternalAssetEndpoint: title: External Asset Endpoint type: object discriminator: propertyName: externalType mapping: BING: "#/components/schemas/BingAssetEndpoint" 3DTILES: "#/components/schemas/External3DTilesAssetEndpoint" GOOGLE_2D_MAPS: "#/components/schemas/Google2dMapsAssetEndpoint" properties: externalType: type: string description: Provides credentials and options to access a third-party services. example: "BING" type: $ref: "#/components/schemas/AssetType" attributions: type: array items: $ref: "#/components/schemas/AssetEndpointAttribution" example: { "externalType": "BING", "type": "IMAGERY", "options": { "url": "https://dev.virtualearth.net", "mapStyle": "AerialWithLabels", "key": "Ap_cv0-5RHFzEgGUenjAWOcyLvj3xbpHqRJl7qwejJBF_rPrqtiYIQlWedpauan4", }, "attributions": [ { "html": 'Cesium ion', "collapsible": false, }, ], } AssetAttribution: type: string description: A Markdown compatible string containing any required attribution for this asset. Clients will be required to display this attribution to end users. example: "[NASA](https://earthobservatory.nasa.gov/image-use-policy)" AssetMetadata: title: Asset Metadata type: object properties: id: $ref: "#/components/schemas/AssetIdentifier" name: $ref: "#/components/schemas/AssetName" description: $ref: "#/components/schemas/AssetDescription" attribution: $ref: "#/components/schemas/AssetAttribution" type: $ref: "#/components/schemas/AssetType" bytes: description: The number of bytes this asset occupies in the user's account. type: integer example: 8675309 minimum: 0 readOnly: true dateAdded: description: The date and time that this asset was created in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. type: string format: date-time example: "2019-03-19T13:17:02.838Z" readOnly: true status: $ref: "#/components/schemas/AssetStatus" percentComplete: type: integer description: The percentage progress of the tiling pipeline preparing this asset. minimum: 0 maximum: 100 example: 100 readOnly: true archivable: type: boolean description: If true the asset can be archived else if false the asset cannot be archived. example: false readOnly: true exportable: type: boolean description: | `true` if this asset can be used with the exports API, `false` otherwise. example: true readOnly: true labels: type: array description: The labels currently applied to this asset. items: $ref: "#/components/schemas/LabelMetadata" readOnly: true options: $ref: "#/components/schemas/AssetOptions" from: $ref: "#/components/schemas/AssetFrom" creatorId: type: integer description: The userId of the user that created this asset; `undefined` for premium assets example: 123 readOnly: true creatorUsername: type: string description: The username of the user that created this asset, `undefined` for premium assets, or if the user has been deleted example: "example user" readOnly: true required: - name - type - options # QuickAddAssets: # title: Quick Add Assets # type: object # properties: # name: # $ref: "#/components/schemas/AssetName" # objectName: # description: The name of the main asset. In most cases this will be the same as `name`, but in the cases of assets with raster overlays, this will be the non-imagery asset. # type: string # readOnly: true # description: # $ref: "#/components/schemas/AssetDescription" # assetId: # $ref: "#/components/schemas/AssetIdentifier" # type: # $ref: "#/components/schemas/AssetType" # subscribed: # type: boolean # description: | # `true` if the user is subscribed to the asset, `false` otherwise. # readOnly: true # rasterOverlays: # type: array # description: The raster overlays available for this asset # items: # $ref: "#/components/schemas/QuickAddRasterOverlays" # required: # - name # - objectName # - description # - assetId # - type # QuickAddRasterOverlays: # title: Quick Add Raster Overlays # type: object # properties: # name: # $ref: "#/components/schemas/AssetName" # example: Bing Maps Aerial # assetId: # $ref: "#/components/schemas/AssetIdentifier" # subscribed: # type: boolean # description: | # `true` if the user is subscribed to the asset, `false` otherwise. # example: true # readOnly: true # required: # - name # - assetId TokenExpiration: description: The date and time after which the token is no longer valid, in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. Not present if the token never expires. type: string format: date-time example: "2027-03-19T13:17:02.838Z" TokenMetadata: title: Token Metadata type: object properties: id: $ref: "#/components/schemas/TokenIdentifier" name: $ref: "#/components/schemas/TokenName" token: $ref: "#/components/schemas/Token" dateAdded: description: The date and time that this token was created in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. type: string format: date-time example: "2019-03-19T13:17:02.838Z" readOnly: true dateModified: description: The date and time that this token was last modified in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. type: string format: date-time example: "2019-03-19T13:17:02.838Z" readOnly: true dateLastUsed: description: The date and time that this token was last used in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. type: string format: date-time example: "2019-03-19T13:17:02.838Z" readOnly: true assetIds: $ref: "#/components/schemas/TokenAssetIds" isDefault: description: True if this token is the default token, else false. type: boolean example: false readOnly: true allowedUrls: $ref: "#/components/schemas/TokenAllowedUrls" scopes: $ref: "#/components/schemas/TokenScopes" expiration: $ref: "#/components/schemas/TokenExpiration" required: - scopes ArchiveMetadata: title: Archive Metadata type: object properties: id: $ref: "#/components/schemas/ArchiveIdentifier" assetId: $ref: "#/components/schemas/AssetIdentifier" format: $ref: "#/components/schemas/ArchiveFormat" status: $ref: "#/components/schemas/ArchiveStatus" bytesArchived: type: integer description: The total number of bytes of the archive that has been processed. minimum: 0 example: 1024 readOnly: true ArchiveMetadata2: title: Archive Metadata type: object discriminator: propertyName: type mapping: FULL: "#/components/schemas/ArchiveMetadata2Full" CLIP_LATITUDE_LONGITUDE_RECTANGLE: "#/components/schemas/ArchiveMetadata2WithClip" properties: id: $ref: "#/components/schemas/ArchiveIdentifier" name: type: string assetIds: type: array items: $ref: "#/components/schemas/AssetIdentifier" format: $ref: "#/components/schemas/ArchiveFormat" status: $ref: "#/components/schemas/ArchiveStatus" bytesArchived: type: integer description: The total number of bytes of the archive that has been processed. minimum: 0 example: 1024 readOnly: true type: $ref: "#/components/schemas/ArchiveType" ArchiveMetadata2WithClip: allOf: - $ref: "#/components/schemas/ArchiveMetadata2" - properties: clipRegion: $ref: "#/components/schemas/PackedLatitudeLongitudeRectangle" ArchiveMetadata2Full: allOf: - $ref: "#/components/schemas/ArchiveMetadata2" ExportMetadata: title: Export Metadata type: object properties: id: $ref: "#/components/schemas/ExportIdentifier" assetId: $ref: "#/components/schemas/AssetIdentifier" status: $ref: "#/components/schemas/ExportStatus" bytesExported: type: integer description: The total number of bytes that have been exported. minimum: 0 example: 1024 readOnly: true dateAdded: description: The date and time at which this export was added in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. type: string format: date-time example: "2022-09-20T16:16:02.838Z" readOnly: true to: $ref: "#/components/schemas/AssetTo" TokenMetadataDefaultToken: title: Token Metadata type: object properties: id: $ref: "#/components/schemas/TokenIdentifier" name: $ref: "#/components/schemas/TokenName" token: $ref: "#/components/schemas/Token" dateAdded: description: The date and time that this token was created in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. type: string format: date-time example: "2019-03-19T13:17:02.838Z" readOnly: true dateModified: description: The date and time that this token was last modified in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. type: string format: date-time example: "2019-03-19T13:17:02.838Z" readOnly: true dateLastUsed: description: The date and time that this token was last used in [RFC 3339](https://tools.ietf.org/html/rfc3339) format. type: string format: date-time example: "2019-03-19T13:17:02.838Z" readOnly: true assetIds: $ref: "#/components/schemas/TokenAssetIds" isDefault: description: True if this token is the default token, else false. type: boolean example: true readOnly: true scopes: $ref: "#/components/schemas/TokenScopes" required: - scopes AwsCredentials: description: Contains credential information for Amazon Web Services. properties: accessKey: type: string description: An AWS Access Key ID secretAccessKey: type: string description: An AWS Secret Access Key sessionToken: type: string description: The session token. Only required when using STS temporary credentials. required: - accessKey - secretAccessKey AzureCredentials: description: Contains credential information for Azure Storage. Only one type credentials may be specified. Either accessKey only, sasToken only or tenantId/clientId/clientSecret. writeOnly: true properties: accessKey: type: string description: An Azure Storage Access Key sasToken: type: string description: An Azure Storage SAS Token with Read/Write/List permissions tenantId: type: string description: An Azure Tenant ID clientId: type: string description: An Azure Client ID clientSecret: type: string description: An Azure Client Secret AwsLocation: description: Contains location information for S3 properties: bucket: type: string description: The name of the S3 bucket to export to example: "destination.bucket" prefix: type: string description: The destination prefix to export to example: "destinationPrefix" required: - bucket AzureLocation: description: Contains location information for Azure Storage properties: account: type: string description: The name of the Azure Storage account to export to container: type: string description: The name of the Azure Storage container to export to prefix: type: string description: The prefix to export to required: - account - container AssetTo: discriminator: propertyName: type mapping: S3: "#/components/schemas/S3Export" AZURE: "#/components/schemas/AzureExport" description: Contains information about the type and destination of the export. properties: type: type: string enum: - S3 - AZURE description: Specifies the type of external service. Currently only Amazon S3 and Azure are supported. required: - type AssetToInlineCredentials: discriminator: propertyName: type mapping: S3: "#/components/schemas/S3ExportInlineCredentials" AZURE: "#/components/schemas/AzureExportInlineCredentials" description: Contains information about the type and destination of the export. properties: type: type: string enum: - S3 - AZURE description: Specifies the type of external service. Currently only Amazon S3 and Azure are supported. required: - type S3Export: type: object allOf: - $ref: "#/components/schemas/AssetTo" - $ref: "#/components/schemas/AwsLocation" - required: - bucket S3ExportInlineCredentials: type: object writeOnly: true allOf: - $ref: "#/components/schemas/AssetToInlineCredentials" - $ref: "#/components/schemas/AwsLocation" - $ref: "#/components/schemas/AwsCredentials" AzureExport: type: object allOf: - $ref: "#/components/schemas/AssetTo" - $ref: "#/components/schemas/AzureLocation" AzureExportInlineCredentials: type: object writeOnly: true allOf: - $ref: "#/components/schemas/AssetToInlineCredentials" - $ref: "#/components/schemas/AzureLocation" - $ref: "#/components/schemas/AzureCredentials" AssetFrom: discriminator: propertyName: type mapping: S3: "#/components/schemas/S3Import" SKETCHFAB: "#/components/schemas/SketchfabImport" AZURE: "#/components/schemas/AzureImport" description: When supplied, contains options for tiling source files hosted by external services. When using AWS S3, the size of the resulting tileset, not the size of the source data, is counted against your account storage quota. writeOnly: true properties: type: type: string enum: - S3 - AZURE - SKETCHFAB description: Specifies the type of external service. Currently only Amazon S3, Azure and Sketchfab are supported. To import from Sketchfab, you must link your Sketchfab account to your ion account on your [user account page](https://ion.cesium.com/account) and specify `options.sourceType` as `3D_MODEL` or `3D_CAPTURE`. required: - type S3Import: type: object allOf: - $ref: "#/components/schemas/AssetFrom" - properties: bucket: type: string description: The name of the S3 bucket to import data from credentials: $ref: "#/components/schemas/AwsCredentials" keys: type: array description: Contains zero or more Keys to retrieve. minimum: 0 items: type: string prefixes: type: array description: Contains zero or more Prefixes which will be used to retrieve all matching Keys. minimum: 0 items: type: string - required: - bucket - credentials AzureImport: type: object allOf: - $ref: "#/components/schemas/AssetFrom" - properties: account: type: string description: The name of the Azure Storage account to import data from container: type: string description: The name of the Azure Storage container to import data from credentials: $ref: "#/components/schemas/AzureCredentials" keys: type: array description: Contains zero or more Keys to retrieve. minimum: 0 items: type: string prefixes: type: array description: Contains zero or more Prefixes which will be used to retrieve all matching Keys. minimum: 0 items: type: string - required: - account - container - credentials SketchfabImport: type: object allOf: - $ref: "#/components/schemas/AssetFrom" - properties: modelId: type: string description: The id of the Sketchfab model to import - required: - modelId IModelImportOptions: type: object properties: iModelId: type: string description: id of the iModel to import. name: allOf: - $ref: "#/components/schemas/AssetName" description: The name of the asset. When omitted, the name is derived from the iModel name and the imported changeset's creation timestamp. changesetIndex: type: integer minimum: 1 description: "**Experimental.** The iModel changeset index to import. When omitted, the latest changeset is imported." example: 10 required: - iModelId AssetOptions: description: Contains options specific to the type of source data being uploaded. writeOnly: true discriminator: propertyName: sourceType mapping: RASTER_IMAGERY: "#/components/schemas/ImageryRasterOptions" RASTER_TERRAIN: "#/components/schemas/TerrainRasterOptions" TERRAIN_DATABASE: "#/components/schemas/TerrainDatabaseOptions" CITYGML: "#/components/schemas/CityGmlOptions" KML: "#/components/schemas/KmlOptions" 3D_CAPTURE: "#/components/schemas/3DCaptureOptions" BIM_CAD: "#/components/schemas/BimCadOptions" BIM_CAD_DB: "#/components/schemas/BimCadDbOptions" 3D_MODEL: "#/components/schemas/3DModelOptions" POINT_CLOUD: "#/components/schemas/PointCloudOptions" 3DTILES: "#/components/schemas/3DTilesOptions" CZML: "#/components/schemas/CzmlOptions" GEOJSON: "#/components/schemas/GeoJsonOptions" properties: sourceType: type: string description: | The type of data being uploaded. | Value | Description | | - | - | | RASTER_IMAGERY | Imagery data in any [supported raster format](https://cesium.com/learn/3d-tiling/tiler-data-formats/#supported-data-formats) | | RASTER_TERRAIN | Terrain data as a single a single band of floating point or integer elevations in any [supported raster format](https://cesium.com/learn/3d-tiling/tiler-data-formats/#supported-data-formats) | | TERRAIN_DATABASE | A single Cesium Terrain Database file | | CITYGML | CityGML with associated textures | | KML | KML or KMZ file with associated COLLADA models and textures | | 3D_CAPTURE | An OBJ, COLLADA, or glTF model created through photogrammetry processes | | BIM_CAD | An IFC, OBJ or glTF model created through a BIM/CAD design process | | BIM_CAD_DB | A design model in IFC, Revit, DWG, DXF or DGN formats. | | 3D_MODEL | An OBJ, COLLADA, or glTF model created through 3D scanning processes | | POINT_CLOUD | A LASer or LAZ point cloud. A PLY file for gaussian splats | | 3DTILES | A pre-tiled 3D Tiles tileset | | CZML | A CZML file with associated models and textures | | GEOJSON | A GeoJSON files. | Select a value from the list to see options specific to the selected type. Not all types provide additional options. required: - sourceType ImageryRasterOptions: type: object description: Multiple different outputs can be generated of type `3DTILES` or `LAS` for a reconstruction job. Only one `SPLATS_3DTILES` output is allowed. allOf: - $ref: "#/components/schemas/AssetOptions" - properties: outputs: type: array description: "This option is only valid when passed along with `type: 3DTILES`. An array of outputs to generate from the reconstruction job. At least one `3DTILES` mesh output is required. Only one `SPLATS_3DTILES` output is allowed. Multiple outputs of type `LAS` and `3DTILES` can be generated. The specifyable properties for each output type can be found at [Options3DTiles](https://developer.bentley.com/apis/reality-modeling/operations/jobs-create/#options3dtiles), [OptionsLas](https://developer.bentley.com/apis/reality-modeling/operations/jobs-create/#optionslas), and [GaussianSplatsOptions](https://developer.bentley.com/apis/reality-modeling/operations/jobs-create/#gaussiansplatsoptions)." items: type: object required: - outputType properties: outputType: $ref: "#/components/schemas/ReconstructionOutputType" options: type: object description: "An optional object that controls the output settings for this output. The specifyable properties depend on the `outputType`: [Options3DTiles](https://developer.bentley.com/apis/reality-modeling/operations/jobs-create/#options3dtiles), [OptionsLAS](https://developer.bentley.com/apis/reality-modeling/operations/jobs-create/#optionslas), or [GaussianSplatsOptions](https://developer.bentley.com/apis/reality-modeling/operations/jobs-create/#gaussiansplatsoptions)." name: type: string description: An optional string that specifies the name of the asset to be generated. If provided, this overrides the name in the main options object. fillImageJob: type: object description: "This option is only valid when passed along with `type: 3DTILES`. Specifies properties to control the fill image properties process. The specifyable properties are listed at [FillImageJob](https://developer.bentley.com/apis/reality-modeling/operations/jobs-create/#fillimagepropertiesoptions)." calibrationJob: type: object description: "This option is only valid when passed along with `type: 3DTILES`. Specifies properties to control the calibration process. The specifyable properties are listed at [CalibrationJob](https://developer.bentley.com/apis/reality-modeling/operations/jobs-create/#calibrationoptions)." reconstructionJob: type: object description: "This option is only valid when passed along with `type: 3DTILES`. Specifies properties to control the reconstruction job process. The specifyable properties are listed at [ReconstructionJob](https://developer.bentley.com/apis/reality-modeling/operations/jobs-create/#reconstructionjoboptions)." TerrainRasterOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" - properties: heightReference: type: string enum: - MEAN_SEA_LEVEL - WGS84 description: By default, the source data's vertical datum is used as the base height which elevation values are relative to. Specifying this property will override that behavior. Set to `WGS84` to force use of the WSG84 ellipsoid or `MEAN_SEA_LEVEL` to force use of the EGM96 MSL model. If not specified and no vertical datum is available, `WGS84` is used. example: MEAN_SEA_LEVEL toMeters: type: number description: When specified, overrides the units of the vertical axis and provides the constant scale factor to apply to input elevation values in order to convert them to meters. Setting this property is only useful in the rare case that the vertical axis has different units than the horizontal axis. example: 1.0 baseTerrainId: type: integer description: By default, any area of the earth not covered by the provided terrain will have an elevation of mean sea level. By specifying the asset identifier of an existing terrain tileset, the new terrain will be placed on top of the referenced terrain to create a new derived dataset. Void values in the source terrain will also be blended with the existing underlying terrain data. example: 1 waterMask: type: boolean description: Set to `true` to treat elevation values at sea level as water. This will add a water mask to the terrain tileset. Typically, this value is only set to true when tiling a global tileset. default: false TerrainDatabaseOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" CityGmlOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" - properties: textureFormat: $ref: "#/components/schemas/TextureFormatBuildings" geometryCompression: $ref: "#/components/schemas/GeometryCompression" disableColors: type: boolean description: When set to true, ignores color information and creates all white geometry. default: false disableTextures: type: boolean description: When set to true, ignores texture information and uses the underlying geometry color. default: false clampToTerrain: type: boolean description: | When terrain clamping is enabled, CityGML will adjust the height of the following object types so that they lay flat on the WGS84 ellipsoid, or specified `baseTerrainId`. * CityFurniture * GroundSurface * Track * Road * Railway * Square * ReliefFeature * LandUse * TransportationObject default: false baseTerrainId: type: integer description: By default, `clampToTerrain` will be place models on the WGS84 ellipsoid. If a terrain asset id is specified, objects will be placed on top of the referenced terrain. example: 1 KmlOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" - properties: textureFormat: $ref: "#/components/schemas/TextureFormatBuildings" geometryCompression: $ref: "#/components/schemas/GeometryCompression" baseTerrainId: type: integer description: By default, KML will use the WGS84 ellipsoid as the reference ground height for models. If a terrain asset id is specified, models will used the height of the referenced terrain instead. This is only available if AssetType is 3DTILES. example: 1 PositionOrientationOptions: type: object properties: position: type: array description: The origin of the tileset in [longitude, latitude, height] format in EPSG:4326 coordinates and height in meters. This value is ignored if the source data already contains georeferencing information. minItems: 3 maxItems: 3 items: type: number 3DCaptureOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" - $ref: "#/components/schemas/PositionOrientationOptions" - properties: inputCrs: type: string description: "The coordinate reference system to apply to the data. Overrides any CRS embedded in the data itself. Can be specified as a WKT, proj string, or EPSG string." geometryCompression: $ref: "#/components/schemas/GeometryCompression" textureFormat: $ref: "#/components/schemas/TextureFormatCapture" BimCadOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" - $ref: "#/components/schemas/PositionOrientationOptions" - properties: inputCrs: type: string description: "The coordinate reference system to apply to the data. Overrides any CRS embedded in the data itself. Can be specified as a WKT, proj string, or EPSG string." geometryCompression: type: string enum: - NONE - DRACO - MESHOPT - QUANTIZATION description: | Controls the type of compression applied to geometry when creating a 3D Tiles tileset. | Value | Description | | - | - | | NONE | Disable geometry compression. | | DRACO | [Draco compression](https://google.github.io/draco/) is a type of geometric compression optimized for smaller file sizes. 3D Tiles produced with this option require a client, such as CesiumJS, that supports the [KHR_draco_mesh_compression](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_draco_mesh_compression) glTF extension. | | MESHOPT | [Meshopt](https://github.com/zeux/meshoptimizer#vertexindex-buffer-compression) geometric compression is optimized for runtime performance. 3D Tiles produced with this option require a client, such as CesiumJS, that supports the [EXT_meshopt_compression](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_meshopt_compression) glTF extension. | | QUANTIZATION | [Quantization](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_mesh_quantization/README.md) conducts vertex quantization by storing positions as integers rather than floats. 3D Tiles produced with this option require a client, such as CesiumJS, that supports the [KHR_mesh_quantization](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_mesh_quantization/README.md) glTF extension. default: DRACO textureFormat: type: string enum: - AUTO - KTX2 description: | Controls the format of textures in the 3D Tiles tileset. | Value | Description | | - | - | | AUTO | Automatically select between PNG or JPG on an image-by-image basis to produce the smallest tileset compatible with all 3D Tiles clients. | | KTX2 | [KTX v2.0](https://www.khronos.org/ktx/) is an image container format that supports [Basis Universal supercompression](https://github.com/BinomialLLC/basis_universal#basis_universal). Use KTX2 compression to create a smaller tileset with better streaming performance. | default: AUTO BimCadDbOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" - $ref: "#/components/schemas/PositionOrientationOptions" - properties: inputCrs: type: string description: "The coordinate reference system to apply to the data. Overrides any CRS embedded in the data itself. Can be specified as an EPSG string." heightReference: type: string enum: - MEAN_SEA_LEVEL - WGS84 - NAVD88 - NGVD29 description: If not embedded in the file, use this vertical datum as the base height which elevation values are relative to. This option is only valid if advanced is set to true. skipMesh: type: boolean description: If set, excludes mesh geometry from the resulting 3D Tiles tileset. default: false skipLines: type: boolean description: If set, excludes line geometry from the resulting 3D Tiles tileset. default: false skipText: type: boolean description: If set, excludes text geometry from the resulting 3D Tiles tileset. default: false baseAssetId: type: integer description: | The id of an existing BIM/CAD Database (`BIM_CAD_DB`) asset to re-upload source files to. When set, the upload creates a new mesh based on the updated version of the BIM/CAD Database. example: 123456 existingFileBehavior: type: string enum: - KEEP description: | How source files from the previous version that are not part of the new upload are treated. Required when `baseAssetId` is set. Currently must be set to `KEEP` 3DModelOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" - $ref: "#/components/schemas/PositionOrientationOptions" - properties: geometryCompression: $ref: "#/components/schemas/GeometryCompression" textureFormat: $ref: "#/components/schemas/TextureFormatModel" optimize: type: boolean description: Optimizes the model for rendering by combining primitives and textures. This is only available if AssetType is GLTF. default: false PointCloudOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" - $ref: "#/components/schemas/PositionOrientationOptions" - properties: geometryCompression: $ref: "#/components/schemas/GeometryCompression" inputCrs: type: string description: "The coordinate reference system to apply to the data. Overrides any CRS embedded in the data itself. Can be specified as a WKT, proj string, or EPSG string." gaussianSplats: type: boolean description: "If set, runs the gaussian splat pipeline on the provided point cloud. The source data provided must be in the PLY format" 3DTilesOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" - properties: tilesetJson: type: string description: The relative path of the main JSON file that will be the entry point to load the tileset. example: "tileset.json" required: - tilesetJson CzmlOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" GeoJsonOptions: type: object allOf: - $ref: "#/components/schemas/AssetOptions" - properties: lodProperty: type: string description: | Converting GeoJSON data to 3D Tiles is currently in technical preview and is not intended for production use. This option is only valid when passed along with `type: 3DTILES`. Property key used to rank and discard features during LOD simplification. For example, using `volume` for polylines encoding traffic information will prioritize higher volume roads closer to the tileset root. If omitted or property key is not found, simplification falls back to geometry size. simplificationLevel: type: string enum: - LOW - MEDIUM - HIGH description: | Converting GeoJSON data to 3D Tiles is currently in technical preview and is not intended for production use. This option is only valid when passed along with `type: 3DTILES`. Controls how aggressive the simplification will be. `LOW` corresponds to less simplification and thus denser elements in view. | Value | Description | | - | - | | LOW | Less simplification and denser elements in view. | | MEDIUM | The default simplification level. | | HIGH | More aggressive simplification. | default: MEDIUM responses: 401: description: Invalid Credentials 402: description: Plan Upgrade Required 404: description: Resource Not Found securitySchemes: OAuth2: description: | All Cesium ion endpoints require authentication in the form of an access token provided in the `Authorization` header of the request. ion uses the OAuth 2.0 `Bearer ` format. type: oauth2 flows: authorizationCode: authorizationUrl: https://cesium.com/ion/oauth/ tokenUrl: https://api.cesium.com/oauth/tokens scopes: assets:list: List the metadata for all assets available to the account. assets:limited-list: List the metadata for selected assets available to the account. assets:read: Read metadata and access the tiled data for individual assets available to the account. assets:write: Create, modify, and delete assets in the account. labels:read: List labels in the account. labels:write: Create, modify, and delete labels in the account. geocode: Enables the CesiumJS geocoder. Note geocoding via the REST API is not yet supported. profile:read: Read your username, email address, avatar, and storage quota. archives:read: List and download asset archives. archives:write: Create and delete asset archives. exports:read: List asset exports. exports:write: Export assets. tokens:read: Read token metadata and list all tokens for the account. AccessToken: description: | A Cesium ion access token provided as a Bearer token in the `Authorization` header. An access token can be used anywhere an OAuth 2.0 token can, with the same scopes, and additionally supports the `tokens:write` scope, which is not available via OAuth 2.0 since granting a third-party OAuth client the ability to create, modify, and delete a user's other tokens is out of scope for delegated access. type: http scheme: bearer