Cloud API

v1.0.0-build.52-channel.stable (stable · latest)v1.0.0-build.51-channel.stable (stable)v1.0.0-build.50-channel.stable (stable)v1.0.0-build.53-channel.insider (insider)v1.0.0-build.49-channel.insider (insider)

stable 2026-08-25 JSON ↗

API server for the Niksphere Cloud platform

Server & Base URL

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

http://localhost:8081/api/v1

Endpoints Overview

Method	Endpoint	Summary
GET	/api/v1/auth/me	Get current user info
GET	/api/v1/environments	List environments
POST	/api/v1/environments	Create a new environment
GET	/api/v1/environments/check-slug	Check environment slug availability
PUT	/api/v1/environments/{id}	Edit an environment
DELETE	/api/v1/environments/{id}	Delete an environment
GET	/api/v1/operations	List operations
GET	/api/v1/regions	List available regions
GET	/api/v1/tenants	List all tenants
POST	/api/v1/tenants	Create a new tenant
GET	/api/v1/tenants/check-slug	Check tenant slug availability
PUT	/api/v1/tenants/{id}	Edit a tenant
DELETE	/api/v1/tenants/{id}	Delete a tenant
GET	/api/v1/users	List all users
POST	/api/v1/users	Create a new user

Auth

GET /api/v1/auth/me

Get current user info

Returns the authenticated user's subject, role, and tenant ID from the JWT context

Responses:

Status Code	Description	Schema / Content
200	OK	AuthMeResponse
401	Unauthorized	ErrorResponse

Environments

GET /api/v1/environments

List environments

Returns all environments visible to the authenticated user based on role and tenant

Responses:

Status Code	Description	Schema / Content
200	OK	Array<Environment>
500	Internal Server Error	ErrorResponse

POST /api/v1/environments

Create a new environment

Creates a new environment for a tenant and queues a provisioning operation

Parameters:

Name	Located in	Type	Required	Description
tenantId	query	string	no	Tenant ID (required for SUPERUSER)
body	body	CreateEnvironmentRequest	yes	Environment details

Responses:

Status Code	Description	Schema / Content
202	Accepted	EnvironmentCreatedResponse
400	Bad Request	ErrorResponse
500	Internal Server Error	ErrorResponse

GET /api/v1/environments/check-slug

Check environment slug availability

Validates an environment slug format and checks uniqueness within a tenant

Parameters:

Name	Located in	Type	Required	Description
slug	query	string	yes	Slug to check
tenantId	query	string	no	Tenant ID (used by SUPERUSER)
region	query	string	no	Region ID for URL preview

Responses:

Status Code	Description	Schema / Content
200	OK	SlugCheckResponse

PUT /api/v1/environments/{id}

Edit an environment

Updates the name and/or slug of an existing environment

Parameters:

Name	Located in	Type	Required	Description
id	path	string	yes	Environment ID
body	body	EditEnvironmentRequest	yes	Fields to update

Responses:

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

DELETE /api/v1/environments/{id}

Delete an environment

Queues an environment deletion operation and sets its status to DELETING

Parameters:

Name	Located in	Type	Required	Description
id	path	string	yes	Environment ID

Responses:

Status Code	Description	Schema / Content
202	Accepted	OperationQueuedResponse
404	Not Found	ErrorResponse
500	Internal Server Error	ErrorResponse

Operations

GET /api/v1/operations

List operations

Returns all operations visible to the authenticated user based on role and tenant

Responses:

Status Code	Description	Schema / Content
200	OK	Array<Operation>
500	Internal Server Error	ErrorResponse

Regions

GET /api/v1/regions

List available regions

Returns the list of all available deployment regions

Responses:

Status Code	Description	Schema / Content
200	OK	Array<Region>

Tenants

GET /api/v1/tenants

List all tenants

Returns all tenants. Requires SUPERUSER role.

Responses:

Status Code	Description	Schema / Content
200	OK	Array<Tenant>
403	Forbidden	ErrorResponse
500	Internal Server Error	ErrorResponse

POST /api/v1/tenants

Create a new tenant

Creates a new tenant with the given name and slug. Requires SUPERUSER role.

Parameters:

Name	Located in	Type	Required	Description
body	body	CreateTenantRequest	yes	Tenant details

Responses:

Status Code	Description	Schema / Content
201	Created	Tenant
400	Bad Request	ErrorResponse
403	Forbidden	ErrorResponse
500	Internal Server Error	ErrorResponse

GET /api/v1/tenants/check-slug

Check tenant slug availability

Validates a tenant slug format and checks uniqueness. Requires SUPERUSER role.

Parameters:

Name	Located in	Type	Required	Description
slug	query	string	yes	Slug to check

Responses:

Status Code	Description	Schema / Content
200	OK	SlugCheckResponse
403	Forbidden	ErrorResponse

PUT /api/v1/tenants/{id}

Edit a tenant

Updates the name and/or slug of an existing tenant. Requires SUPERUSER role.

Parameters:

Name	Located in	Type	Required	Description
id	path	string	yes	Tenant ID
body	body	EditTenantRequest	yes	Fields to update

Responses:

Status Code	Description	Schema / Content
200	OK	Tenant
400	Bad Request	ErrorResponse
403	Forbidden	ErrorResponse
404	Not Found	ErrorResponse
500	Internal Server Error	ErrorResponse

DELETE /api/v1/tenants/{id}

Delete a tenant

Queues a tenant deletion operation and sets its status to DELETING. Requires SUPERUSER role.

Parameters:

Name	Located in	Type	Required	Description
id	path	string	yes	Tenant ID

Responses:

Status Code	Description	Schema / Content
202	Accepted	OperationQueuedResponse
403	Forbidden	ErrorResponse
404	Not Found	ErrorResponse
500	Internal Server Error	ErrorResponse

Users

GET /api/v1/users

List all users

Returns all user accounts. Requires SUPERUSER role.

Responses:

Status Code	Description	Schema / Content
200	OK	Array<niksphere-cloud_internal_models.User>
403	Forbidden	ErrorResponse
500	Internal Server Error	ErrorResponse

POST /api/v1/users

Create a new user

Creates a new user identity, credential, and cloud user profile. Requires SUPERUSER role.

Parameters:

Name	Located in	Type	Required	Description
body	body	CreateUserRequest	yes	User details

Responses:

Status Code	Description	Schema / Content
201	Created	niksphere-cloud_internal_models.User
400	Bad Request	ErrorResponse
403	Forbidden	ErrorResponse
500	Internal Server Error	ErrorResponse

Data Models & Schemas

AuthMeResponse

Property	Type	Description
role	string
sub	string
tenantId	string

CreateEnvironmentRequest

Property	Type	Description
name	string
region	string
slug	string

CreateTenantRequest

Property	Type	Description
name	string
slug	string

CreateUserRequest

Property	Type	Description
password	string
tenantId	string
type	string
username	string

EditEnvironmentRequest

Property	Type	Description
name	string
slug	string

EditTenantRequest

Property	Type	Description
name	string
slug	string

EnvironmentCreatedResponse

Property	Type	Description
environment	Environment
message	string
operation_id	string

ErrorResponse

Property	Type	Description
error	string

OperationQueuedResponse

Property	Type	Description
message	string
operation_id	string

SlugCheckResponse

Property	Type	Description
error	string
url	string
valid	boolean

ActionType

Engine

Property	Type	Description
createdAt	string
environmentId	string
externalId	string	e.g. Railway Container Service ID
id	string
name	string
status	string
url	string

Environment

Property	Type	Description
createdAt	string
engine	Engine
externalId	string	e.g. Railway Environment ID
id	string
name	string	e.g. "Acme Workshop"
region	string	selected region ID
regionInfo	any	Enriched dynamically on API read (ignored by GORM)
slug	string	e.g. "acme-workshop"
status	string	PENDING, READY, DELETING
tenant	any	Associations
tenantId	string

EnvironmentProvider

Operation

Property	Type	Description
actionDetails	string
actionType	ActionType
createdAt	string
createdBy	string
endsOn	string
id	string
logs	string
result	OperationResult
scheduledOn	string
startedOn	string
status	OperationStatus
tenantId	string

OperationResult

OperationStatus

Region

Property	Type	Description
id	RegionID
name	string
provider	EnvironmentProvider
subdomain	string

RegionID

Tenant

Property	Type	Description
createdAt	string
id	string
name	string
slug	string
status	string	READY, DELETING

niksphere-cloud_internal_models.User

Property	Type	Description
created_at	string
id	string
identities	Array<niksphere-cloud_internal_models.UserIdentity>	Associations
name	string
tenantId	string
type	niksphere-cloud_internal_models.UserRole
updated_at	string

niksphere-cloud_internal_models.UserIdentity

Property	Type	Description
created_at	string
id	string
identityId	string
userId	string

niksphere-cloud_internal_models.UserRole