API’s for business applications

Overview

When devices publish data to Live Objects, there are two ways for applications to retrieve this data:

  • mode RESTful API: designed for applications that retrieve Data and Events via HTTPS using a RESTful API architecture. This mode is stateless, meaning each request is independent and the server does not maintain a session.

  • Broker / "Application mode" : Customer Applications (backend) retrieve Data and Events from FIFO queues, pushed according to Notification rules. Using MQTT protocol, this mode supports stateful sessions, allowing MQTT clients to maintain persistent subscriptions without losing messages.

Both modes provide access to the same types of messages, but they differ in protocol, session handling, and delivery guarantees.

REST APIs

API endpoints

https://liveobjects.orange-business.com/api/

Currently, two version coexist "v0" and "v1". As a consequence all methods described in this document are available on URLs starting by:

https://liveobjects.orange-business.com/api/v0/

or

https://liveobjects.orange-business.com/api/v1/

Some v0 methods have been deprecated and replaced by v1 methods.

Principles

All the functionalities of Live Objects are available on the REST APIs. It is the same API that is used by the Live Objects web portal.

Content

By default all methods that consume or return content only accept one format: JSON (cf. http://json.org ).

As a consequence, for those methods the use of HTTP headers Content-Type or Accept with value application/json is optional.

API-key authentication

Clients of the Live Objects Rest API are authenticated, based on an API key that must be provided with any request made to the API.

This API key must be added has a HTTP header named X-API-Key to the request.

Example (HTTP request to the API):

GET /api/v1/deviceMgt/devices HTTP/1.1
Host: <base URL>
X-API-Key: <API key>

If you don’t provide such an API key, or if you use an invalid API key, Live Objects responds with the standard HTTP Status code 403 Forbidden.

Paging

Some methods that return a list of entities allow paging: the method doesn’t return the full list of entities, but only a subset of the complete list matching your request.

Two standard query parameters are used in the list method (i.e. that must be added at the end of the URL, after a ?, separated by a &, and defined like this: <param>=<value>). These parameters depend on API version.

API v0

  • size: maximum number of items to return (i.e. number of items per page),

  • page: number of the page to display (starts at 0).

Those parameters are not mandatory: by default page will be set to 0 and size to 20.

Example:

  • If size=10 and page=0 then item number 0 to 9 (at most) will be returned.

  • If size=20 and page=1, then items number 20 to 39 (at most) will be returned.

Example (HTTP request to the API):

GET /api/v0/apiKeys?page=100&size=20 HTTP/1.1
Host: <base URL>
X-API-Key: <API key>

The responses of such methods are a “page” of items - a JSON object with the following attributes:

  • totalCount: total number of entities matching request in service (only part of them are returned),

  • size: the value for “size” taken into account (can be different of the one in request if the value was invalid),

  • page: the value for “page” taken into account (can be different of the one in request if the value was invalid),

  • data: list of returned entities.

API v1

  • limit: maximum number of items to return (i.e. number of items per page),

  • offset: number of items to skip (starts at 0).

Those parameters are not mandatory: by default offset will be set to 0 and limit to 20.

Example:

  • If limit=10 and offset=0 then item number 0 to 9 (at most) will be returned.

  • If limit=20 and offset=1, then items number 1 to 20 (at most) will be returned.

Example (HTTP request to the API):

GET /api/v1/deviceMgt/devices?limit=100&offset=20 HTTP/1.1
Host: <base URL>
X-API-Key: <API key>
X-Total-Count: <boolean>

The responses of such methods are a list of items. If request header X-Total-Count is true, the total count of items will be present in the HTTP response header.

Response HTTP headers:

  • X-Result-Count: number of items return in the response

  • X-Result-Limit: the value for “limit” taken into account

  • X-Total-Count: Optional. total number of entities matching request in service

HTTPS REST API documentation

All HTTPS REST methods (device management, data management and bus management, etc.) are described in the HTTPS REST API documentation available here : https://liveobjects.orange-business.com/swagger-ui/index.html.

"Application" mode

The "application" mode purpose is to retrieve messages available in your FIFOs.

Typically, use this mode when you want to consume flows of data collected by Live Objects.

The FIFO you connect to, must be declared using the FIFO APIs. To push data toward these FIFOs, you must use the Fifo publish action rules.

Application mode can also be used to publish a DataMessage in the specific case that it is not linked to any device.

Summary

In "application" mode, you can use these authorized topics:

Direction Topic Description

Subscribe

fifo/{fifoName}

Consume the messages of a fifo

Publish

application/v1/data

Store a DataMessage (specific use case where data is not linked to a device)

Connection

When initiating the MQTT connection, to select the "application" mode you must use the following credentials:

  • clientId : any string between 1 and 128 characters long, containing no spaces or special characters except :, - or _ . The MQTT protocol indicates it must be unique per connection, but Live Objects does not enforce it.

  • username : application (case sensitive)

  • password : a valid API Key with BUS_R role to subscribe to FIFO and/or DATA_W to publish DataMessage

To find more information regarding Live Objects MQTT endpoints, please refer to: MQTT endpoints

You must use a secured connection (MQTTS port 8883). The MQTT non-secured connection is not supported for "application" mode.

FIFO usage

An action policy with FIFO publish action pushes messages to a FIFO queue, allowing the "application" mode to consume them in a reliable way using MQTT subscription.

When creating an action policy with a FIFO publish action, the targeted FIFO is automatically created.

FIFO queues behaviour

Messages are persisted on disk in a FIFO queue until acknowledged or expired.

Each message is delivered to a single consumer; when multiple consumers are subscribed, messages are load-balanced among them. FIFO consumption requires acknowledgement to avoid message loss.

Examples:

  • If a message enters a FIFO with no consumer subscribed, it remains on disk until a consumer subscribes and acknowledges the reception of the message.

  • If a message enters a FIFO while a consumer is subscribed, it is delivered immediately and removed only after acknowledgement; if the consumer does not acknowledge the message, it is returned to the queue and will be delivered to the next available consumer.

There are two ways a message in a FIFO can expire:

  • Expiration delay: if a message is not consumed and acknowledged within the delay defined in your offer settings, it is automatically dropped from the FIFO.

  • noRetention = true: when the action policy sets noRetention to true, unconsumed messages are not kept — without an ongoing MQTT subscription, data messages are dropped immediately.

FIFO subscription

To subscribe to a FIFO queue, a MQTT client connected in "application" mode must subscribe to the following MQTT topic:

fifo/\{fifoName\}

where fifoName is the identifier of the targeted FIFO queue.

This works only if the used API key has no restriction or if the FIFO queue is specified in the API key’s restriction list.

If the subscription succeeds, Live Objects only returns a MQTT SUBACK packet once the subscription is active.

If the subscription fails (for ex. because the FIFO does not exist), a MQTT SUBACK packet is returned based on the MQTT protocol version used. In MQTT 3.1.1, the Failure return code 0x80 will be used. In MQTT 3.1, 0x01 will be returned.

You can refer to your Audit Logs where additional information regarding errors during MQTT connection will be displayed.

Data publication

The nominal way to publish DataMessage is to use MQTT External connector mode and publish a Data as a device.

In some specific use cases you may want to publish data without any device enrichment process, similar to the HTTP data store API.

To publish such DataMessage, a MQTT client connected in "application" mode must publish to the following MQTT topic:

application/v1/data

The payload of this publication should follow:

DataMessage publication
{
   "streamId":"urn:lo:nsid:detector_A8:12435355",
   "timestamp":"2019-05-20T16:01:47Z",
   "model":"data_v0",
   "value":{
      "temperature":14.6,
      "battery":53,
      "messageAlert":"low battery"
   },
   "location":{
      "lat":48.86667,
      "lon":2.33333,
      "alt":35.2,
      "accuracy":12.3,
      "provider":"GPS"
   },
   "tags":[
      "production",
      "london"
   ],
   "metadata":{
      "encoding":"base64",
      "source":"urn:lo:nsid:detector_A8:12435355"
   }
}
Field Description

streamId

(Mandatory). The streamId where the data will be stored in; and retrieved using the HTTP store API.

timestamp

(Optional). Should follow ISO-8601 format. If not set, current timestamp will be used.

model

(Optional). Can not contain ' ' (space) or '.' (dot) character. Model is needed to be able to use the search APIs on fields inside the value object.

value

(Optional). JSON compliant object. No inner field name should contain '.' (dot) character.

location

(Optional). If set, geo-query will be available through search APIs.

tags

(Optional) List of additional information used to tag the DataMessage

metadata.encoding

(Optional) In order for the data to be enriched by decoders and pipelines functionalities, 'metadata.encoding' field must be set.

metadata.source

(Optional) source of the data.

If the publication succeeds, Live Objects will acknowledge the message according to the QoS level.

If the publication fails (for ex. because the JSON is badly formatted), Live Objects will nevertheless acknowledge the message according to the QoS level, and an AuditLog message will be sent with anomaly details.

MCP Protocol (BETA)

Live Objects integrates MCP (Model Context Protocol), a protocol used by LLMs to interact with a platform.

It allows you to use your own LLM based tools to analyze your devices and data on Live Objects. It is very useful for debugging purposes, as it can easily fetch information through several domains (device inventory, data, trigger and action rules, audit logs, access logs…​) to detect anomalies and issues on your devices, and to understand the root cause of these issues. It can effectively perform aggregation queries on your data, check your rules configuration, test your decoders, investigate through your audit logs and access logs.

The results you will get is very dependent on the LLM you are using, and the way you ask your questions. So it can be very useful to experiment with different LLMs and different ways of asking your questions to find the best way to get the information you are looking for. Some LLMs are better at understanding complex questions and at using the right tools to fetch specific information.

How many devices do I have in each of my device types?
How many devices have sent data with value.battery.level < 20 in the last 7 days?
Why 'device001' has not sent any data since 2 days?
Who did update the rule 'temperature alert' last time, and what was the change?
What are the most common errors in my audit logs?

Endpoint

MCP is available at the following endpoint:

https://liveobjects.orange-business.com/api/mcp

The authentication is based on the HTTP header X-API-Key. A tool that supports the use of custom HTTP headers is required to use MCP on Live Objects.

You can create a new API Key in the 'Administration > API Keys' section of the Live Objects web portal. Be careful to set up the right permissions for this API key, depending on the information you want to fetch through MCP.

On top of these permissions, you also need to enable the 'MCP' permission on your account. Be careful with the Write permissions, as it allows you to execute actions on Live Objects through MCP, which can potentially be destructive.

Disclaimer

LLMs behaviour can be unpredictable, and can potentially generate destructive actions on the platform if you give them write access.

Be careful about the permissions granted to the API key you configure in your MCP agent, and define only the minimum permissions required for your use case.

Even with read only access, be careful about the information that you allow the LLM to fetch from Live Objects, as it can potentially contain sensitive information about your devices and data. And based on your LLM provider and MCP client, the information fetched from Live Objects can potentially be used by the LLM provider to further train their models, and can be exposed to third parties.

If you use an API Key with write permissions, but have the read only MCP access in your account subscriptions, then the API Key will be restricted to its 'read' permissions. Using an API Key with only 'read' permissions will ensure that the LLM will not be able to perform any destructive action on the platform, even if your account has activated the read/write MCP option.

Enabling MCP on your account

MCP is currently in BETA, and is not enabled by default on all accounts.

If you want to use MCP, please ask for a MCP access through the support page.

There are 2 types of MCP access : read only and read/write.

The read only access allows you to fetch information from Live Objects, but not to perform any action on the platform.

The read/write access allows you to perform actions on the platform (e.g. create or update a device, create a new rule…​).

Please ask for the right type of access depending on your needs. But you need to be careful when asking for a read/write access, as it can potentially allow you to perform destructive actions on the platform (e.g. bulk delete devices, delete a rule…​). So please make sure to ask for the right type of access depending on your needs.

Configuring your MCP agent

To connect an MCP client (VS Code, Cline, etc.) to Live Objects, you only need to configure:

For security reasons, do not hard-code your API Key in a file committed to git. Prefer storing it in an environment variable (or your client secret store) and referencing it from your MCP client configuration.

VS Code and GitHub Copilot

If you are using VS Code with GitHub Copilot, you can configure a remote MCP server in your workspace configuration (for example in a {workspace}/.vscode/mcp.json file).

{
  "servers": {
    "liveobjects": {
    "type": "http",
    "url": "https://liveobjects.orange-business.com/api/mcp",
      "headers": {
        "X-API-Key": "${env:LIVEOBJECTS_MCP_API_KEY}"
      }
    }
  }
}

Cline

In Cline, add a new MCP server that points to the Live Objects endpoint and sends the X-API-Key header. Depending on your Cline version, this can be done from the UI settings or by editing its MCP servers configuration file.

{
  "mcpServers": {
    "liveobjects": {
      "type": "streamableHttp",
      "url": "https://liveobjects.orange-business.com/api/mcp",
      "headers": {
        "X-API-Key": "${env:LIVEOBJECTS_MCP_API_KEY}"
      }
    }
  }
}

Once configured, you can validate your setup by asking your agent a simple question such as: "How many devices do I have?". The agent should then be able to query the device inventory through MCP.

Version 2026.7.0 • Updated date 2026-08-11 12:37:29 UTC