API Documentation

OpenAPI Document

The App Manager API is documented in a JSON file conforming to the OpenAPI 3.0 specification.

Swagger

The best way to visualize and interact with the API is through Swagger.

Using Swagger Editor on the web

With Swagger Editor, you can view and edit the OpenAPI document inside your browser, while previewing the documentation in real time.

Visit https://editor-next.swagger.io/ and select File → Import file, or drag-and-drop the openapi.json file into the browser window.

You can then view and make edits to the OpenAPI document in the left panel (in YAML format) and visualize the UI in the right panel, or simply drag the divider all the way to the left if you are only interested in the UI.

Note: This method will allow you to view the documentation in Swagger UI, but you will only be able to interact with the API if it can be accessed from a public URL/IP address. In that case, replace http://localhost:5000/ in the url field with the correct address. Otherwise, you will need to install locally (see below) on the system that is running the Django backend in order to issue API calls through Swagger UI.

Installing Swagger Editor locally

Swagger Editor can also be installed locally with https://github.com/swagger-api/swagger-editor, or by cloning the repository.

git clone https://github.com/swagger-api/swagger-editor.git

Then open index.html and import openapi.json or drag-and-drop into the browser window.

Using Swagger UI standalone

If you do not need to view or edit the OpenAPI document, you can also use a standalone version of Swagger UI.

The tool https://github.com/vajahath/open-swagger-ui will allow you to open a local openapi.json file in the Swagger UI.

It requires Node.js >=10 and can be installed via npm:

npm i -g open-swagger-ui

Then, make sure you are in the directory containing openapi.json (or point the command to where it is located) and run:

open-swagger-ui .\openapi.json --open

Authentication

In order to use the API, you will need to provide an authorization token.

You can generate an authentication token from your username and password with a POST /accounts/api-token-auth/ call, with the following request body:

{
  "username": "user123",
  "password": "pw123"
}

If you fail to authenticate, any API calls (except for /accounts/api-token-auth/) will return an error code 401.

When making an API call, use -H 'Authorization: Token 123abc', replacing 123abc with your token.

If you are using Swagger UI, click on the ‘Authorize’ button and use value Token 123abc, replacing 123abc with your token.

If you are using something like Postman, click on Headers and add these, replacing 123abc with your token.

Error Codes

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

200 - Successful operation

401 - Unauthorized (see Authentication)

4xx/5xx - Request failed for some other reason

Response

All API calls will generate a response in the format below:

{
  "requestId": null,
  "result": "",
  "error": null
}

requestId contains a unique identifier for each request.
- You can view the contents of a specific request with GET /api/request/{requestId}/ .
result contains the result of the request.
error contains an error code and description if the request failed on the backend.
- Note: The API call, itself, will still be successful and return code 200.

Endpoints

All API endpoints are listed below, along with a brief description for each. More detail on usage and expected results can be found in the OpenAPI document or viewed through the Swagger UI.

Account management (accounts)

POST /accounts/api-token-auth/ Generate API token to authorize session
POST /accounts/changePassword/ Change the password of the specified user

General high-level API calls (api)

GET /api/folder/{folderId}/tree/ Return a tree containing all children of the specified folder
GET /api/request/{requestId}/ Return the contents of the specified request
GET /api/status/ Report the status of the API backend, including mode
GET /api/tree/ Return the highest level tree for this install
GET /api/{entity}/allconfig/ Return a full listing of an entity type (nodes, apps, objects)
GET /api/{entity}/allconfigfromtypes/ Return a full listing of an entity type (nodes, apps, objects)
GET /api/{schemaId}/schema/ Return the schema file for the specified schema ID
GET /api/itemTypes Return list of schema item types
GET /api/schema/ Return the schema files for the specified schema IDs
POST /api/{category}/{itemId}/move/ Move node or folder to new location
POST /api/folder/add/ Add new folder
GET /api/folder/{folderId}/view/ Get folder properties
POST /api/folder/{folderId}/delete/Delete folder
GET /api/folder/{folderId}/config/ Get folder configurations
POST /api/folder/{folderId}/config/Adjust the settings of the specified node

Operations on a specified node (api_node)

GET /api/{nodeId}/apps/ Return a list of all apps under the specified node
POST /api/{nodeId}/command/ Send a command to the specified node
GET /api/{nodeId}/config/ Return the settings for the specified node
POST /api/{nodeId}/config/ Adjust the settings for the specified node
POST /api/{nodeId}/delete/ Delete the specified node from the remote manager database
GET /api/{nodeId}/export/ Full recursive export for the specified node
POST /api/{nodeId}/import/ Full recursive import for the specified node
POST /api/{nodeId}/sync/ Sync the specified node to the remote manager
GET /api/{nodeId}/tree/ Return the highest level tree for the specified node
GET /api/{nodeId}/view/ Return the schema and settings for the specified node
GET /api/{nodeId}/defaults/ Return node defaults configurations

Operations on a specified app (api_app)

POST /api/{nodeId}/{appId}/command/ Send a command to the specified app
GET /api/{nodeId}/{appId}/config/ Return the settings for the specified app
POST /api/{nodeId}/{appId}/config/ Adjust the settings for the specified app
GET /api/{nodeId}/{appId}/export/ Full recursive export for the specified app
POST /api/{nodeId}/{appId}/import/ Full recursive import for the specified app
POST /api/{nodeId}/{appId}/license/ Set the license for the specified app
POST /api/{nodeId}/{appId}/licenserequest/ Request a license for the specified app
GET /api/{nodeId}/{appId}/models/ List all models that can be added in the specified app
GET /api/{nodeId}/{appId}/tree/ Return the highest level tree for the specified app
GET /api/{nodeId}/{appId}/view/ Return the schema and settings for the specified app
GET /api/{appId}/{schemaId}/get_metadata/ Return metadata properties associated with the schema for the specified app
GET /api/{appId}/{schemaId}/metadata_schema/ Return schema injected with the properties for the specified app

Operations on a specified object (api_object)

GET /api/{nodeId}/{appId}/{objectId}/children/ List the direct children of the specified object
POST /api/{nodeId}/{appId}/{objectId}/command/ Send a command to the specified object
GET /api/{nodeId}/{appId}/{objectId}/config/ Return the settings for the specified object
POST /api/{nodeId}/{appId}/{objectId}/config/ Adjust the settings for the specified object
POST /api/{nodeId}/{appId}/{objectId}/copy/ Create a recursive copy of the specified object
POST /api/{nodeId}/{appId}/{objectId}/delete/ Delete the specified object
GET /api/{nodeId}/{appId}/{objectId}/export/ Full recursive export for the specified object
POST /api/{nodeId}/{appId}/{objectId}/import/ Full recursive import for the specified object
GET /api/{nodeId}/{appId}/{objectId}/tree/ Return the highest level tree for the specified object
GET /api/{nodeId}/{appId}/{objectId}/view/ Return the schema and settings for the specified object
GET /api/{nodeId}/{appId}/{objectId}/{objectType}/children/ List all children of the specified object that are of the specified type

Operations involving a specified object type within a specified app (api_objectType)

GET /api/{nodeId}/{appId}/{objectType}/add/ Return the default schema for the specified object type
POST /api/{nodeId}/{appId}/{objectType}/add/ Create a new instance of the specified object type under the specified app
GET /api/{nodeId}/{appId}/{objectType}/allconfig/ List all objects of the specified type under the specified app, along with their settings
GET /api/{nodeId}/{appId}/{objectType}/listing/ List all instances of the specified object type under the specified app
GET /api/{nodeId}/{appId}/{objectType}/newview/ Return a schema file filled with default values in order to display new items in UI

Log file handling (log)

POST /log/delete/{applabel}/ Delete all logs under the specified app label
POST /log/delete/{applabel}/{filename}/ Delete the specified log file
GET /log/download/{applabel}/{filename}/ Return the contents of the specified log file
GET /log/getlogs/ List all available logs
GET /log/zip/ Create a zip file containing all logs
GET /log/gettextlogs/Get list of all logs
GET /log/query/{applabel}/{filename}/{count}/ Return the contents of the specified log file

General system information (system)

GET /system/systemDateTime/ Return the current date and time for the system (in Unix Epoch time)
GET /system/systemInfo/ Return information about the system

Operations involving package management (packagemanager)

GET /packagemanager/info/{installId}/ Return installed package details
GET /packagemanager/tree/ Return list of installed packages
GET /packagemanager/available/ Return list of packages that can be installed
GET /packagemanager/history/Return list of packages that were installed
POST /packagemanager/uploadModule/ Upload package for installation
POST /packagemanager/{nodeId}/delete/{packageId}/ Delete imported package
POST /packagemanager/{nodeId}/install/ Install package
POST /packagemanager/{nodeId}/uninstall/Uninstall package
POST /packagemanager/{nodeId}/remoteUpload/Remote upload packages

Dashboard operations (dashboard)

GET /dashboard/ Return list of nodes

Operations involving mqtt (mqtt)

GET /mqtt/{nodeId}/{action}/ Get node information
POST /mqtt/{nodeId}/{action}/ Perform action on node