Cloud API
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
https://my.niksphere.de/api/v1Endpoints 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 | niksphere-cloud_internal_handlers.AuthMeResponse |
401 | Unauthorized | niksphere-cloud_internal_handlers.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<niksphere-cloud_internal_models.Environment> |
500 | Internal Server Error | niksphere-cloud_internal_handlers.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 | niksphere-cloud_internal_handlers.CreateEnvironmentRequest | yes | Environment details |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
202 | Accepted | niksphere-cloud_internal_handlers.EnvironmentCreatedResponse |
400 | Bad Request | niksphere-cloud_internal_handlers.ErrorResponse |
500 | Internal Server Error | niksphere-cloud_internal_handlers.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 | niksphere-cloud_internal_handlers.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 | niksphere-cloud_internal_handlers.EditEnvironmentRequest | yes | Fields to update |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | niksphere-cloud_internal_models.Environment |
400 | Bad Request | niksphere-cloud_internal_handlers.ErrorResponse |
404 | Not Found | niksphere-cloud_internal_handlers.ErrorResponse |
500 | Internal Server Error | niksphere-cloud_internal_handlers.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 | niksphere-cloud_internal_handlers.OperationQueuedResponse |
404 | Not Found | niksphere-cloud_internal_handlers.ErrorResponse |
500 | Internal Server Error | niksphere-cloud_internal_handlers.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<niksphere-cloud_internal_models.Operation> |
500 | Internal Server Error | niksphere-cloud_internal_handlers.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<niksphere-cloud_internal_models.Region> |
Tenants
GET /api/v1/tenants
List all tenants
Returns all tenants. Requires SUPERUSER role.
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | Array<niksphere-cloud_internal_models.Tenant> |
403 | Forbidden | niksphere-cloud_internal_handlers.ErrorResponse |
500 | Internal Server Error | niksphere-cloud_internal_handlers.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 | niksphere-cloud_internal_handlers.CreateTenantRequest | yes | Tenant details |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
201 | Created | niksphere-cloud_internal_models.Tenant |
400 | Bad Request | niksphere-cloud_internal_handlers.ErrorResponse |
403 | Forbidden | niksphere-cloud_internal_handlers.ErrorResponse |
500 | Internal Server Error | niksphere-cloud_internal_handlers.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 | niksphere-cloud_internal_handlers.SlugCheckResponse |
403 | Forbidden | niksphere-cloud_internal_handlers.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 | niksphere-cloud_internal_handlers.EditTenantRequest | yes | Fields to update |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
200 | OK | niksphere-cloud_internal_models.Tenant |
400 | Bad Request | niksphere-cloud_internal_handlers.ErrorResponse |
403 | Forbidden | niksphere-cloud_internal_handlers.ErrorResponse |
404 | Not Found | niksphere-cloud_internal_handlers.ErrorResponse |
500 | Internal Server Error | niksphere-cloud_internal_handlers.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 | niksphere-cloud_internal_handlers.OperationQueuedResponse |
403 | Forbidden | niksphere-cloud_internal_handlers.ErrorResponse |
404 | Not Found | niksphere-cloud_internal_handlers.ErrorResponse |
500 | Internal Server Error | niksphere-cloud_internal_handlers.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<User> |
403 | Forbidden | niksphere-cloud_internal_handlers.ErrorResponse |
500 | Internal Server Error | niksphere-cloud_internal_handlers.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 | niksphere-cloud_internal_handlers.CreateUserRequest | yes | User details |
Responses:
| Status Code | Description | Schema / Content |
|---|---|---|
201 | Created | User |
400 | Bad Request | niksphere-cloud_internal_handlers.ErrorResponse |
403 | Forbidden | niksphere-cloud_internal_handlers.ErrorResponse |
500 | Internal Server Error | niksphere-cloud_internal_handlers.ErrorResponse |
Data Models & Schemas
User
| Property | Type | Description |
|---|---|---|
created_at | string | |
id | string | |
identities | Array<UserIdentity> | Associations |
name | string | |
tenantId | string | |
type | UserRole | |
updated_at | string |
UserIdentity
| Property | Type | Description |
|---|---|---|
created_at | string | |
id | string | |
identityId | string | |
userId | string |
UserRole
niksphere-cloud_internal_handlers.AuthMeResponse
| Property | Type | Description |
|---|---|---|
role | string | |
sub | string | |
tenantId | string |
niksphere-cloud_internal_handlers.CreateEnvironmentRequest
| Property | Type | Description |
|---|---|---|
name | string | |
region | string | |
slug | string |
niksphere-cloud_internal_handlers.CreateTenantRequest
| Property | Type | Description |
|---|---|---|
name | string | |
slug | string |
niksphere-cloud_internal_handlers.CreateUserRequest
| Property | Type | Description |
|---|---|---|
password | string | |
tenantId | string | |
type | string | |
username | string |
niksphere-cloud_internal_handlers.EditEnvironmentRequest
| Property | Type | Description |
|---|---|---|
name | string | |
slug | string |
niksphere-cloud_internal_handlers.EditTenantRequest
| Property | Type | Description |
|---|---|---|
name | string | |
slug | string |
niksphere-cloud_internal_handlers.EnvironmentCreatedResponse
| Property | Type | Description |
|---|---|---|
environment | niksphere-cloud_internal_models.Environment | |
message | string | |
operation_id | string |
niksphere-cloud_internal_handlers.ErrorResponse
| Property | Type | Description |
|---|---|---|
error | string |
niksphere-cloud_internal_handlers.OperationQueuedResponse
| Property | Type | Description |
|---|---|---|
message | string | |
operation_id | string |
niksphere-cloud_internal_handlers.SlugCheckResponse
| Property | Type | Description |
|---|---|---|
error | string | |
url | string | |
valid | boolean |
niksphere-cloud_internal_models.ActionType
niksphere-cloud_internal_models.Engine
| Property | Type | Description |
|---|---|---|
createdAt | string | |
environmentId | string | |
externalId | string | e.g. Railway Container Service ID |
id | string | |
name | string | |
status | string | |
url | string |
niksphere-cloud_internal_models.Environment
| Property | Type | Description |
|---|---|---|
createdAt | string | |
engine | niksphere-cloud_internal_models.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 |
niksphere-cloud_internal_models.EnvironmentProvider
niksphere-cloud_internal_models.Operation
| Property | Type | Description |
|---|---|---|
actionDetails | string | |
actionType | niksphere-cloud_internal_models.ActionType | |
createdAt | string | |
createdBy | string | |
endsOn | string | |
id | string | |
logs | string | |
result | niksphere-cloud_internal_models.OperationResult | |
scheduledOn | string | |
startedOn | string | |
status | niksphere-cloud_internal_models.OperationStatus | |
tenantId | string |
niksphere-cloud_internal_models.OperationResult
niksphere-cloud_internal_models.OperationStatus
niksphere-cloud_internal_models.Region
| Property | Type | Description |
|---|---|---|
id | niksphere-cloud_internal_models.RegionID | |
name | string | |
provider | niksphere-cloud_internal_models.EnvironmentProvider | |
subdomain | string |
niksphere-cloud_internal_models.RegionID
niksphere-cloud_internal_models.Tenant
| Property | Type | Description |
|---|---|---|
createdAt | string | |
id | string | |
name | string | |
slug | string | |
status | string | READY, DELETING |