---
title: "Designer API"
description: "REST API for controlling Disguise Designer, including Service and Session endpoints"
url: https://developer.disguise.one/api/introduction/
---

# Designer API

Welcome to the documentation for the Designer APIs! These APIs provide programmatic access to the functionality of the Disguise platform, allowing you to build integrations and applications that can control and interact with Disguise.

## Software Version

This documentation relates to the suite of APIs released in version r23.2. Current and previous versions of Designer can be found in the [Disguise User Guide](https://help.disguise.one/designer/release-notes/release-notes) or downloaded from your [Cloud account](https://disguise.cloud).

## Service and Session

The Service APIs relate to functionality provided by the d3service runtime and are available whenever Disguise is installed on a machine. The Session APIs relate to the currently running session and as such are only available when Designer is running.

## Ports

The Service and Session APIs are accessed by HTTP over a single port, `80`. In most cases, such as making an HTTP request or accessing with a web browser, only the IP address or hostname needs to be specified.

If a conflict exists, this port can be changed using d3Manager under Machine Settings > Advanced Network Configuration.

## Discovery

From r30.4, the Designer APIs can be discovered using DNS-SD. This is useful for finding the hostname and port of a Designer instance without prior knowledge. See the [Discovery](/api/discovery) page for more information.

## SMC API

As well as the main Session & Service Disguise APIs, the server can also forward requests to the [SMC API](/smc/introduction) hosted on the Remora System Management Controller.

Requests intended for the SMC API should sent to the server using the `api/smc` route which will forward them to the SMC API server on the `api` route - for example, to query the LED strip status (`api/ledstrip` if querying the SMC API directly) you should query `api/smc/ledstrip`.

## Getting Started

To get started with these APIs, you will need to make HTTP requests to the appropriate API endpoint. Here is a simple example using the JavaScript [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) to make a `GET` request to the `/api/service/system/detectsystems` endpoint to retrieve the list of machines found on the local network:

```js
// Make a HTTP API request using javascript

fetch('http://127.0.0.1/api/service/system/detectsystems')
  .then(response => response.json())
  .then(data => console.log(data.result));
```

This code uses the `fetch` function to send a `GET` request to the `/api/service/system/detectsystems` endpoint, it logs the systems found to the console.

For more information about the Service and Session APIs, including a list of all available endpoints and the parameters and responses for each endpoint, please see the detailed documentation using the links in the sidebar.

## Recommended: Use Live Update Instead of Polling REST APIs

While the REST APIs are useful for one-off requests and retrieving state snapshots, using them for continuous polling is not recommended. Polling REST endpoints at regular intervals can lead to unnecessary load, reduced performance, and less predictable behaviour in your integration.

For ongoing or high-frequency state monitoring, we strongly encourage using the [Live Update API](session/liveupdate) instead.

### Why we recommend Live Update

The Live Update API is designed specifically for real-time monitoring and change tracking. It provides several advantages over REST polling:

-   **Subscription-based updates**: Instead of repeatedly requesting data, you subscribe to exactly the updates you need.
-   **Configurable update rates**: You can set the frequency and conditions under which updates are delivered.
-   **Lower performance impact**: Because changes are pushed to your client only when needed, both Designer and your integration run more efficiently.
-   **Cleaner integration patterns**: Live Update avoids common issues seen with polling loops, such as unnecessary network traffic, thread blocking, and shutdown complications.

### When REST is still appropriate

A common pattern is to use REST once at startup to gather baseline information, then switch to Live Update subscriptions for all ongoing state tracking.

REST calls remain ideal for:

-   Initial state retrieval
-   Occasional, explicit operations (such as POST requests used to set or update values)
-   Low-frequency, single-purpose requests

REST is suitable for state-changing operations. Actions performed via POST, PUT, or PATCH, such as updating configuration or triggering commands, align well with REST’s synchronous request/response model.

After retrieving initial data, we recommend transitioning to [Live Update](session/liveupdate) subscriptions for any continuous or event-driven workflows.