Nimble WebSocket API v1

Nimble's WebSocket API (Application Programming Interface) enables users to subscribe to real-time streaming data and events. Behind this API is a software layer that routes data, arbitrates resources and executes Deep Learning and analytics functions to enable enriched business insights at world-class speed.

The latest online documentation can be found here.

The Key Elements of Nimble

Nimble and the WebSocket API have six key elements: Configuration, Source, Sink, Pipeline, Channel, and Stream.
A Configuration is a collection of Sources, Sinks and Pipeline Elements arranged to execute the desired analytic behavior.
A Source brings data into Nimble.
A Sink pushes data out of Nimble.
A Pipeline is made up of processing elements that perform some analytics task.
Since a Source can be shared between multiple Pipelines, a Channel is an abstraction of both a Source and a Pipeline that can be thought of as "the data brought in by this Source is operated on by this Pipeline".
A Stream is a proxied fMP4 video stream from a Source.

WebSocket topics

There are three WebSocket topic categories:

  • /config : allows you to subscribe to notifications about the changes in the Configuration.
  • /exports : allows you to subscribe to the metadata output of the Channel as well as inspect Channel properties such as its current Configuration, processing rate (FPS), and latency.
  • /stats : allows you to subscribe to Nimble's system-level details such as current CPU and Memory load.

WebSocket PUB/SUB

In the context of this API, PUB and SUB do not have the traditional meaning:
Publishing (PUB) to a WebSocket does not redistribute that data to other subscribers - only the server (Nimble) sends data to subscribers. Instead, publishing allows the client to configure an open WebSocket session with the server according to the endpoint's PUB specification. On the other hand, an endpoint's SUB specification defines the messages that clients will receive over the connection from Nimble. Note: Only after a client subscribes to an endpoint (by establishing the WebSocket connection) can it publish JSON to configure the session.

Operations

  • PUB /v1/config/notify

    Notification events for changes to the Configuration.

    Specify which events to subscribe to.

    Operation IDconfig-subscribe

    Accepts the following message:

    Configuration notification subscriptionConfigNotificationSubscription

    Subscribe or unsubscribe from Configuration events.

    oneOf

    Examples

  • SUB /v1/config/notify

    Notification events for changes to the Configuration.

    Open a WebSocket connection to receive notification events for changes in the Configuration.

    Operation IDconfig-notify

    Accepts the following message:

    Configuration notificationConfigNotification

    Global Configuration change notification.

    oneOf

    Examples

  • PUB /v1/exports/notify

    Notification events for changes to the Exports.

    Specify which events to subscribe to.

    Operation IDexports-subscribe

    Accepts the following message:

    Exports notification subscriptionExportsNotificationSubscription

    Subscribe or unsubscribe from events.

    oneOf

    Examples

  • SUB /v1/exports/notify

    Notification events for changes to the Exports.

    Open a WebSocket connection to receive notification events for changes to the Exports.

    Operation IDexports-notify

    Accepts the following message:

    Exports notificationExportsNotification

    Exports changed notification

    oneOf

    Examples

  • PUB /v1/exports/channels/metadata

    Multi-Channel metadata streaming.

    Specify which channels to subscribe to.

    Operation IDchannels-metadata-subscribe

    Accepts the following message:

    Channels subscriptionChannelsSubscription

    Specify which Channels to subscribe to.

    oneOf

    Examples

  • SUB /v1/exports/channels/metadata

    Multi-Channel metadata streaming.

    Receive JSON metadata from all inferencing Channels.

    Operation IDchannels-metadata

    Accepts the following message:

    Channel metadata with IDChannelMetadataWithID

    Metadata for a frame of video extracted by the inferencing Channel.

    oneOf
    uid: ChannelMultipartWithID

    Examples

  • PUB /v1/exports/channels/notify

    Multi-Channel event notification.

    Specify which channels to subscribe to.

    Operation IDchannels-notify-subscribe

    Accepts the following message:

    Channels subscriptionChannelsSubscription

    Specify which Channels to subscribe to.

    oneOf

    Examples

  • SUB /v1/exports/channels/notify

    Multi-Channel event notification.

    Receive notification events for updates to Channels.

    Operation IDchannels-notify

    Accepts the following message:

    Channel notification with IDChannelNotificationWithID

    Channel statistics changed notification.

    allOf

    Examples

  • SUB /v1/exports/channel/{id}/metadata

    Channel metadata streaming.

    Receive JSON metadata from an inferencing Channel.

    Operation IDchannel-metadata
    id
    required
    number
    format: int32>= 0uid: id

    The ID of the Channel to connect to.

    Accepts the following message:

    Channel metadataChannelMetadata

    Metadata for a frame of video extracted by the inferencing Channel.

    oneOf
    uid: ChannelMultipart

    Examples

  • PUB /v1/exports/channel/{id}/notify

    Channel event notification.

    Specify which events to subscribe to.

    Operation IDchannel-notify-subscribe
    id
    required
    number
    format: int32>= 0uid: id

    The ID of the Channel to connect to.

    Accepts the following message:

    Channel notification subscriptionChannelNotificationSubscription

    Subscribe or unsubscribe from Channel events.

    oneOf

    Examples

  • SUB /v1/exports/channel/{id}/notify

    Channel event notification.

    Receive notification events for updates to specific Channel.

    Operation IDchannel-notify
    id
    required
    number
    format: int32>= 0uid: id

    The ID of the Channel to connect to.

    Accepts the following message:

    Channel notificationChannelNotification

    Channel statistic changed notification.

    oneOf
    uid: ChannelNotifications

    Examples

  • SUB /v1/exports/stream/{id}

    Video streaming.

    Receive a binary stream of fragmented MP4 video.

    Operation IDmp4-video-stream
    id
    required
    number
    format: int32>= 0uid: id

    The ID of the Stream to connect to.

    Accepts one of the following messages:

    • #0Stream statusStreamStatus

      Stream status indication.

      oneOf

      Examples

    • #1Stream dataStreamData

      Fragmented MP4 video Stream data.

      Payload
      string
      format: binary

      Examples

  • PUB /v1/stats/notify

    Notification events for updates to the Statistics.

    Specify which events to subscribe to.

    Operation IDstats-subscribe

    Accepts the following message:

    Global statistics notification subscriptionStatsNotificationSubscription

    Subscribe or unsubscribe from events.

    oneOf

    Examples

  • SUB /v1/stats/notify

    Notification events for updates to the Statistics.

    Receive notification events for updates to Statistics.

    Operation IDstats-notify

    Accepts the following message:

    Global stats notificationStatsNotification

    Global statistics changed notification.

    oneOf

    Examples

Messages

  • #1Configuration notification subscriptionConfigNotificationSubscription

    Subscribe or unsubscribe from Configuration events.

    oneOf
  • #2Configuration notificationConfigNotification

    Global Configuration change notification.

    oneOf
  • #3Exports notification subscriptionExportsNotificationSubscription

    Subscribe or unsubscribe from events.

    oneOf
  • #4Exports notificationExportsNotification

    Exports changed notification

    oneOf
  • #5Channels subscriptionChannelsSubscription

    Specify which Channels to subscribe to.

    oneOf
  • #6Channel notification subscriptionChannelNotificationSubscription

    Subscribe or unsubscribe from Channel events.

    oneOf
  • #7Channel notificationChannelNotification

    Channel statistic changed notification.

    oneOf
    uid: ChannelNotifications
  • #8Channel notification with IDChannelNotificationWithID

    Channel statistics changed notification.

    allOf
  • #9Channel metadataChannelMetadata

    Metadata for a frame of video extracted by the inferencing Channel.

    oneOf
    uid: ChannelMultipart
  • #10Channel metadata with IDChannelMetadataWithID

    Metadata for a frame of video extracted by the inferencing Channel.

    oneOf
    uid: ChannelMultipartWithID
  • #11Stream statusStreamStatus

    Stream status indication.

    oneOf
  • #12Stream dataStreamData

    Fragmented MP4 video Stream data.

    Payload
    string
    format: binary
  • #13Global statistics notification subscriptionStatsNotificationSubscription

    Subscribe or unsubscribe from events.

    oneOf
  • #14Global stats notificationStatsNotification

    Global statistics changed notification.

    oneOf

Schemas

  • ConfigNotificationType
    string
    uid: ConfigNotificationType
      Allowed values:
    • "source"
    • "sink"
    • "pipeline"
  • ConfigNotificationAction
    string
    uid: ConfigNotificationAction
      Allowed values:
    • "created"
    • "updated"
    • "stats"
    • "deleted"
  • object
    uid: ConfigNotificationItem
  • allOf
    uid: ConfigSourceNotificationItem
  • allOf
    uid: ConfigSourceCreated
  • allOf
    uid: ConfigSourceUpdated
  • allOf
    uid: ConfigSourceStats
  • allOf
    uid: ConfigSourceDeleted
  • allOf
    uid: ConfigSinkNotificationItem
  • allOf
    uid: ConfigSinkCreated
  • allOf
    uid: ConfigSinkUpdated
  • allOf
    uid: ConfigSinkStats
  • allOf
    uid: ConfigSinkDeleted
  • allOf
    uid: ConfigPipelineNotificationItem
  • allOf
    uid: ConfigPipelineCreated
  • allOf
    uid: ConfigPipelineUpdated
  • allOf
    uid: ConfigPipelineStats
  • allOf
    uid: ConfigPipelineDeleted
  • ExportsNotificationType
    string
    uid: ExportsNotificationType
      Allowed values:
    • "channel"
    • "stream"
  • ExportsNotificationAction
    string
    uid: ExportsNotificationAction
      Allowed values:
    • "created"
    • "deleted"
  • object
    uid: ExportsNotificationItem
  • allOf
    uid: ExportsChannelNotificationItem
  • allOf
    uid: ExportsChannelCreated
  • allOf
    uid: ExportsChannelDeleted
  • allOf
    uid: ExportsStreamNotificationItem
  • allOf
    uid: ExportsStreamCreated
  • allOf
    uid: ExportsStreamDeleted
  • object
    uid: ChannelsQuerySubscription
  • object
    uid: ChannelMetadataQuerySubscription
  • ChannelNotificationType
    string
    uid: ChannelNotificationType
      Allowed values:
    • "fps"
    • "latency"
  • oneOf
    uid: ChannelNotifications
  • object
    uid: ChannelNotification
  • allOf
    uid: ChannelFPS

    The processing frame rate of the channel

  • allOf
    uid: ChannelLatency

    The processing latency of the channel

  • ChannelMetadataTimestamp
    number
    format: doubleuid: ChannelMetadataTimestamp

    Media presentation timestamp (PTS)

  • ChannelJpeg
    string
    format: bytemedia type: image/jpegencoding: base64uid: ChannelJpeg

    Optional Jpeg image

  • oneOf
    uid: ChannelMultipart
  • oneOf
    uid: ChannelMultipartWithID
  • StreamReset
    string
    uid: StreamReset

    Indicates the video has reached end-of-stream and is restarting.

    Const:"reset"
  • StatsType
    string
    uid: StatsType
      Allowed values:
    • "uptime"
    • "cpu"
    • "memory"
  • object
    uid: Stat
  • allOf
    uid: StatUptime

    The uptime (in seconds) since Nimble started

  • allOf
    uid: StatCPU

    The CPU load (measured in CPU threads utilized)

  • allOf
    uid: StatMemory

    The amount of memory used (measured in bytes)