Engine API

v1.1.0-build.67-channel.stable (stable · latest)v1.1.0-build.73-channel.insider (insider)v1.1.0-build.68-channel.insider (insider)v1.1.0-build.63-channel.insider (insider)v1.1.0-build.62-channel.insider (insider)

insider 2026-08-17 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://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
POST	/api/v1/admin/apps/{id}/drop-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
GET	/api/v1/admin/apps/{id}/versions/{version}/download/app	Download an application package
GET	/api/v1/admin/apps/{id}/versions/{version}/download/sym	Download an application Symbol file
DELETE	/api/v1/admin/apps/{id}/{version}	Delete an application version
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

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

POST /api/v1/admin/apps/{id}/drop-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

GET /api/v1/admin/apps/{id}/versions/{version}/download/app

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/apps/{id}/versions/{version}/download/sym

Download an application Symbol file

Downloads the symbols (.niksym) 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 Symbole file	file
404	Not Found	ErrorResponse
500	Internal Server Error	ErrorResponse

DELETE /api/v1/admin/apps/{id}/{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/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

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

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