Cesium Labels API

openapi: 3.2.0
info:
  title: Cesium ion Labels 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: 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.'
paths:
  /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'
components:
  schemas:
    LabelMetadata:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/LabelIdentifier'
        name:
          $ref: '#/components/schemas/LabelName'
        color:
          $ref: '#/components/schemas/LabelResponseColor'
      required:
      - id
      - name
      - color
    LabelColor:
      type: string
      description: The label color encoded as a CSS hex string.
      example: '#404040'
    LabelIdentifier:
      type: integer
      description: The unique identifier for this label.
      example: 17
    LabelName:
      type: string
      description: The name of this label.
      example: Priority
    LabelResponseColor:
      type: string
      description: The label color encoded as a CSS hex string.
      example: '#404040'
    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
  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:
    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
  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