API reference

GET /api/v1/api-keys

List my API keys

Responses

• 200 OK - APIKeysOutputBody
  Fields

  Field	Type	Description
  items required	array of APIKey

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/api-keys

Create an API key

Request body application/json

Responses

• 201 Created - CreateAPIKeyOutputBody
  Fields

  Field	Type	Description
  api_key required	APIKey
  token required	string	The key itself. Shown only now; store it safely.

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/api-keys/{id}

Revoke one of my API keys

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/auth/me/ssh-keys

Your SSH keys for SFTP

Responses

• 200 OK - List-ssh-keysResponse
  Fields

  Field	Type	Description
  items required	array of SSHKeyOut

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/auth/me/ssh-keys

Add an SSH public key for SFTP

Request body application/json

Responses

• 201 Created - SSHKeyOut
  Fields

  Field	Type	Description
  created_at required	string (date-time)
  fingerprint required	string
  id required	integer (int64)
  last_used_at required	string (nullable) (date-time)
  name required	string
  public_key required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/auth/me/ssh-keys/{id}

Remove an SSH key

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/agent/ca

The agent CA certificate (agents verify it against --ca-hash before enrolling)

No authentication needed.

Responses

• 200 OK - CAInfo
  Fields

  Field	Type	Description
  ca_hash required	string	sha256:<hex> of the CA's SubjectPublicKeyInfo
  ca_pem required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/agent/enroll

Enroll a node (called by ngcp-agent enroll)

Consumes a one-time token, creates the node and signs the agent's certificate. The agent must verify ca_pem against the --ca-hash it was given.

No authentication needed.

Request body application/json

Responses

• 200 OK - Response
  Fields

  Field	Type	Description
  ca_pem required	string	Verify its SubjectPublicKeyInfo hash against the --ca-hash from the token
  certificate_pem required	string
  grpc_address required	string	host:port of the AgentLink endpoint
  node_id required	integer (int64)
  node_name required	string
  update_public_key required	string	Ed25519 key (hex) that signs agent updates

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/agent/releases

Agent builds available for self-update

Responses

• 200 OK - List-agent-releasesResponse
  Fields

  Field	Type	Description
  items required	array of AgentRelease

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/audit-events

Search the audit log

Responses

• 200 OK - PageAuditEvent
  Fields

  Field	Type	Description
  items required	array of AuditEvent
  next_cursor required	string	Pass as ?cursor= to get the next page; empty when there are no more

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/auth/login

Sign in with username/email and password

On success without 2FA, sets the session cookie and returns the CSRF token. With 2FA on, returns status mfa_required and an mfa_token for POST /auth/login/mfa.

No authentication needed.

Request body application/json

Responses

• 200 OK - LoginBody
  Fields

  Field	Type	Description
  csrf_token	string	Send as X-CSRF-Token on every state-changing request
  mfa_token	string	Send with the code to POST /auth/login/mfa (valid 5 minutes)
  status required	string: ok, mfa_required
  user	User

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/auth/login/mfa

Complete sign-in with a 2FA code or recovery code

No authentication needed.

Request body application/json

Responses

• 200 OK - LoginBody
  Fields

  Field	Type	Description
  csrf_token	string	Send as X-CSRF-Token on every state-changing request
  mfa_token	string	Send with the code to POST /auth/login/mfa (valid 5 minutes)
  status required	string: ok, mfa_required
  user	User

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/auth/logout

Sign out of this session

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/auth/logout-all

Sign out of every session, including this one

Responses

• 200 OK - LogoutAllOutputBody
  Fields

  Field	Type	Description
  sessions_ended required	integer (int64)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/auth/me

Who am I

Responses

• 200 OK - MeBody
  Fields

  Field	Type	Description
  auth_method required	string: session, api_key
  branding required	MeBranding	What this account sees: the panel's branding, overridden by its reseller's
  client_ip required	string	The address this request came from, as the controller sees it
  csrf_token	string
  mfa_enrollment_required required	boolean	Policy requires turning on 2FA before anything else
  password_min_length required	integer (int64)	Current password policy, for form hints
  permissions required	array of string	Effective global permissions
  recovery_codes_left required	integer (int64)
  user required	User

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PATCH /api/v1/auth/me

Change my display name or email address

Request body application/json

Responses

• 200 OK - User
  Fields

  Field	Type	Description
  created_at required	string (date-time)
  denied_permissions required	array of string
  display_name required	string
  email required	string
  extra_permissions required	array of string
  id required	integer (int64)
  last_login_at required	string (nullable) (date-time)
  last_login_ip required	string (nullable)
  locked_until required	string (nullable) (date-time)
  must_change_password required	boolean
  reseller_id required	integer (nullable) (int64)
  role required	string: superadmin, admin, reseller, user, subuser
  status required	string: active, suspended, disabled
  totp_enabled required	boolean
  updated_at required	string (date-time)
  username required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/auth/password

Change my password (ends my other sessions)

Request body application/json

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/auth/recovery-codes

Replace my recovery codes

Request body application/json

Responses

• 200 OK - RecoveryCodesOutputBody
  Fields

  Field	Type	Description
  recovery_codes required	array of string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/auth/sessions

List my active sessions

Responses

• 200 OK - SessionsOutputBody
  Fields

  Field	Type	Description
  items required	array of Session

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/auth/sessions/{id}

End one of my sessions

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/auth/totp/disable

Turn off two-factor authentication

Request body application/json

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/auth/totp/enable

Confirm a code and turn on two-factor authentication

Returns recovery codes. They are shown only once.

Request body application/json

Responses

• 200 OK - RecoveryCodesOutputBody
  Fields

  Field	Type	Description
  recovery_codes required	array of string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/auth/totp/setup

Start turning on two-factor authentication

Request body application/json

Responses

• 200 OK - TOTPSetupOutputBody
  Fields

  Field	Type	Description
  otpauth_uri required	string	Render as a QR code
  secret required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/public/branding

Branding for the sign-in page

No authentication needed.

Responses

• 200 OK - BrandingOutputBody
  Fields

  Field	Type	Description
  password_min_length required	integer (int64)	Password policy, for form hints
  product_name required	string
  support_url required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/backup-targets

Backup targets (local folder, SFTP, S3-compatible)

Responses

• 200 OK - ItemsTargetViewBody
  Fields

  Field	Type	Description
  items required	array of TargetView

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/backup-targets

Add a backup target

Request body application/json

Responses

• 201 Created - TargetView
  Fields

  Field	Type	Description
  config required	TargetConfig
  created_at required	string (date-time)
  has_password required	boolean
  has_private_key required	boolean
  has_secret_key required	boolean
  id required	integer (int64)
  keep_days required	integer (int32)
  keep_last required	integer (int32)
  kind required	string: local, sftp, s3
  name required	string
  updated_at required	string (date-time)
  user_selectable required	boolean

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/backup-targets/{id}

Change a backup target (its kind stays)

Request body application/json

Responses

• 200 OK - TargetView
  Fields

  Field	Type	Description
  config required	TargetConfig
  created_at required	string (date-time)
  has_password required	boolean
  has_private_key required	boolean
  has_secret_key required	boolean
  id required	integer (int64)
  keep_days required	integer (int32)
  keep_last required	integer (int32)
  kind required	string: local, sftp, s3
  name required	string
  updated_at required	string (date-time)
  user_selectable required	boolean

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/backup-targets/{id}

Remove a backup target no task uses (its backups stay where they are)

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/backups

A service's backups

Responses

• 200 OK - SvcBackupsBody
  Fields

  Field	Type	Description
  items required	array of BackupView
  targets required	array of TargetChoice	Where the caller may back this service up to

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/services/{id}/backups

Back a service up now

The node streams a .tar.gz of the service's files to the target while the server keeps running; progress arrives as "backups" events on the WebSocket topic service:{id}.

Request body application/json

Responses

• 202 Accepted - BackupView
  Fields

  Field	Type	Description
  completed_at	string (date-time)
  created_at required	string (date-time)
  error required	string
  id required	integer (int64)
  location required	string
  message required	string
  provider required	string
  restore_error required	string
  restore_status required	string: , running, completed, failed
  restored_at	string (date-time)
  scheduled required	boolean
  size_bytes required	integer (int64)
  status required	string: pending, running, completed, failed, deleted
  target required	string
  target_id	integer (int64)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/services/{id}/backups/{backup_id}

Delete a backup from its target

Responses

• 202 Accepted
• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/services/{id}/backups/{backup_id}/restore

Restore a backup

The node stops the service, downloads and unpacks the backup into a staging folder, replaces the backed-up files and starts the service again if it was running.

Responses

• 202 Accepted
• 4xx/5xx error envelope {"error":{"code","message","details"}}

PATCH /api/v1/services/{id}/package

Move a game server to another package of the same game (billing: upgrade / downgrade)

Applies the package's limits; slots are clamped into the new range unless given. Administrators, the owner's reseller and billing keys.

Request body application/json

Responses

• 200 OK - View
  Fields

  Field	Type	Description
  cpu_limit_percent required	integer (int32)	0 = unlimited; 100 = one core
  cpu_percent required	number (nullable) (float)
  crash_policy required	CrashPolicy
  created_at required	string (date-time)
  desired_state required	string: running, stopped
  disk_limit_bytes required	integer (int64)	File manager / SFTP / upload quota; 0 = unlimited
  external_id required	string (nullable)	The billing system's reference
  file_deny required	array of string	Deny globs added for this service (on top of the game definition's): matching paths are hidden from everyone except administrators
  game_id required	string
  has_rcon	boolean	The game has a remote console (only on GET /services/{id})
  has_workshop	boolean	The game takes Steam Workshop mods (only on GET /services/{id})
  id required	integer (int64)
  install	InstallProgress	While installing / updating
  install_dir required	string
  installed required	boolean	The game files are in place
  ip required	string
  last_error required	string	The last command the agent refused, and why
  last_exit_code required	integer (nullable) (int32)
  max_players required	integer (nullable) (int32)
  memory_limit_bytes required	integer (int64)	0 = unlimited
  memory_used_bytes required	integer (nullable) (int64)
  metrics_at required	string (nullable) (date-time)
  mods required	object	Workshop items per modlist variable
  name required	string
  node_connected required	boolean	The node's agent link is up
  node_id required	integer (int64)
  node_name required	string
  node_os required	string: windows, linux
  observed_at required	string (nullable) (date-time)
  observed_message required	string
  observed_status required	string	What the agent last reported
  os_user required	string
  owner_user_id required	integer (int64)
  owner_username required	string
  package_id required	integer (nullable) (int64)	The package it was ordered with (null = none)
  permissions	array of string	What the caller may do on this service (absent on WebSocket events)
  players required	integer (nullable) (int32)	From the game's status query while it runs (null = unknown)
  ports	array of PortView	Only on GET /services/{id}
  primary_port required	integer (nullable) (int32)
  process_count required	integer (nullable) (int32)
  processes	array of ProcessView	Only on GET /services/{id}
  query_at required	string (nullable) (date-time)
  query_map required	string
  query_name required	string	Server name the game reports
  restarts required	integer (int32)	Crash restarts within the crash-policy window
  secret_variables required	array of string	Password variables that have a value (values are never returned)
  sftp	SFTPInfo	How the caller connects with SFTP (only on GET /services/{id}, with the files permission)
  slots required	integer (int32)
  status required	string: installing, install_failed, stopped, starting, running, stopping, crashed, suspended, moving, deleting
  steam_account_id required	integer (nullable) (int64)
  suspend_reason required	string	Why it was suspended (billing or an administrator)
  suspended required	boolean
  variables required	object

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/usage

Disk, CPU, memory and player usage of a game server (billing usage updates)

Responses

• 200 OK - UsageReport
  Fields

  Field	Type	Description
  cpu_avg_percent required	number (double)	100 = one core
  cpu_max_percent required	number (double)
  disk_limit_bytes required	integer (int64)	0 = unlimited
  disk_measured_at required	string (nullable) (date-time)	When the disk usage was measured (older when the node is offline)
  disk_used_bytes required	integer (nullable) (int64)	The service directory's size; null when never measured
  mem_avg_bytes required	integer (int64)
  mem_limit_bytes required	integer (int64)	0 = unlimited
  mem_max_bytes required	integer (int64)
  net_measured required	boolean	Per-service network traffic is not measured yet (always false)
  players_max required	integer (int32)
  samples required	integer (int64)	Resource samples in the period (one per minute while running)
  service_id required	integer (int64)
  since required	string (date-time)
  slots required	integer (int32)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/users/{id}/sso-link

A one-time sign-in link for a customer account ("Log in to panel")

Only for user and sub-user accounts in the caller's tenancy. With service_id the link opens that game server (the account must own it or have access).

Request body application/json

Responses

• 200 OK - SsoOutBody
  Fields

  Field	Type	Description
  expires_at required	string (date-time)
  url required	string	Open this in the customer's browser; it works once, for 60 seconds

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/configs

The service's config files as forms

Settings come from the game definition; bound settings follow a panel value (a variable or the slot count) and show it.

Responses

• 200 OK - List-configsResponse
  Fields

  Field	Type	Description
  items required	array of ConfigFileView

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/services/{id}/configs/{index}

Save a config form

values: the settings to change (others stay as they are). A bound setting changes its variable / the slot count instead; the file follows. A password left null is unchanged. hash: the form's version (409 when the file changed meanwhile).

Request body application/json

Responses

• 200 OK - ConfigFileView
  Fields

  Field	Type	Description
  error	string	Why the file could not be read or parsed
  exists required	boolean
  format required	string
  hash	string	Content version; send it back to detect concurrent edits
  index required	integer (int64)	Position in the game definition's config_files
  label required	string
  path required	string
  settings required	array of ConfigSettingView

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/datacenters

List datacenters

Responses

• 200 OK - List-datacentersResponse
  Fields

  Field	Type	Description
  items required	array of Datacenter

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/datacenters

Create a datacenter

Request body application/json

Responses

• 201 Created - Datacenter
  Fields

  Field	Type	Description
  created_at required	string (date-time)
  id required	integer (int64)
  location required	string
  name required	string
  node_count required	integer (int64)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/datacenters/{id}

Rename or relocate a datacenter

Request body application/json

Responses

• 200 OK - Datacenter
  Fields

  Field	Type	Description
  created_at required	string (date-time)
  id required	integer (int64)
  location required	string
  name required	string
  node_count required	integer (int64)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/datacenters/{id}

Delete an empty datacenter

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/files

List a folder of the service

Directories first, then by name. Paths the game definition or an administrator denies are left out (administrators see them).

Responses

• 200 OK - List-filesResponse
  Fields

  Field	Type	Description
  items required	array of FileEntry
  path required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/files/content

Open a text file in the editor

Files up to 2 MiB; larger ones are downloaded.

Responses

• 200 OK - FileContentOut
  Fields

  Field	Type	Description
  binary required	boolean	Not UTF-8 text: download it instead
  content required	string	UTF-8 text; empty when binary
  entry required	FileEntry
  hash required	string	Send back as expect when saving

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/services/{id}/files/content

Save a text file from the editor

expect: omit to overwrite or create, "absent" to only create, or the hash the editor read (409 conflict when the file changed meanwhile).

Request body application/json

Responses

• 200 OK - Write-fileResponse
  Fields

  Field	Type	Description
  entry required	FileEntry
  hash required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/services/{id}/files/direct-download

A signed URL to download straight from the node

null when the node has no direct file endpoint; then use GET .../files/download. The URL works for one hour.

Request body application/json

Responses

• 200 OK - Direct-downloadResponse
  Fields

  Field	Type	Description
  direct required	DirectTarget

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/files/download

Download a file

Streams from the node through the controller (constant memory). For a direct node URL use POST .../files/direct-download.

Responses

• 200 The file - string (binary)
• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/services/{id}/files/ops

Create a folder, rename / move, copy, delete, change permissions, compress or extract

mkdir: path. rename / copy: path -> dest (rename with overwrite replaces a file). delete: paths. chmod: path + mode (octal bits as a number, Linux; Windows only toggles read-only). compress: paths -> dest (.zip, .tar.gz, .tar). extract: path (an archive) -> dest folder (overwrite replaces existing files).

Request body application/json

Responses

• 200 OK - File-operationResponse
  Fields

  Field	Type	Description
  entry	FileEntry
  files	integer (int64)	extract: files written
  skipped	array of string	extract: entries left out (existing, denied, links)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/files/search

Find files and folders by name below a folder

Responses

• 200 OK - Search-filesResponse
  Fields

  Field	Type	Description
  items required	array of FileEntry
  truncated required	boolean	More than 500 matches

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/files/stat

Describe one file or folder

Responses

• 200 OK - FileEntry
  Fields

  Field	Type	Description
  mode required	integer (int32)	(min 0)
  modified required	string (date-time)
  name required	string
  path required	string
  size required	integer (int64)
  type required	string: file, dir, link, other

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/files/usage

The service directory's size and quota

Responses

• 200 OK - ServiceDiskUsage
  Fields

  Field	Type	Description
  quota_bytes required	integer (int64)	0 = unlimited
  used_bytes required	integer (int64)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/services/{id}/uploads

Start a chunked upload

Then PUT each chunk (chunk_bytes at most, in order) to .../uploads/{upload}?offset=N, and POST .../complete. After a 409 conflict on a chunk (a gap or a retry from the wrong place), GET .../uploads/{upload} returns received: resume there. When direct is set, the chunks may go straight to the node instead (PUT {direct.url}?offset=N with header Authorization: Bearer {direct.token}).

Request body application/json

Responses

• 201 Created - UploadInfo
  Fields

  Field	Type	Description
  chunk_bytes required	integer (int64)
  direct	DirectTarget	Upload straight to the node (PUT {url}?offset=N with the token); fall back to the controller when it fails
  id required	string
  path required	string
  received required	integer (int64)
  size required	integer (int64)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/uploads/{upload}

How much of an upload the node has (to resume)

Responses

• 200 OK - UploadInfo
  Fields

  Field	Type	Description
  chunk_bytes required	integer (int64)
  direct	DirectTarget	Upload straight to the node (PUT {url}?offset=N with the token); fall back to the controller when it fails
  id required	string
  path required	string
  received required	integer (int64)
  size required	integer (int64)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/services/{id}/uploads/{upload}

Send one chunk of an upload

The raw bytes (application/octet-stream), at most 64 MiB per request. They stream to the node; the controller keeps no copy.

Request body application/octet-stream

Responses

• 200 OK - Upload-chunkResponse
  Fields

  Field	Type	Description
  received required	integer (int64)	Bytes the node has now

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/services/{id}/uploads/{upload}

Cancel an upload and drop what was sent

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/services/{id}/uploads/{upload}/complete

Finish an upload: the file appears at its path

Responses

• 200 OK - FileEntry
  Fields

  Field	Type	Description
  mode required	integer (int32)	(min 0)
  modified required	string (date-time)
  name required	string
  path required	string
  size required	integer (int64)
  type required	string: file, dir, link, other

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/game-definitions

Every game definition, enabled or not, with its origin and use

Responses

• 200 OK - List-game-definitionsResponse
  Fields

  Field	Type	Description
  items required	array of GameAdmin

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/game-definitions

Upload a new or changed game definition

The definition is validated first (422 with every problem). Its version must be higher than the stored one; a saved built-in becomes custom and is no longer refreshed by controller upgrades.

Request body application/json

Responses

• 200 OK - GameSource
  Fields

  Field	Type	Description
  category required	string
  enabled required	boolean
  has_rcon required	boolean	The game has a remote console (RCON console, rcon tasks, stop over RCON)
  has_workshop required	boolean	modlist variables take Steam Workshop ids or links
  id required	string
  install_steps required	object	Install steps per OS
  name required	string
  needs_steam_account required	boolean	Installing needs a Steam account in the vault
  origin required	string: builtin, custom	builtin definitions refresh with the controller until someone edits them
  platforms required	array of string
  ports required	array of GamePort
  scripts required	object
  service_count required	integer (int64)
  slots_default required	integer (int64)
  slots_max required	integer (int64)
  slots_min required	integer (int64)
  source_yaml required	string
  updated_at required	string (date-time)
  variables required	array of GameVariable
  version required	integer (int64)
  versions required	array of GameVersion

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/game-definitions/validate

Check a game.yaml without saving it

Always 200: valid is false with every problem (path or line + message) when the definition has errors.

Request body application/json

Responses

• 200 OK - Validate-game-definitionResponse
  Fields

  Field	Type	Description
  game	Game
  problems required	array of ValidationProblem
  valid required	boolean

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/game-definitions/{game}

A game definition with its YAML, scripts and versions

Responses

• 200 OK - GameSource
  Fields

  Field	Type	Description
  category required	string
  enabled required	boolean
  has_rcon required	boolean	The game has a remote console (RCON console, rcon tasks, stop over RCON)
  has_workshop required	boolean	modlist variables take Steam Workshop ids or links
  id required	string
  install_steps required	object	Install steps per OS
  name required	string
  needs_steam_account required	boolean	Installing needs a Steam account in the vault
  origin required	string: builtin, custom	builtin definitions refresh with the controller until someone edits them
  platforms required	array of string
  ports required	array of GamePort
  scripts required	object
  service_count required	integer (int64)
  slots_default required	integer (int64)
  slots_max required	integer (int64)
  slots_min required	integer (int64)
  source_yaml required	string
  updated_at required	string (date-time)
  variables required	array of GameVariable
  version required	integer (int64)
  versions required	array of GameVersion

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PATCH /api/v1/game-definitions/{game}

Offer or hide a game for new services

Request body application/json

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/game-definitions/{game}

Delete a custom definition that no service uses

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/game-definitions/{game}/versions/{version}

The YAML of an earlier version (for a diff)

Responses

• 200 OK - Get-game-definition-versionResponse
  Fields

  Field	Type	Description
  source_yaml required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/games

Game definitions available for new services

Responses

• 200 OK - List-gamesResponse
  Fields

  Field	Type	Description
  items required	array of Game

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/meta/permissions

Roles and permission flags

Responses

• 200 OK - CatalogOutputBody
  Fields

  Field	Type	Description
  permissions required	array of string
  roles required	array of RoleInfo
  service_permissions required	array of string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/game-definitions/{game}/mods

A game's mod catalog

Responses

• 200 OK - ItemsCatalogModBody
  Fields

  Field	Type	Description
  items required	array of CatalogMod

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/game-definitions/{game}/mods

Add a Workshop item or collection to a game's mod catalog

Request body application/json

Responses

• 201 Created - CatalogMod
  Fields

  Field	Type	Description
  created_at required	string (date-time)
  description required	string
  game_id required	string
  id required	integer (int64)
  kind required	string: workshop, workshop_collection
  name required	string
  updated_at required	string (date-time)
  workshop_id required	integer (int64)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/game-definitions/{game}/mods/{mod_id}

Change a catalog entry

Request body application/json

Responses

• 200 OK - CatalogMod
  Fields

  Field	Type	Description
  created_at required	string (date-time)
  description required	string
  game_id required	string
  id required	integer (int64)
  kind required	string: workshop, workshop_collection
  name required	string
  updated_at required	string (date-time)
  workshop_id required	integer (int64)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/game-definitions/{game}/mods/{mod_id}

Remove a catalog entry (services keep their mods)

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/services/{id}/mods

A service's mod lists and its game's mod catalog

Responses

• 200 OK - ServiceModsView
  Fields

  Field	Type	Description
  catalog required	array of CatalogMod
  installed required	boolean
  lists required	array of ModList
  workshop required	boolean	The game takes Steam Workshop mods

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/services/{id}/mods/expand

Resolve a Workshop id or link (a collection becomes its items, with titles)

Request body application/json

Responses

• 200 OK - ItemsWorkshopItemBody
  Fields

  Field	Type	Description
  items required	array of WorkshopItem

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/services/{id}/mods/{variable}

Replace one mod list (Workshop ids in load order)

Request body application/json

Responses

• 200 OK - SetModsOutBody
  Fields

  Field	Type	Description
  cpu_limit_percent required	integer (int32)	0 = unlimited; 100 = one core
  cpu_percent required	number (nullable) (float)
  crash_policy required	CrashPolicy
  created_at required	string (date-time)
  desired_state required	string: running, stopped
  disk_limit_bytes required	integer (int64)	File manager / SFTP / upload quota; 0 = unlimited
  external_id required	string (nullable)	The billing system's reference
  file_deny required	array of string	Deny globs added for this service (on top of the game definition's): matching paths are hidden from everyone except administrators
  game_id required	string
  has_rcon	boolean	The game has a remote console (only on GET /services/{id})
  has_workshop	boolean	The game takes Steam Workshop mods (only on GET /services/{id})
  id required	integer (int64)
  install	InstallProgress	While installing / updating
  install_dir required	string
  installed required	boolean	The game files are in place
  ip required	string
  last_error required	string	The last command the agent refused, and why
  last_exit_code required	integer (nullable) (int32)
  max_players required	integer (nullable) (int32)
  memory_limit_bytes required	integer (int64)	0 = unlimited
  memory_used_bytes required	integer (nullable) (int64)
  metrics_at required	string (nullable) (date-time)
  mods required	object	Workshop items per modlist variable
  mods_changed required	boolean	Run the update action to download the new mods
  name required	string
  node_connected required	boolean	The node's agent link is up
  node_id required	integer (int64)
  node_name required	string
  node_os required	string: windows, linux
  observed_at required	string (nullable) (date-time)
  observed_message required	string
  observed_status required	string	What the agent last reported
  os_user required	string
  owner_user_id required	integer (int64)
  owner_username required	string
  package_id required	integer (nullable) (int64)	The package it was ordered with (null = none)
  permissions	array of string	What the caller may do on this service (absent on WebSocket events)
  players required	integer (nullable) (int32)	From the game's status query while it runs (null = unknown)
  ports	array of PortView	Only on GET /services/{id}
  primary_port required	integer (nullable) (int32)
  process_count required	integer (nullable) (int32)
  processes	array of ProcessView	Only on GET /services/{id}
  query_at required	string (nullable) (date-time)
  query_map required	string
  query_name required	string	Server name the game reports
  restarts required	integer (int32)	Crash restarts within the crash-policy window
  secret_variables required	array of string	Password variables that have a value (values are never returned)
  sftp	SFTPInfo	How the caller connects with SFTP (only on GET /services/{id}, with the files permission)
  slots required	integer (int32)
  status required	string: installing, install_failed, stopped, starting, running, stopping, crashed, suspended, moving, deleting
  steam_account_id required	integer (nullable) (int64)
  suspend_reason required	string	Why it was suspended (billing or an administrator)
  suspended required	boolean
  variables required	object

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/enrollment-tokens

Pending (unused, unexpired) enrollment tokens

Responses

• 200 OK - List-enrollment-tokensResponse
  Fields

  Field	Type	Description
  items required	array of EnrollmentToken

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/enrollment-tokens

Create a one-time token to add a node

Request body application/json

Responses

• 201 Created - NewTokenOutBody
  Fields

  Field	Type	Description
  ca_hash required	string
  commands required	object	Ready-to-paste commands: windows, linux (enroll an agent installed from its package); linux_install, windows_install (one-line installers, present when the panel serves the agent packages)
  created_at required	string (date-time)
  datacenter_id required	integer (int64)
  expires_at required	string (date-time)
  hint required	string
  id required	integer (int64)
  node_name required	string
  token required	string	Shown once

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/enrollment-tokens/{id}

Cancel an unused enrollment token

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/nodes

List nodes with live status and the latest metrics

Responses

• 200 OK - List-nodesResponse
  Fields

  Field	Type	Description
  items required	array of Node

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/nodes/{id}

Get a node

Responses

• 200 OK - Node
  Fields

  Field	Type	Description
  agent_version required	string
  arch required	string
  capabilities required	array of string
  cert_not_after required	string (nullable) (date-time)
  connected required	boolean	The agent link is up right now
  connected_at required	string (nullable) (date-time)
  cpu_cores required	integer (int32)
  cpu_percent required	number (nullable) (float)
  created_at required	string (date-time)
  datacenter_id required	integer (int64)
  disk_bytes required	integer (int64)
  disks required	array of DiskUsage
  firewall_managed required	boolean
  hostname required	string
  id required	integer (int64)
  ip_addresses	array of NodeIP	Only on GET /nodes/{id}
  last_seen_at required	string (nullable) (date-time)
  memory_bytes required	integer (int64)
  memory_used_bytes required	integer (nullable) (int64)
  metrics_at required	string (nullable) (date-time)
  mode required	string: active, draining, disabled	Operator mode; draining/disabled persist across disconnects (see connected for the link)
  name required	string
  net_rx_bytes required	integer (nullable) (int64)
  net_tx_bytes required	integer (nullable) (int64)
  os required	string: windows, linux
  os_version required	string
  overcommit_percent required	integer (int32)
  port_range_end required	integer (int32)
  port_range_start required	integer (int32)
  services_dir required	string
  status required	string: pending, online, offline, draining, disabled
  steamcmd_dir required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PATCH /api/v1/nodes/{id}

Change node settings or mode (active, draining, disabled)

Request body application/json

Responses

• 200 OK - Node
  Fields

  Field	Type	Description
  agent_version required	string
  arch required	string
  capabilities required	array of string
  cert_not_after required	string (nullable) (date-time)
  connected required	boolean	The agent link is up right now
  connected_at required	string (nullable) (date-time)
  cpu_cores required	integer (int32)
  cpu_percent required	number (nullable) (float)
  created_at required	string (date-time)
  datacenter_id required	integer (int64)
  disk_bytes required	integer (int64)
  disks required	array of DiskUsage
  firewall_managed required	boolean
  hostname required	string
  id required	integer (int64)
  ip_addresses	array of NodeIP	Only on GET /nodes/{id}
  last_seen_at required	string (nullable) (date-time)
  memory_bytes required	integer (int64)
  memory_used_bytes required	integer (nullable) (int64)
  metrics_at required	string (nullable) (date-time)
  mode required	string: active, draining, disabled	Operator mode; draining/disabled persist across disconnects (see connected for the link)
  name required	string
  net_rx_bytes required	integer (nullable) (int64)
  net_tx_bytes required	integer (nullable) (int64)
  os required	string: windows, linux
  os_version required	string
  overcommit_percent required	integer (int32)
  port_range_end required	integer (int32)
  port_range_start required	integer (int32)
  services_dir required	string
  status required	string: pending, online, offline, draining, disabled
  steamcmd_dir required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/nodes/{id}

Remove a node (revokes its certificate and disconnects it)

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/nodes/{id}/metrics

Node resource samples (up to 24 h)

Responses

• 200 OK - Get-node-metricsResponse
  Fields

  Field	Type	Description
  items required	array of MetricSample

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/nodes/{id}/update-agent

Send a signed self-update to a connected agent

Request body application/json

Responses

• 202 Accepted - Update-node-agentResponse
  Fields

  Field	Type	Description
  request_id required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/notification-deliveries

The latest 200 deliveries with their status

Responses

• 200 OK - ItemsDeliveryBody
  Fields

  Field	Type	Description
  items required	array of Delivery

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/notification-events

Events a webhook can subscribe to

Responses

• 200 OK - ItemsStringBody
  Fields

  Field	Type	Description
  items required	array of string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/settings/notification-templates

Message templates per event (Go text/template over the event: .Service .Node .Message .Panel)

Responses

• 200 OK - ItemsTemplateViewBody
  Fields

  Field	Type	Description
  items required	array of TemplateView

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/settings/notification-templates

Replace the template overrides (an empty text uses the default)

Request body application/json

Responses

• 200 OK - ItemsTemplateViewBody
  Fields

  Field	Type	Description
  items required	array of TemplateView

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/settings/smtp

The outgoing mail server for e-mail notifications

Responses

• 200 OK - SMTPView
  Fields

  Field	Type	Description
  from required	string
  has_password required	boolean
  host required	string
  port required	integer (int64)
  security required	string: starttls, tls, none,
  username required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/settings/smtp

Change the mail server (an empty host turns e-mail off)

Request body application/json

Responses

• 200 OK - SMTPView
  Fields

  Field	Type	Description
  from required	string
  has_password required	boolean
  host required	string
  port required	integer (int64)
  security required	string: starttls, tls, none,
  username required	string

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/webhooks

Webhooks: generic (HMAC-signed JSON), Discord and e-mail

Responses

• 200 OK - ItemsWebhookViewBody
  Fields

  Field	Type	Description
  items required	array of WebhookView

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/webhooks

Add a webhook

Generic webhooks receive the event as JSON with X-NGCP-Event, X-NGCP-Timestamp and, with a secret, X-NGCP-Signature: sha256=hex(HMAC-SHA256(secret, timestamp + "." + body)).

Request body application/json

Responses

• 201 Created - WebhookView
  Fields

  Field	Type	Description
  created_at required	string (date-time)
  enabled required	boolean
  events required	array of string	Empty = every event
  has_secret required	boolean
  id required	integer (int64)
  kind required	string: generic, discord, email
  name required	string
  updated_at required	string (date-time)
  url required	string	Generic: the endpoint; Discord: masked; email: the addresses

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/webhooks/{id}

Change a webhook (its kind stays)

Request body application/json

Responses

• 200 OK - WebhookView
  Fields

  Field	Type	Description
  created_at required	string (date-time)
  enabled required	boolean
  events required	array of string	Empty = every event
  has_secret required	boolean
  id required	integer (int64)
  kind required	string: generic, discord, email
  name required	string
  updated_at required	string (date-time)
  url required	string	Generic: the endpoint; Discord: masked; email: the addresses

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/webhooks/{id}

Remove a webhook

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/webhooks/{id}/test

Send a test message (see the delivery log)

Responses

• 202 Accepted
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/packages

Packages (products): all for administrators, the global ones plus their own for resellers

Responses

• 200 OK - PackagesOutBody
  Fields

  Field	Type	Description
  items required	array of Package

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/packages

Create a package

Request body application/json

Responses

• 201 Created - Package
  Fields

  Field	Type	Description
  allowed_datacenter_ids required	array of integer (int64)	Empty = any datacenter
  cpu_limit_percent required	integer (int32)	0 = unlimited; 100 = one core
  created_at required	string (date-time)
  description required	string
  disk_limit_bytes required	integer (int64)	File manager / SFTP / upload quota; 0 = unlimited
  enabled required	boolean	Disabled packages cannot be ordered; existing game servers keep running
  game_id required	string
  id required	integer (int64)
  memory_limit_bytes required	integer (int64)	0 = unlimited
  name required	string
  reseller_id required	integer (int64)	0 = a global package (every reseller may sell it)
  service_count required	integer (int64)
  slots_default required	integer (int32)
  slots_max required	integer (int32)
  slots_min required	integer (int32)
  start_on_create required	boolean	Start new game servers after the install
  updated_at required	string (date-time)
  variables required	object	Startup variable defaults for new game servers

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/packages/{id}

A package

Responses

• 200 OK - Package
  Fields

  Field	Type	Description
  allowed_datacenter_ids required	array of integer (int64)	Empty = any datacenter
  cpu_limit_percent required	integer (int32)	0 = unlimited; 100 = one core
  created_at required	string (date-time)
  description required	string
  disk_limit_bytes required	integer (int64)	File manager / SFTP / upload quota; 0 = unlimited
  enabled required	boolean	Disabled packages cannot be ordered; existing game servers keep running
  game_id required	string
  id required	integer (int64)
  memory_limit_bytes required	integer (int64)	0 = unlimited
  name required	string
  reseller_id required	integer (int64)	0 = a global package (every reseller may sell it)
  service_count required	integer (int64)
  slots_default required	integer (int32)
  slots_max required	integer (int32)
  slots_min required	integer (int32)
  start_on_create required	boolean	Start new game servers after the install
  updated_at required	string (date-time)
  variables required	object	Startup variable defaults for new game servers

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/packages/{id}

Replace a package's settings (not its game or owner)

Existing game servers keep their limits until their package is applied again (PATCH /services/{id}/package).

Request body application/json

Responses

• 200 OK - Package
  Fields

  Field	Type	Description
  allowed_datacenter_ids required	array of integer (int64)	Empty = any datacenter
  cpu_limit_percent required	integer (int32)	0 = unlimited; 100 = one core
  created_at required	string (date-time)
  description required	string
  disk_limit_bytes required	integer (int64)	File manager / SFTP / upload quota; 0 = unlimited
  enabled required	boolean	Disabled packages cannot be ordered; existing game servers keep running
  game_id required	string
  id required	integer (int64)
  memory_limit_bytes required	integer (int64)	0 = unlimited
  name required	string
  reseller_id required	integer (int64)	0 = a global package (every reseller may sell it)
  service_count required	integer (int64)
  slots_default required	integer (int32)
  slots_max required	integer (int32)
  slots_min required	integer (int32)
  start_on_create required	boolean	Start new game servers after the install
  updated_at required	string (date-time)
  variables required	object	Startup variable defaults for new game servers

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/packages/{id}

Delete a package no game server uses

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/resellers

Resellers with their quotas and what their customers use

Responses

• 200 OK - ResellersOutBody
  Fields

  Field	Type	Description
  items required	array of Reseller

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/resellers

Create a reseller

Its accounts are then created as users with role reseller and this reseller_id.

Request body application/json

Responses

• 201 Created - Reseller
  Fields

  Field	Type	Description
  accounts required	integer (int64)	Accounts of this reseller, including its own reseller accounts
  allowed_game_ids required	array of string	Games the reseller may sell; empty = all
  allowed_node_ids required	array of integer (int64)	Nodes its customers' game servers may be placed on; empty = all
  branding required	ResellerBranding
  created_at required	string (date-time)
  id required	integer (int64)
  name required	string
  quotas required	ResellerQuotas
  updated_at required	string (date-time)
  usage required	ResellerUsage

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/resellers/{id}

A reseller (administrators any; a reseller account its own, with quotas and usage)

Responses

• 200 OK - Reseller
  Fields

  Field	Type	Description
  accounts required	integer (int64)	Accounts of this reseller, including its own reseller accounts
  allowed_game_ids required	array of string	Games the reseller may sell; empty = all
  allowed_node_ids required	array of integer (int64)	Nodes its customers' game servers may be placed on; empty = all
  branding required	ResellerBranding
  created_at required	string (date-time)
  id required	integer (int64)
  name required	string
  quotas required	ResellerQuotas
  updated_at required	string (date-time)
  usage required	ResellerUsage

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/resellers/{id}

Replace a reseller's name, branding, quotas and allowed games / nodes

Lowering a quota below what is in use is allowed; it only stops further growth.

Request body application/json

Responses

• 200 OK - Reseller
  Fields

  Field	Type	Description
  accounts required	integer (int64)	Accounts of this reseller, including its own reseller accounts
  allowed_game_ids required	array of string	Games the reseller may sell; empty = all
  allowed_node_ids required	array of integer (int64)	Nodes its customers' game servers may be placed on; empty = all
  branding required	ResellerBranding
  created_at required	string (date-time)
  id required	integer (int64)
  name required	string
  quotas required	ResellerQuotas
  updated_at required	string (date-time)
  usage required	ResellerUsage

• 4xx/5xx error envelope {"error":{"code","message","details"}}

DELETE /api/v1/resellers/{id}

Delete a reseller that has no accounts left

Responses

• 204 No Content
• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/schedule-preview

The next runs of a cron expression (checks it too)

Responses

• 200 OK - ItemsTimeBody
  Fields

  Field	Type	Description
  items required	array of string (date-time)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

GET /api/v1/schedules

Global scheduled tasks

Responses

• 200 OK - ItemsTaskViewBody
  Fields

  Field	Type	Description
  items required	array of TaskView

• 4xx/5xx error envelope {"error":{"code","message","details"}}

POST /api/v1/schedules

Add a global scheduled task (every service matching the selector)

Request body application/json

Responses

• 201 Created - TaskView
  Fields

  Field	Type	Description
  action required	string
  created_at required	string (date-time)
  cron required	string
  enabled required	boolean
  id required	integer (int64)
  last_result	TaskResult
  last_run_at	string (date-time)
  name required	string
  next required	array of string (date-time)	The next three runs
  params required	TaskParams
  scope required	string: global, service
  selector	TaskSelector
  service_id	integer (int64)
  timezone required	string
  updated_at required	string (date-time)

• 4xx/5xx error envelope {"error":{"code","message","details"}}

PUT /api/v1/schedules/{id}

Change a global scheduled task

Request body application/json

Responses

• 200 OK - TaskView
  Fields

  Field	Type	Description
  action required	string
  created_at required	string (date-time)
  cron required	string
  enabled required	boolean
  id required	integer (int64)
  last_result	TaskResult
  last_run_at	string (date-time)
  name required	string
  next required	array of string (date-time)	The next three runs
  params required	TaskParams
  scope required	string: global, service
  selector	TaskSelector
  service_id	integer (int64)
  timezone required	string
  updated_at required	string (date-time)

• 4xx/5xx error envelope {"error":{"code","message","details"}}