Engine API
insider 2026-10-02 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/v1NOTE
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/actors | List all actors |
POST | /api/v1/admin/actors | Create a new actor |
GET | /api/v1/admin/actors/{id} | Get actor details |
PUT | /api/v1/admin/actors/{id} | Update an actor |
DELETE | /api/v1/admin/actors/{id} | Delete an actor |
GET | /api/v1/admin/actors/{id}/identities | List actor identities |
DELETE | /api/v1/admin/actors/{id}/identities/external/{ext_id} | Delete an external SSO identity link |
POST | /api/v1/admin/actors/{id}/identities/password | Set or update actor password |
POST | /api/v1/admin/actors/{id}/identities/pat | Create a Personal Access Token |
DELETE | /api/v1/admin/actors/{id}/identities/pat/{pat_id} | Delete a Personal Access Token |
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/clients | List all clients |
POST | /api/v1/admin/clients | Register a new client |
GET | /api/v1/admin/clients/{id} | Get client details |
PUT | /api/v1/admin/clients/{id} | Update client details |
DELETE | /api/v1/admin/clients/{id} | Delete a client |
PUT | /api/v1/admin/clients/{id}/toggle | Enable or disable client |
GET | /api/v1/admin/dap | DAP debug control connection |
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/admin/sessions | List active client runtime sessions |
DELETE | /api/v1/admin/sessions/{id} | Terminate an active client runtime session |
GET | /api/v1/admin/tasks | List background tasks |
GET | /api/v1/admin/tasks/{id} | Get task status |
DELETE | /api/v1/admin/tasks/{id} | Cancel a task |
GET | /api/v1/admin/tasks/{id}/stream | Stream task events |
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/actors
List all actors
Retrieves a list of all registered actors
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
500 | Internal Server Error | response.Response |
POST /api/v1/admin/actors
Create a new actor
Registers a new user, system, or service actor
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
request | body | ActorAddRequest | yes | Actor creation payload |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
500 | Internal Server Error | response.Response |
GET /api/v1/admin/actors/{id}
Get actor details
Retrieves details of a specific actor by ID
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Actor ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
PUT /api/v1/admin/actors/{id}
Update an actor
Updates an actor's display name or status
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Actor ID |
request | body | ActorEditRequest | yes | Actor edit payload |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
DELETE /api/v1/admin/actors/{id}
Delete an actor
Removes an actor from the system
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Actor ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
GET /api/v1/admin/actors/{id}/identities
List actor identities
Retrieves all linked credentials (password, PATs, external SSO links) for an actor
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Actor ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
DELETE /api/v1/admin/actors/{id}/identities/external/{ext_id}
Delete an external SSO identity link
Unlinks and deletes an external SSO identity provider link from an actor
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Actor ID |
ext_id | path | string | yes | External Identity ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
POST /api/v1/admin/actors/{id}/identities/password
Set or update actor password
Sets or resets the embedded password credentials for an actor
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Actor ID |
request | body | SetPasswordRequest | yes | Password payload |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
POST /api/v1/admin/actors/{id}/identities/pat
Create a Personal Access Token
Generates a new Personal Access Token (PAT) for an actor
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Actor ID |
request | body | CreatePATRequest | yes | PAT creation payload |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
DELETE /api/v1/admin/actors/{id}/identities/pat/{pat_id}
Delete a Personal Access Token
Revokes and deletes a specific Personal Access Token belonging to an actor
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Actor ID |
pat_id | path | string | yes | Personal Access Token ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
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 | response.Response |
401 | Unauthorized | response.Response |
500 | Internal Server Error | response.Response |
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 |
|---|---|---|
202 | Accepted | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
409 | Conflict | response.Response |
500 | Internal Server Error | response.Response |
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 | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
500 | Internal Server Error | response.Response |
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 |
|---|---|---|
202 | Accepted | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
409 | Conflict | response.Response |
500 | Internal Server Error | response.Response |
POST /api/v1/admin/apps/{id}/install/{version}
Install an application version
Installs and activates a specific version of an application as a background operation
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 |
|---|---|---|
202 | Accepted | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
409 | Conflict | response.Response |
500 | Internal Server Error | response.Response |
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 |
|---|---|---|
202 | Accepted | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
409 | Conflict | response.Response |
500 | Internal Server Error | response.Response |
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 | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
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 |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
GET /api/v1/admin/clients
List all clients
Retrieves a list of all registered OAuth clients
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
500 | Internal Server Error | response.Response |
POST /api/v1/admin/clients
Register a new client
Registers a new OAuth 2.0 / OIDC client in the system
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
request | body | ClientAddRequest | yes | Client creation payload |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
GET /api/v1/admin/clients/{id}
Get client details
Retrieves details of a specific OAuth client by ID
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Client ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
PUT /api/v1/admin/clients/{id}
Update client details
Updates an existing client's display name, redirect URIs, or allowed grants
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Client ID |
request | body | ClientEditRequest | yes | Client edit payload |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
DELETE /api/v1/admin/clients/{id}
Delete a client
Removes a third-party OAuth client from the system
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Client ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
PUT /api/v1/admin/clients/{id}/toggle
Enable or disable client
Activates or deactivates an OAuth client
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Client ID |
request | body | ClientToggleRequest | yes | Toggle payload |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
GET /api/v1/admin/dap
DAP debug control connection
Control-plane WebSocket used by the Niksphere CLI's DAP proxy to arm, break, step, and inspect the next Client Runtime session created via the Engine's API
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 | response.Response |
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 | response.Response |
401 | Unauthorized | response.Response |
500 | Internal Server Error | response.Response |
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 | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
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 | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
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 | response.Response |
400 | Bad Request | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
500 | Internal Server Error | response.Response |
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 | response.Response |
GET /api/v1/admin/sessions
List active client runtime sessions
Retrieves a snapshot of all currently active client runtime WebSocket sessions
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
DELETE /api/v1/admin/sessions/{id}
Terminate an active client runtime session
Forces the WebSocket connection backing the given session id to close
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Session ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
Tasks
GET /api/v1/admin/tasks
List background tasks
Returns a list of all tracked background tasks
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
GET /api/v1/admin/tasks/{id}
Get task status
Returns status, title, message, percent, and timestamps for a task
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Task ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
DELETE /api/v1/admin/tasks/{id}
Cancel a task
Cancels a task if it has not yet started execution
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Task ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
409 | Conflict | response.Response |
GET /api/v1/admin/tasks/{id}/stream
Stream task events
Streams live newline-delimited JSON events for a task until completion
Parameters:
| Name | Located in | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Task ID |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | response.Response |
401 | Unauthorized | response.Response |
404 | Not Found | response.Response |
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 | response.Response |
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 | response.Response |
404 | Not Found | response.Response |
Data Models & Schemas
github_com_niksphere_niksphere-idpbroker-go.ActorType
github_com_niksphere_niksphere-idpbroker-go.ClientType
ActorAddRequest
| Property | Type | Description |
|---|---|---|
name | string | |
type | any |
ActorEditRequest
| Property | Type | Description |
|---|---|---|
name | string | |
status | string |
ClientAddRequest
| Property | Type | Description |
|---|---|---|
actor_id | string | |
allowed_grants | Array<string> | |
client_id | string | |
client_name | string | |
client_secret | string | |
client_type | any | |
redirect_uris | Array<string> |
ClientEditRequest
| Property | Type | Description |
|---|---|---|
allowed_grants | Array<string> | |
client_name | string | |
redirect_uris | Array<string> |
ClientToggleRequest
| Property | Type | Description |
|---|---|---|
is_active | boolean |
CreatePATRequest
| Property | Type | Description |
|---|---|---|
expiry_days | integer | |
name | string | |
scopes | Array<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 |
HealthResponse
| Property | Type | Description |
|---|---|---|
database | string | |
service | string | |
status | string | |
timestamp | string |
SetPasswordRequest
| Property | Type | Description |
|---|---|---|
password | string | |
username | string |
response.Response
| Property | Type | Description |
|---|---|---|
actor_id | string | |
actor_name | string | |
data | any | |
final | boolean | |
message | string | |
message_code | string | |
percent | integer | |
status | string | |
task_id | string | |
title | string |