Device Data Hub WebSocket API

The Device Data Hub WebSocket API lets you consume data from Device Data Hub¹. It is a JSON-RPC based WebSocket API.

Version history

Version	Date	Description
1.0.0	2026-05-25	Initial version

Identification

• AXIS OS: 12.11 or later
• API Discovery²: id=datahub-streaming-over-websocket

Use cases

Connect to Device Data Hub

The first step is to establish a WebSocket connection to the vapix/ws/v1 endpoint. Include data-hub in the apis query parameter to establish a session with Device Data Hub:

wss://<device>/vapix/ws/v1?apis=data-hub

For information about authenticating the connection, see Authentication.

List available topics

Topics identify the data streams available from Device Data Hub. Use the data-hub_v1:listTopics method to retrieve the topics that can be subscribed to. This method takes an empty object as params and returns a topics array:

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "data-hub_v1:listTopics",
    "params": {}
}

Response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {
        "topics": [{ "name": "some.topic" }, { "name": "other.topic" }]
    }
}

Subscribe to data

Subscribe to one or more topics using the data-hub_v1:subscribe method to receive matching data samples. Multiple subscriptions can be created with different filters, and each subscription is identified by its unique subscriptionId. Subscriptions may include filters for instance or data values and may request historical data. See data-hub_v1:subscribe for details about filtering.

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "data-hub_v1:subscribe",
    "params": {
        "subscriptionId": "subscription-1",
        "filters": [
            {
                "topics": ["some.Topic", "other.Topic"]
            }
        ]
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {
        "subscriptionId": "subscription-1"
    }
}

Receive data from Data Hub

The device sends matching data samples through the data-hub_v1:topicSample notification. Each message includes the subscriptionId and topic, along with the sample data and timestamp.

Message

{
    "jsonrpc": "2.0",
    "method": "data-hub_v1:topicSample",
    "params": {
        "subscriptionId": "subscription-1",
        "topic": "some.Topic",
        "instance": {
            "key0": "value0"
            //additional key-value pairs
        },
        "data": {
            //topic sample data
        },
        "timestamp": "2026-03-17T09:39:52.569Z",
        "isHistorical": false
    }
}

Remove a subscription

Use the data-hub_v1:unsubscribe method to remove an existing subscription by providing the ID of the subscription. Other subscriptions in the session remain active.

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "data-hub_v1:unsubscribe",
    "params": {
        "subscriptionId": "subscription-1"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {}
}

Remove all subscriptions

Use the data-hub_v1:unsubscribeAll method to remove all existing subscriptions in the WebSocket session.

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "data-hub_v1:unsubscribeAll",
    "params": {}
}

Response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {}
}

List existing subscriptions

Use the data-hub_v1:listSubscriptions method to retrieve all active subscriptions in the WebSocket session. The response includes each subscription's subscriptionId and other details.

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "data-hub_v1:listSubscriptions",
    "params": {}
}

Response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {
        "subscriptions": [
            {
                "subscriptionId": "subscription-1",
                "filters": [
                    {
                        "topics": ["some.Topic", "other.Topic"],
                        "instanceFilter": [],
                        "dataFilter": []
                    }
                ],
                "startFrom": {
                    "position": "new"
                }
            }
            //additional subscriptions
        ]
    }
}

API specification

This API uses JSON-RPC over a WebSocket connection. Establish the connection through the vapix/ws/v1 endpoint with the apis query parameter set to or including data-hub.

wss://<device>/vapix/ws/v1?apis=data-hub

Requests and responses use the JSON-RPC format described below.

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "<METHOD>",
    "params": {
        //method parameters
    }
}

The id is a client-defined identifier used to match the response to the request. The method specifies the API operation to perform, and params contains the parameters required by that method.

Successful response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {
        //method result data
    }
}

The id identifies the request to which the response belongs. The result object contains the data returned by the requested method.

Error response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "error": {
        "code": -32700,
        "message": "Invalid JSON",
        "data": {
            //additional error data
        }
    }
}

The id identifies the request that failed. The error object contains an error code, a description in message, and optional additional information in data. Possible error codes are defined in the Errors section.

Methods

The following methods are defined as part of this API.

listTopics

Use the data-hub_v1:listTopics method to get a list of available topics. This method takes an empty object as params. The returned data contains an array of available topics:

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "data-hub_v1:listTopics",
    "params": {}
}

Parameter	Required	Description
{}	Yes	An empty object. No parameters are required to list the available topics.

Response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {
        "topics": [
            { "name": "topic.name.1" },
            { "name": "topic.name.2" }
            //additional topics
        ]
    }
}

Result	Description
topics	An array containing the available topics.
topics[].name	The name of the topic.

subscribe

Use the data-hub_v1:subscribe method to subscribe to one or multiple topics. A subscription can include an instance filter, a data filter, or a starting position for historical data. Use subscriptionId to identify the subscription, and create multiple subscriptions when different filters are needed. Each WebSocket session supports up to 10 subscriptions, and up to 10 WebSocket sessions can be active concurrently.

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "data-hub_v1:subscribe",
    "params": {
        "subscriptionId": "subscription-1",
        "filters": [
            {
                "topics": ["topic.name.1"],
                "instanceFilter": [{ "key-1": "value-1" }],
                "dataFilter": ["expression"]
            }
        ],
        "startFrom": {
            "position": "new"
        }
    }
}

Parameter	Required	Description
subscriptionId	No	Identifies the subscription. If omitted, the device assigns a unique ID.
filters	Yes	Contains the filter used to select the topics and data samples. The array currently supports one filter object.
filters[].topics	Yes	Lists of topics to subscribe to. Minimum one topic is required.
filters[].instanceFilter	No	Filters samples by instance key-value pairs.
filters[].dataFilter	No	Filters samples using jq-style expressions.
startFrom	No	Specifies the position from which samples are received.
startFrom.position	No	Set to oldest to include historical samples, or new to receive only new samples. Defaults to new.

Response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {
        "subscriptionId": "subscription-1"
    }
}

Result	Description
subscriptionId	The unique identifier assigned to the subscription. Use this ID to identify the subscription when receiving samples, listing subscriptions, or removing the subscription.

unsubscribe

Use the data-hub_v1:unsubscribe method to remove an existing subscription by providing the ID of the subscription. Other subscriptions in the session remain active.

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "data-hub_v1:unsubscribe",
    "params": {
        "subscriptionId": "subscription-1"
    }
}

Parameter	Required	Description
subscriptionId	Yes	Identifies the subscription to remove.

Response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {}
}

Result	Description
{}	Indicates that the subscription was removed successfully.

unsubscribeAll

Use the data-hub_v1:unsubscribeAll method to remove all existing subscriptions.

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "data-hub_v1:unsubscribeAll",
    "params": {}
}

Parameter	Required	Description
{}	Yes	An empty object. No parameters are required to remove all subscriptions.

Response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {}
}

Result	Description
{}	Indicates that all subscriptions were removed successfully.

listSubscriptions

Use the data-hub_v1:listSubscriptions method to list all existing subscriptions.

Request

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "method": "data-hub_v1:listSubscriptions",
    "params": {}
}

Parameter	Required	Description
{}	Yes	An empty object. No parameters are required to list the subscriptions.

Response

{
    "jsonrpc": "2.0",
    "id": "Client defined request ID",
    "result": {
        "subscriptions": [
            //list of subscription objects
        ]
    }
}

Result	Description
subscriptions	An array containing the active subscriptions in the WebSocket session. The same subscription object structure as used in the data-hub_v1:subscribe method is returned.

topicSample

The device uses the data-hub_v1:topicSample method to send matching samples to the client. Each message includes the subscriptionId, the topic sample, and other details. This method is a notification, so no id field is included and no response is expected from the client.

Notification

{
    "jsonrpc": "2.0",
    "method": "data-hub_v1:topicSample",
    "params": {
        "subscriptionId": "subscription-1",
        "topic": "some.topic",
        "instance": { "key-1": "value-1" },
        "data": {
            //topic data
        },
        "timestamp": "2026-03-17T09:39:52.569Z",
        "isHistorical": false
    }
}

Parameter	Required	Description
subscriptionId	Yes	Identifies the subscription that the sample matches.
topic	Yes	Identifies the topic from which the sample was received.
instance	Yes	Contains the instance key-value pairs associated with the sample.
data	Yes	Contains the topic sample data.
timestamp	Yes	Indicates when the sample was produced, in ISO 8601 date-time format.
isHistorical	Yes	Indicates whether the sample was cached before the subscription started.

Errors

Error codes returned are defined in the following Common error codes and Data Hub specific error codes sections.

Common error codes

Code	Meaning
-32700	Invalid JSON
-32600	Invalid request
-32601	Method not found
-32602	Invalid parameter value specified
-32603	Internal error
2100	API version not supported
2105	Authorization failed
2107	Transport level error

Data Hub specific error codes

Code	Meaning
1200	No such subscription

Authentication

The API supports Basic and Digest authentication. A session token can also be used to authenticate the WebSocket connection.

A session token can be generated by making the following request. The request requires Basic or Digest authentication.

curl

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  "http://<device>/axis-cgi/wssession.cgi"

HTTP

GET /axis-cgi/wssession.cgi
Host: <device>

The device responds with the session token in the payload:

HTTP/1.1 200 OK
Content-Type: text/plain

<session-token>

The token is valid for 15 seconds. Include the returned token in the WebSocket connection URL before it expires:

wss://<device>/vapix/ws/v1?wssession=<session-token>&apis=data-hub

Note: It is strongly recommended to use HTTPS and WSS for secure connections. HTTP and WS transmit data without encryption and are not secure.

Footnotes

1. Device Data Hub (DDH) is an on-device data exchange system built on a publish/subscribe (pub/sub) model. It lets applications and services on an Axis device share data with each other and with external consumers in a structured, decoupled way. ↩

2. Axis VAPIX Library: API Discovery. ↩