Integration APIs¶

This article is about the APIs in IWS that developers can use to integrate Indigo with external services:

New in 2026.1 WebSockets API v3 – one connection carrying every object type you subscribe to, plus folders and the tag library. This is what new clients should use, and it's what Indigo Touch for Web uses.
WebSockets API v2 – the seven typed feeds, one connection per object type. Unchanged and fully supported for existing integrations.
HTTP API – shares as much of the messaging construction with the WebSocket interface as is practical.
New in 2026.1 MCP API – the Model Context Protocol server, which lets an AI chat client or coding agent control Indigo. Deliberately control-only: it cannot change your configuration.

These APIs are authenticated with HTTP Digest, API Keys, and local secrets (either as a query string or preferably an Authorization header) depending on how the user configures it in the Start Local Server dialog. The MCP API is the exception: it takes an API key or local secret as a bearer token only.

Warning

HTTP Basic authentication has been deprecated due to its insecure nature.
The old REST API has been deprecated in favor of the HTTP API.

Versioning¶

A quick note on versioning: all APIs are versioned in the URL path — /v2/, /v3/ — and that top level number changes as necessary. The two are not in lockstep across APIs: as of Indigo 2026.1 the HTTP API is at v2, the WebSocket API offers both v2 and v3, and MCP is at v3.

Asking the server what it speaks¶

New in 2026.1 API v3.9 GET /api/capabilities reports which versions of each API this server serves, and where each one lives. It's unauthenticated and takes no body:

{
  "server": {"version": "2026.1.0", "apiVersion": "3.9"},
  "apis": {
    "http":      {"versions": [2],    "paths": {"2": "/v2/api"}},
    "websocket": {"versions": [2, 3], "paths": {"2": "/v2/api/ws/<type>-feed",
                                                "3": "/v3/api/ws/full-feed"}},
    "mcp":       {"versions": [3],    "paths": {"3": "/v3/api/mcp"}}
  }
}

Fetch it and pick the highest version of an API that you and the server have in common. A 404 means the server predates 2026.1, since the endpoint is new in that release, so its absence is itself an answer. This lets a client tell which server it's talking to before it commits to a connection, rather than having to interpret a failed upgrade.

The v3 WebSocket feed additionally sends a hello frame first on every connection, carrying the protocol number and a feature list, so additions made within v3 are discoverable in-band without a version bump.

Python vs JavaScript¶

In these APIs, we’re using JSON (JavaScript Object Notation) as the message format for communicating between the WebSocket and HTTP APIs and IWS. In JavaScript, an “object” definition looks (almost) exactly like a Python dictionary (and vice versa). So we may refer to an object or dictionary (dict): for the purposes of this document, they refer to the same JSON construct. For example, we may call this an object or a dict:

{
  "key1": "value 1",
  "key2": 2
}

We expect there will be both Python and JavaScript users integrating our APIs, so we wanted to explicitly call this out. As a primarily Python organization, you may notice a bias towards “dict”.

Python developers will notice the use of null in the message descriptions. This corresponds to the Python None object. Also of note are the booleans true and false, which are capitalized in Python but not in JSON. Here’s a handy cheat sheet:

Python	JSON Equivalent
True	true
False	false
float	Number
int	Number
None	null
dict	Object
list	Array
tuple	Array
str	String

If you are new to JSON, you may want to use the JSON Validator website to validate that the JSON message you are sending is valid JSON.