Urban Sky Real-time Balloon Telemetry

# generated: '2026-07-21'
# method: generated
# source: https://docs.urbansky.com/ (getting-started, basic-telemetry, api/javascript)
# note: Urban Sky publishes no AsyncAPI document. This spec was generated
#   faithfully from the documented Urban Sky SDK WebSocket event surface and
#   the data types published in the SDK API reference. Event names, fields,
#   and examples are taken verbatim from the docs; nothing is invented.
asyncapi: 3.0.0
info:
  title: Urban Sky Real-time Balloon Telemetry
  version: current
  description: >-
    Real-time balloon telemetry feed delivered over WebSocket by the Urban Sky
    SDK (JavaScript and Python). Clients authenticate with an
    organization-scoped API token and receive push updates for balloon and
    unassigned-device telemetry. Generated by API Evangelist from the published
    SDK documentation at https://docs.urbansky.com/ - Urban Sky does not
    publish an AsyncAPI document.
  externalDocs:
    url: https://docs.urbansky.com/
defaultContentType: application/json
servers:
  production:
    host: api.ops.atmosys.com
    protocol: wss
    description: >-
      Default SDK baseUrl (https://api.ops.atmosys.com); the SDK maintains the
      WebSocket connection and reconnects automatically.
    security:
      - $ref: '#/components/securitySchemes/apiToken'
channels:
  balloonUpdate:
    address: 'balloon:update'
    description: Balloon telemetry update received when a balloon's position changes.
    messages:
      balloonUpdate:
        $ref: '#/components/messages/balloonUpdate'
  unassignedDevices:
    address: 'unassigned:devices'
    description: Telemetry for devices not currently assigned to a balloon.
    messages:
      unassignedDevices:
        $ref: '#/components/messages/unassignedDevices'
operations:
  receiveBalloonUpdate:
    action: receive
    channel:
      $ref: '#/channels/balloonUpdate'
  receiveUnassignedDevices:
    action: receive
    channel:
      $ref: '#/channels/unassignedDevices'
components:
  securitySchemes:
    apiToken:
      type: httpApiKey
      name: x-api-token
      in: header
      description: Organization-scoped Urban Sky API token (issued by support).
  messages:
    balloonUpdate:
      name: balloonUpdate
      title: Balloon update
      payload:
        $ref: '#/components/schemas/BalloonUpdate'
    unassignedDevices:
      name: unassignedDevices
      title: Unassigned devices update
      payload:
        type: object
        properties:
          devices:
            type: array
            items:
              $ref: '#/components/schemas/Device'
  schemas:
    BalloonUpdate:
      type: object
      required: [balloonId, missionId, devices]
      properties:
        balloonId:
          type: string
          description: Unique balloon identifier
          examples: ['BLN-2024-001']
        missionId:
          type: string
          description: Associated mission ID
          examples: ['MSN-2024-001']
        devices:
          type: array
          description: Array of device telemetry
          items:
            $ref: '#/components/schemas/Device'
    Device:
      type: object
      required: [deviceId, deviceType, lat, lng, timestamp]
      properties:
        deviceId:
          type: string
          description: Unique device identifier
          examples: ['PLD-001']
        deviceType:
          type: string
          description: Device type - PLD (payload), APX (apex), BLS (ballaster)
          examples: ['PLD', 'APX', 'BLS']
        lat:
          type: number
          description: Latitude in decimal degrees
        lng:
          type: number
          description: Longitude in decimal degrees
        altitude:
          type: number
          description: Altitude in meters (when available)
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp