Cesium Asset Elements API

openapi: 3.2.0
info:
  title: Cesium ion Asset Elements API
  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.'
servers:
- url: https://api.cesium.com
  description: Cesium ion API Server
security:
- OAuth2: []
tags:
- name: Asset Elements
  description: The Asset Elements API provides a mechanism to query individual elements within an asset.
paths:
  /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 |

        | `= 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: <https://api.cesium.com/v1/assets/123/elements?limit=50&page=2>; 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'
components:
  schemas:
    ElementIdentifier:
      type: string
      description: The unique identifier for an element within an asset.
      example: '8796093022212'
      readOnly: true
    AssetIdentifier:
      type: integer
      description: The unique identifier for this asset.
      example: 3812
    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
    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
    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
    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
  parameters:
    elementId:
      description: The unique identifier of the element within the asset.
      in: path
      name: elementId
      schema:
        $ref: '#/components/schemas/ElementIdentifier'
      required: true
    assetId:
      description: The asset identifier on which to perform the operation.
      in: path
      name: assetId
      schema:
        $ref: '#/components/schemas/AssetIdentifier'
      required: true
  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 <your_access_token>` 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