Engine API

insider 2026-08-26 JSON ↗

Management API for Niksphere applications and core data.

Server & Base URL

All REST API endpoints documented below are relative to the Engine base URL:

http

http://localhost:3000/api/v1

NOTE

For custom host/port setups or production deployments, configure NIKSPHERE_ENGINE_HTTP_BASE_URL (or http_base_url in config.yaml). See the Engine Configuration Reference for all options.

Endpoints Overview

Method	Endpoint	Summary
`GET`	`/api/v1/admin/apps`	List all applications
`POST`	`/api/v1/admin/apps/publish`	Publish an application package
`POST`	`/api/v1/admin/apps/upload`	Upload an application package
`DELETE`	`/api/v1/admin/apps/{id}/data`	Drop application database tables
`POST`	`/api/v1/admin/apps/{id}/install/{version}`	Install an application version
`POST`	`/api/v1/admin/apps/{id}/uninstall`	Uninstall an application
`DELETE`	`/api/v1/admin/apps/{id}/versions/{version}`	Delete an application version
`GET`	`/api/v1/admin/apps/{id}/versions/{version}/package`	Download an application package
`GET`	`/api/v1/admin/identities`	List all users
`POST`	`/api/v1/admin/identities`	Create a new user
`PUT`	`/api/v1/admin/identities/{username}`	Edit a user (Change Password)
`DELETE`	`/api/v1/admin/identities/{username}`	Delete a user
`GET`	`/api/v1/admin/idps/external`	List all external IdPs
`POST`	`/api/v1/admin/idps/external`	Create a new external IdP
`PUT`	`/api/v1/admin/idps/external/{id}`	Edit an external IdP
`DELETE`	`/api/v1/admin/idps/external/{id}`	Delete an external IdP
`GET`	`/api/v1/admin/monitor`	Live log and telemetry streaming
`GET`	`/api/v1/client`	Client runtime WebSocket connection
`GET`	`/api/v1/health`	Service health check
`GET`	`/api/v1/openapi.json`	OpenAPI specification

Admin

`GET` /api/v1/admin/apps

List all applications

Retrieves a detailed list of all applications and their available versions

Responses:

Status Code	Description	Schema / Content
`200`	OK	`AppListWrapper`
`500`	Internal Server Error	`ErrorResponse`

`POST` /api/v1/admin/apps/publish

Publish an application package

Uploads and automatically installs/activates a Niksphere App package (.nikapp) on the server in a single request

Parameters:

Name	Located in	Type	Required	Description
`file`	`formData`	`file`	`yes`	Niksphere App Package
`allow_drops`	`query`	`boolean`	`no`	Allow drops

Responses:

Status Code	Description	Schema / Content
`200`	OK	`SuccessResponse`
`400`	Bad Request	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`POST` /api/v1/admin/apps/upload

Upload an application package

Uploads a new Niksphere App package (.nikapp) to the server

Parameters:

Name	Located in	Type	Required	Description
`file`	`formData`	`file`	`yes`	Niksphere App Package

Responses:

Status Code	Description	Schema / Content
`200`	OK	`SuccessResponse`
`400`	Bad Request	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`DELETE` /api/v1/admin/apps/{id}/data

Drop application database tables

Drops all physical database tables and associated data for an uninstalled application

Parameters:

Name	Located in	Type	Required	Description
`id`	`path`	`string`	`yes`	Application ID

Responses:

Status Code	Description	Schema / Content
`200`	OK	`SuccessResponse`
`400`	Bad Request	`ErrorResponse`
`404`	Not Found	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`POST` /api/v1/admin/apps/{id}/install/{version}

Install an application version

Installs and activates a specific version of an application

Parameters:

Name	Located in	Type	Required	Description
`id`	`path`	`string`	`yes`	Application ID
`version`	`path`	`string`	`yes`	Version string
`allow_drops`	`query`	`boolean`	`no`	Allow drops

Responses:

Status Code	Description	Schema / Content
`200`	OK	`SuccessResponse`
`400`	Bad Request	`ErrorResponse`
`404`	Not Found	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`POST` /api/v1/admin/apps/{id}/uninstall

Uninstall an application

Deactivates the currently installed version of an app

Parameters:

Name	Located in	Type	Required	Description
`id`	`path`	`string`	`yes`	Application ID

Responses:

Status Code	Description	Schema / Content
`200`	OK	`SuccessResponse`
`400`	Bad Request	`ErrorResponse`
`404`	Not Found	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`DELETE` /api/v1/admin/apps/{id}/versions/{version}

Delete an application version

Permanently removes a specific version of an app from the system

Parameters:

Name	Located in	Type	Required	Description
`id`	`path`	`string`	`yes`	Application ID
`version`	`path`	`string`	`yes`	Version string

Responses:

Status Code	Description	Schema / Content
`200`	OK	`SuccessResponse`
`400`	Bad Request	`ErrorResponse`
`404`	Not Found	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`GET` /api/v1/admin/apps/{id}/versions/{version}/package

Download an application package

Downloads the compiled Niksphere App package (.nikapp) for a specific version

Parameters:

Name	Located in	Type	Required	Description
`id`	`path`	`string`	`yes`	Application ID
`version`	`path`	`string`	`yes`	Version string

Responses:

Status Code	Description	Schema / Content
`200`	The Niksphere App Package	`file`
`404`	Not Found	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`GET` /api/v1/admin/identities

List all users

Retrieves a list of all registered system users (embedded credentials)

Responses:

Status Code	Description	Schema / Content
`200`	OK	`IdentityListWrapper`

`POST` /api/v1/admin/identities

Create a new user

Creates a new user and safely hashes their password

Parameters:

Name	Located in	Type	Required	Description
`request`	`body`	`IdentityAddRequest`	`yes`	User creation data

Responses:

Status Code	Description	Schema / Content
`200`	OK	`IdentityResponse`
`400`	Bad Request	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`PUT` /api/v1/admin/identities/{username}

Edit a user (Change Password)

Changes the password for a given username

Parameters:

Name	Located in	Type	Required	Description
`username`	`path`	`string`	`yes`	Username to edit
`request`	`body`	`IdentityEditRequest`	`yes`	New password

Responses:

Status Code	Description	Schema / Content
`200`	OK	`SuccessResponse`
`400`	Bad Request	`ErrorResponse`
`404`	Not Found	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`DELETE` /api/v1/admin/identities/{username}

Delete a user

Removes a user from the system. Cannot delete the base admin user.

Parameters:

Name	Located in	Type	Required	Description
`username`	`path`	`string`	`yes`	Username to delete

Responses:

Status Code	Description	Schema / Content
`200`	OK	`SuccessResponse`
`400`	Bad Request	`ErrorResponse`
`404`	Not Found	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`GET` /api/v1/admin/idps/external

List all external IdPs

Retrieves a list of all configured external identity providers

Responses:

Status Code	Description	Schema / Content
`200`	OK	`ExternalIdpListWrapper`

`POST` /api/v1/admin/idps/external

Create a new external IdP

Creates a new external identity provider configuration

Parameters:

Name	Located in	Type	Required	Description
`request`	`body`	`ExternalIdpAddRequest`	`yes`	IdP creation data

Responses:

Status Code	Description	Schema / Content
`200`	OK	`ExternalIdpResponse`
`400`	Bad Request	`ErrorResponse`

`PUT` /api/v1/admin/idps/external/{id}

Edit an external IdP

Modifies an existing external IdP

Parameters:

Name	Located in	Type	Required	Description
`id`	`path`	`string`	`yes`	IdP ID to edit
`request`	`body`	`ExternalIdpEditRequest`	`yes`	Updated fields

Responses:

Status Code	Description	Schema / Content
`200`	OK	`SuccessResponse`
`400`	Bad Request	`ErrorResponse`
`404`	Not Found	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`DELETE` /api/v1/admin/idps/external/{id}

Delete an external IdP

Removes an external IdP from the system

Parameters:

Name	Located in	Type	Required	Description
`id`	`path`	`string`	`yes`	IdP ID to delete

Responses:

Status Code	Description	Schema / Content
`200`	OK	`SuccessResponse`
`400`	Bad Request	`ErrorResponse`
`404`	Not Found	`ErrorResponse`
`500`	Internal Server Error	`ErrorResponse`

`GET` /api/v1/admin/monitor

Live log and telemetry streaming

Establishes a WebSocket connection for real-time engine logs and system metrics

Parameters:

Name	Located in	Type	Required	Description
`ticket`	`query`	`string`	`yes`	Single-use WebSocket Ticket

Responses:

Status Code	Description	Schema / Content
`101`	Switching Protocols to WebSocket	`string`
`401`	Unauthorized	`ErrorResponse`

Client

`GET` /api/v1/client

Client runtime WebSocket connection

Establishes a bidirectional WebSocket connection for interactive UI state synchronization and push events

Parameters:

Name	Located in	Type	Required	Description
`ticket`	`query`	`string`	`yes`	Single-use WebSocket Ticket

Responses:

Status Code	Description	Schema / Content
`101`	Switching Protocols to WebSocket	`string`
`401`	Unauthorized	`ErrorResponse`

System

`GET` /api/v1/health

Service health check

Inspects the running service status and database connectivity

Responses:

Status Code	Description	Schema / Content
`200`	OK	`HealthResponse`
`503`	Service Unavailable	`HealthResponse`

`GET` /api/v1/openapi.json

OpenAPI specification

Retrieves the complete OpenAPI JSON specification for the Niksphere Engine API

Responses:

Status Code	Description	Schema / Content
`200`	OK	`object`
`401`	Unauthorized	`ErrorResponse`
`404`	Not Found	`ErrorResponse`

Data Models & Schemas

`AppListResponse`

Property	Type	Description
`author`	`string`
`availableVersions`	`string`
`id`	`string`
`installed`	`boolean`
`name`	`string`
`persisted`	`boolean`
`version`	`string`

`AppListWrapper`

Property	Type	Description
`data`	`Array<AppListResponse>`

`ErrorResponse`

Property	Type	Description
`error`	`string`

`ExternalIdpAddRequest`

Property	Type	Description
`auto_provision`	`boolean`
`client_id`	`string`
`client_secret`	`string`
`is_active`	`boolean`
`issuer_url`	`string`
`name`	`string`
`scopes`	`string`

`ExternalIdpEditRequest`

Property	Type	Description
`auto_provision`	`boolean`
`client_id`	`string`
`client_secret`	`string`
`is_active`	`boolean`
`issuer_url`	`string`
`name`	`string`
`scopes`	`string`

`ExternalIdpListWrapper`

Property	Type	Description
`data`	`Array<ExternalIdpResponse>`

`ExternalIdpResponse`

Property	Type	Description
`auto_provision`	`boolean`
`client_id`	`string`
`created_at`	`string`
`id`	`string`
`is_active`	`boolean`
`issuer_url`	`string`
`name`	`string`
`scopes`	`string`

`HealthResponse`

Property	Type	Description
`database`	`string`
`service`	`string`
`status`	`string`
`timestamp`	`string`

`IdentityAddRequest`

Property	Type	Description
`password`	`string`
`username`	`string`

`IdentityEditRequest`

Property	Type	Description
`password`	`string`

`IdentityListWrapper`

Property	Type	Description
`data`	`Array<IdentityResponse>`

`IdentityResponse`

Property	Type	Description
`created_at`	`string`
`id`	`string`
`username`	`string`

`SuccessResponse`

Property	Type	Description
`message`	`string`
`success`	`boolean`

Engine API ​

Server & Base URL ​

Endpoints Overview ​

Admin ​

GET /api/v1/admin/apps ​

POST /api/v1/admin/apps/publish ​

POST /api/v1/admin/apps/upload ​

DELETE /api/v1/admin/apps/{id}/data ​

POST /api/v1/admin/apps/{id}/install/{version} ​

POST /api/v1/admin/apps/{id}/uninstall ​

DELETE /api/v1/admin/apps/{id}/versions/{version} ​

GET /api/v1/admin/apps/{id}/versions/{version}/package ​

GET /api/v1/admin/identities ​

POST /api/v1/admin/identities ​

PUT /api/v1/admin/identities/{username} ​

DELETE /api/v1/admin/identities/{username} ​

GET /api/v1/admin/idps/external ​

POST /api/v1/admin/idps/external ​

PUT /api/v1/admin/idps/external/{id} ​

DELETE /api/v1/admin/idps/external/{id} ​

GET /api/v1/admin/monitor ​

Client ​

GET /api/v1/client ​

System ​

GET /api/v1/health ​

GET /api/v1/openapi.json ​

Data Models & Schemas ​

AppListResponse ​

AppListWrapper ​

ErrorResponse ​

ExternalIdpAddRequest ​

ExternalIdpEditRequest ​

ExternalIdpListWrapper ​

ExternalIdpResponse ​

HealthResponse ​

IdentityAddRequest ​

IdentityEditRequest ​

IdentityListWrapper ​

IdentityResponse ​

SuccessResponse ​

Engine API

Server & Base URL

Endpoints Overview

Admin

`GET` /api/v1/admin/apps

`POST` /api/v1/admin/apps/publish

`POST` /api/v1/admin/apps/upload

`DELETE` /api/v1/admin/apps/{id}/data

`POST` /api/v1/admin/apps/{id}/install/{version}

`POST` /api/v1/admin/apps/{id}/uninstall

`DELETE` /api/v1/admin/apps/{id}/versions/{version}

`GET` /api/v1/admin/apps/{id}/versions/{version}/package

`GET` /api/v1/admin/identities

`POST` /api/v1/admin/identities

`PUT` /api/v1/admin/identities/{username}

`DELETE` /api/v1/admin/identities/{username}

`GET` /api/v1/admin/idps/external

`POST` /api/v1/admin/idps/external

`PUT` /api/v1/admin/idps/external/{id}

`DELETE` /api/v1/admin/idps/external/{id}

`GET` /api/v1/admin/monitor

Client

`GET` /api/v1/client

System

`GET` /api/v1/health

`GET` /api/v1/openapi.json

Data Models & Schemas

`AppListResponse`

`AppListWrapper`

`ErrorResponse`

`ExternalIdpAddRequest`

`ExternalIdpEditRequest`

`ExternalIdpListWrapper`

`ExternalIdpResponse`

`HealthResponse`

`IdentityAddRequest`

`IdentityEditRequest`

`IdentityListWrapper`

`IdentityResponse`

`SuccessResponse`