Appearance

API Reference ​

Overview ​

The Shardlyn API is a RESTful HTTP API with WebSocket support for real-time features.

Base URLhttps://api.shardlyn.com
Content-Typeapplication/json
ProtocolHTTPS (TLS 1.2+)

See Also

Authentication ​

JWT Authentication ​

Most endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer <access_token>

Access tokens expire after 15 minutes. Use the refresh endpoint to get a new one.

API Token Authentication ​

For programmatic access, use an API token (created in Settings > API Tokens):

Authorization: Bearer shardlyn_api_...

Agent Authentication ​

Agents use a separate token via the X-Agent-Token header. This is internal and not intended for user use.

Auth Badges ​

Throughout this reference, endpoints are marked with:

BadgeMeaning
🔒 JWTRequires JWT access token
🔑 API TokenAccepts API token authentication
🌐 PublicNo authentication required
👑 AdminRequires admin role

Auth Endpoints ​

Authentication, registration, OAuth, and password reset.

MethodPathDescriptionAuth
POST/v1/auth/loginAuthenticate user🌐 Public
POST/v1/auth/registerRegister new user🌐 Public
POST/v1/auth/refreshRefresh access token🌐 Public
POST/v1/auth/forgot-passwordRequest password reset🌐 Public
POST/v1/auth/reset-passwordReset password with token🌐 Public
GET/v1/auth/githubRedirect to GitHub OAuth🌐 Public
GET/v1/auth/github/callbackGitHub OAuth callback🌐 Public
GET/v1/auth/bootstrap/statusCheck if bootstrap needed🌐 Public
POST/v1/auth/bootstrapCreate initial admin user🌐 Public

Login ​

POST /v1/auth/login — Authenticate and receive tokens 🌐

Request / Response

Request:

json
{
  "email": "[email protected]",
  "password": "your-password"
}

Response: 200 OK

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 900,
  "token_type": "Bearer"
}

If MFA is enabled, returns mfa_required: true with a challenge token. Submit the TOTP code via /v1/auth/mfa/challenge.

Register ​

POST /v1/auth/register — Create a new account 🌐

Request / Response

Request:

json
{
  "email": "[email protected]",
  "password": "secure-password"
}

Response: 201 Created

Refresh Token ​

POST /v1/auth/refresh — Get a new access token 🌐

Request / Response

Request:

json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response: 200 OK — Same format as login response.

Forgot / Reset Password ​

POST /v1/auth/forgot-password — Request a password reset email 🌐

json
{ "email": "[email protected]" }

POST /v1/auth/reset-password — Reset password using token 🌐

json
{ "token": "reset-token", "new_password": "new-password" }

GitHub OAuth ​

GET /v1/auth/github — Redirects to GitHub for OAuth authorization 🌐

GET /v1/auth/github/callback — Handles the OAuth callback from GitHub 🌐

Bootstrap (First Setup) ​

GET /v1/auth/bootstrap/status — Check if the platform needs initial setup 🌐

POST /v1/auth/bootstrap — Create the initial admin user 🌐

MFA Endpoints ​

Multi-factor authentication enrollment, verification, and challenge.

MethodPathDescriptionAuth
GET/v1/auth/mfa/statusCheck MFA status🔒 JWT
POST/v1/auth/mfa/enrollStart MFA enrollment🔒 JWT
POST/v1/auth/mfa/verifyVerify TOTP enrollment🔒 JWT
POST/v1/auth/mfa/disableDisable MFA🔒 JWT
POST/v1/auth/mfa/challengeSubmit TOTP during login🌐 Public

MFA Status ​

GET /v1/auth/mfa/status — Check if MFA is enabled 🔒

Response:

json
{ "enabled": false }

Enroll ​

POST /v1/auth/mfa/enroll — Begin MFA enrollment 🔒

Response
json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_uri": "otpauth://totp/Shardlyn:[email protected]?..."
}

Use the otpauth_uri to generate a QR code for authenticator apps.

Verify / Disable / Challenge ​

POST /v1/auth/mfa/verify — Confirm enrollment with a TOTP code 🔒

POST /v1/auth/mfa/disable — Disable MFA (requires TOTP code) 🔒

POST /v1/auth/mfa/challenge — Submit TOTP code during login 🌐

Rate Limit

MFA endpoints are rate limited to 5 attempts per minute.

User Endpoints ​

User profile and management.

MethodPathDescriptionAuth
GET/v1/users/meGet current user🔒 JWT
POST/v1/users/me/passwordUpdate password🔒 JWT
GET/v1/usersList users👑 Admin
POST/v1/usersCreate user👑 Admin
GET/v1/users/{id}Get user👑 Admin
DELETE/v1/users/{id}Delete user👑 Admin

API Token Endpoints ​

Programmatic access tokens for CI/CD and automation.

MethodPathDescriptionAuth
GET/v1/api-tokensList tokens🔒 JWT
POST/v1/api-tokensCreate token🔒 JWT
DELETE/v1/api-tokens/{id}Delete token🔒 JWT

Create Token ​

POST /v1/api-tokens — Create a new API token 🔒

Request / Response

Request:

json
{
  "name": "github-actions",
  "expires_in": 2592000
}

Response: 201 Created

json
{
  "id": "uuid",
  "name": "github-actions",
  "token": "shardlyn_api_abc123...",
  "expires_at": "2026-03-01T00:00:00Z",
  "created_at": "2026-01-31T00:00:00Z"
}

WARNING

The token value is only returned once at creation. Store it securely.

Node Endpoints ​

Node registration, lifecycle management, power control, firewall, inventory, and monitoring.

CRUD ​

MethodPathDescriptionAuth
GET/v1/nodesList nodes🔒 JWT
GET/v1/nodes/{id}Get node details🔒 JWT
PUT/v1/nodes/{id}Update node🔒 JWT
DELETE/v1/nodes/{id}Delete node🔒 JWT
POST/v1/nodes/register-tokenCreate registration token🔒 JWT

Lifecycle ​

MethodPathDescriptionAuth
POST/v1/nodes/{id}/cordonDisable scheduling🔒 JWT
POST/v1/nodes/{id}/uncordonRe-enable scheduling🔒 JWT
POST/v1/nodes/{id}/drainEvict all instances🔒 JWT
POST/v1/nodes/{id}/migrateMigrate instances to another node🔒 JWT

Power Management (Provisioned Nodes) ​

MethodPathDescriptionAuth
POST/v1/nodes/{id}/power/startStart server🔒 JWT
POST/v1/nodes/{id}/power/stopStop server🔒 JWT
POST/v1/nodes/{id}/power/rebootReboot server🔒 JWT
GET/v1/nodes/{id}/power/statusGet power status🔒 JWT
POST/v1/nodes/{id}/resizeResize server🔒 JWT

Firewall (Provisioned Nodes) ​

MethodPathDescriptionAuth
GET/v1/nodes/{id}/firewall/rulesList rules🔒 JWT
POST/v1/nodes/{id}/firewall/rulesAdd rule🔒 JWT
DELETE/v1/nodes/{id}/firewall/rulesRemove rule🔒 JWT

Inventory ​

MethodPathDescriptionAuth
GET/v1/nodes/{id}/inventoryFull inventory🔒 JWT
GET/v1/nodes/{id}/inventory/systemSystem info🔒 JWT
GET/v1/nodes/{id}/inventory/networkNetwork interfaces🔒 JWT
GET/v1/nodes/{id}/inventory/disksDisk info🔒 JWT
GET/v1/nodes/{id}/inventory/usersSystem users🔒 JWT
GET/v1/nodes/{id}/inventory/processesRunning processes🔒 JWT
GET/v1/nodes/{id}/inventory/containersDocker containers🔒 JWT

Monitoring ​

MethodPathDescriptionAuth
GET/v1/nodes/{id}/metrics/historyMetrics history🔒 JWT
GET/v1/nodes/{id}/terminalWebSocket terminal🔒 JWT
GET/v1/nodes/{id}/sshWebSocket SSH (uses CA)🔒 JWT

Container Management (on Node) ​

MethodPathDescriptionAuth
GET/v1/nodes/{id}/containers/{containerId}/logsStream logs🔒 JWT
POST/v1/nodes/{id}/containers/{containerId}/startStart container🔒 JWT
POST/v1/nodes/{id}/containers/{containerId}/stopStop container🔒 JWT
POST/v1/nodes/{id}/containers/{containerId}/restartRestart container🔒 JWT
POST/v1/nodes/{id}/containers/{containerId}/killKill container🔒 JWT
POST/v1/nodes/{id}/processes/{pid}/killKill process🔒 JWT

Workload Endpoints ​

Workload definitions, templates, and import/export.

MethodPathDescriptionAuth
GET/v1/workloadsList workloads🔒 JWT
POST/v1/workloadsCreate workload🔒 JWT
GET/v1/workloads/{id}Get workload🔒 JWT
PUT/v1/workloads/{id}Update workload🔒 JWT
DELETE/v1/workloads/{id}Delete workload🔒 JWT
GET/v1/workloads/{id}/exportExport workload🔒 JWT
POST/v1/workloads/from-templateCreate from workload template🔒 JWT
POST/v1/workloads/import-eggImport Pterodactyl egg🔒 JWT

Instance Endpoints ​

Instance lifecycle, files, console, backups, and git deploy.

CRUD & Lifecycle ​

MethodPathDescriptionAuth
GET/v1/instancesList instances🔒 JWT
POST/v1/instancesCreate instance🔒 JWT
GET/v1/instances/{id}Get instance🔒 JWT
PUT/v1/instances/{id}Update instance🔒 JWT
DELETE/v1/instances/{id}Delete instance🔒 JWT
POST/v1/instances/{id}/startStart🔒 JWT
POST/v1/instances/{id}/stopStop🔒 JWT
POST/v1/instances/{id}/restartRestart🔒 JWT
POST/v1/instances/{id}/killKill (SIGKILL)🔒 JWT

Stats & Monitoring ​

MethodPathDescriptionAuth
GET/v1/instances/{id}/statsReal-time stats🔒 JWT
GET/v1/instances/{id}/metrics/historyMetrics history🔒 JWT

File Management ​

MethodPathDescriptionAuth
GET/v1/instances/{id}/filesList files🔒 JWT
GET/v1/instances/{id}/files/contentRead file🔒 JWT
PUT/v1/instances/{id}/files/contentWrite file🔒 JWT
DELETE/v1/instances/{id}/filesDelete file🔒 JWT
GET/v1/instances/{id}/files/downloadDownload file🔒 JWT
POST/v1/instances/{id}/files/uploadUpload (multipart)🔒 JWT
POST/v1/instances/{id}/files/tusUpload (TUS resumable)🔒 JWT
POST/v1/instances/{id}/files/mkdirCreate directory🔒 JWT
POST/v1/instances/{id}/files/moveMove/rename🔒 JWT
GET/v1/instances/{id}/files/download-zipDownload directory as zip🔒 JWT

Console & Logs ​

MethodPathDescriptionAuth
GET/v1/instances/{id}/logsWebSocket: live logs🔒 JWT
GET/v1/instances/{id}/consoleWebSocket: interactive console🔒 JWT
GET/v1/instances/{id}/install-logsInstall/startup logs🔒 JWT
GET/v1/instances/{id}/logs/historyLog history🔒 JWT
GET/v1/instances/{id}/logs/downloadDownload logs🔒 JWT
DELETE/v1/instances/{id}/logs/clearClear logs👑 Admin

Backups ​

MethodPathDescriptionAuth
GET/v1/instances/{id}/backupsList backups🔒 JWT
POST/v1/instances/{id}/backupsCreate backup🔒 JWT
GET/v1/instances/{id}/backups/{bid}/downloadDownload backup🔒 JWT
POST/v1/instances/{id}/backups/{bid}/restoreRestore backup🔒 JWT
DELETE/v1/instances/{id}/backups/{bid}Delete backup🔒 JWT

Git Deploy ​

MethodPathDescriptionAuth
GET/v1/instances/{id}/gitGet git config🔒 JWT
PUT/v1/instances/{id}/gitCreate/update config🔒 JWT
DELETE/v1/instances/{id}/gitDelete config🔒 JWT
POST/v1/instances/{id}/git/syncTrigger sync🔒 JWT
GET/v1/instances/{id}/git/statusSync status🔒 JWT
GET/v1/instances/{id}/git/historySync history🔒 JWT

Provisioning Endpoints ​

Cloud server provisioning with Terraform.

MethodPathDescriptionAuth
GET/v1/provisionList provision requests🔒 JWT
POST/v1/provisionCreate request🔒 JWT
GET/v1/provision/{id}Get request🔒 JWT
POST/v1/provision/{id}/planGenerate Terraform plan🔒 JWT
POST/v1/provision/{id}/applyApply plan🔒 JWT
DELETE/v1/provision/{id}Delete/destroy🔒 JWT
GET/v1/provision/providersList available providers🔒 JWT

Create Provision Request ​

POST /v1/provision — Provision a new cloud server 🔒

Request / Response

Request:

json
{
  "provider": "hetzner",
  "region": "fsn1",
  "instance_type": "cx31",
  "name": "game-node-1"
}

Response: 201 Created — Returns the provision request with status pending.

Planner Endpoints ​

Capacity planning and workload template recommendations.

MethodPathDescriptionAuth
POST/v1/planner/recommendGeneral recommendations🔒 JWT
POST/v1/planner/suggest-fitFind best node for workload🔒 JWT
GET/v1/planner/pricingProvider pricing data🔒 JWT
GET/v1/planner/templatesSupported workload templates🔒 JWT
POST/v1/planner/recommend-for-templateRecommendation for specific template🔒 JWT

Credentials Endpoints ​

Cloud provider credential management.

MethodPathDescriptionAuth
GET/v1/credentialsList credentials🔒 JWT
POST/v1/credentialsCreate credential🔒 JWT
GET/v1/credentials/{id}Get credential🔒 JWT
PUT/v1/credentials/{id}Update credential🔒 JWT
DELETE/v1/credentials/{id}Delete credential🔒 JWT
POST/v1/credentials/{id}/defaultSet as default🔒 JWT
POST/v1/credentials/{id}/verifyVerify connectivity🔒 JWT

Supported providers: aws, gcp, hetzner, oci, cloudflare, steam

DNS Endpoints ​

DNS zone and record management via cloud provider APIs.

MethodPathDescriptionAuth
GET/v1/dns/zonesList zones🔒 JWT
GET/v1/dns/zones/{zoneId}/recordsList zone records🔒 JWT
GET/v1/dns/recordsList all records🔒 JWT
POST/v1/dns/recordsCreate record🔒 JWT
PUT/v1/dns/records/{id}Update record🔒 JWT
DELETE/v1/dns/records/{id}Delete record🔒 JWT
GET/v1/dns/auto-configGet auto-DNS config🔒 JWT
PUT/v1/dns/auto-configUpdate auto-DNS config🔒 JWT

Create DNS Record ​

POST /v1/dns/records — Create a DNS record 🔒

Request / Response

Request:

json
{
  "credential_id": "uuid",
  "zone_id": "zone-id",
  "type": "A",
  "name": "mc",
  "content": "203.0.113.10",
  "ttl": 300,
  "node_id": "optional-uuid"
}

Response: 201 Created

SSH Certificate Authority Endpoints ​

SSH CA key management and certificate signing.

MethodPathDescriptionAuth
GET/v1/ssh/ca-public-keyGet CA public key🌐 Public
POST/v1/ssh/certificateGenerate signed certificate🔒 JWT
GET/v1/ssh/certificatesList certificates🔒 JWT
GET/v1/ssh/certificates/{id}Get certificate🔒 JWT
POST/v1/ssh/certificates/{id}/revokeRevoke certificate🔒 JWT
GET/v1/ssh/ca/keysList CA keys👑 Admin
POST/v1/ssh/ca/keysGenerate CA key👑 Admin
POST/v1/ssh/ca/keys/rotateRotate CA key👑 Admin

Generate Certificate ​

POST /v1/ssh/certificate — Generate a signed SSH certificate 🔒

Request / Response

Request:

json
{
  "public_key": "ssh-ed25519 AAAA...",
  "principals": ["root", "shardlyn"],
  "validity_hours": 8,
  "node_id": "optional-uuid"
}

Response: 200 OK

json
{
  "certificate": "[email protected] ...",
  "serial_number": "123456",
  "valid_after": "2026-01-31T12:00:00Z",
  "valid_before": "2026-01-31T20:00:00Z",
  "principals": ["root", "shardlyn"]
}

Alert Endpoints ​

Alert management and alert rule configuration.

Alerts ​

MethodPathDescriptionAuth
GET/v1/alertsList alerts🔒 JWT
GET/v1/alerts/unread-countUnread count🔒 JWT
GET/v1/alerts/{id}Get alert🔒 JWT
POST/v1/alerts/{id}/ackAcknowledge alert🔒 JWT

Alert Rules ​

MethodPathDescriptionAuth
GET/v1/alerts/rulesList rules🔒 JWT
POST/v1/alerts/rulesCreate rule🔒 JWT
GET/v1/alerts/rules/{id}Get rule🔒 JWT
PUT/v1/alerts/rules/{id}Update rule🔒 JWT
DELETE/v1/alerts/rules/{id}Delete rule🔒 JWT

Create Alert Rule ​

POST /v1/alerts/rules — Create an alert rule 🔒

Request / Response

Request:

json
{
  "name": "High CPU",
  "target_type": "node",
  "target_id": "uuid",
  "metric": "cpu_usage",
  "operator": "gt",
  "threshold": 90,
  "duration_seconds": 300,
  "severity": "warn",
  "notify_in_app": true,
  "notify_email": true,
  "cooldown_seconds": 600
}

Response: 201 Created

Integration Endpoints ​

Third-party integrations (Discord, Slack, etc.).

MethodPathDescriptionAuth
GET/v1/integrationsList integrations🔒 JWT
GET/v1/integrations/typesAvailable types🔒 JWT
POST/v1/integrationsCreate integration🔒 JWT
GET/v1/integrations/{id}Get integration🔒 JWT
PUT/v1/integrations/{id}Update integration🔒 JWT
DELETE/v1/integrations/{id}Delete integration🔒 JWT
POST/v1/integrations/{id}/testTest integration🔒 JWT

Organization Endpoints ​

Organization management, member roles, and invitations.

Organizations ​

MethodPathDescriptionAuth
GET/v1/organizationsList organizations🔒 JWT
POST/v1/organizationsCreate organization🔒 JWT
GET/v1/organizations/{orgId}Get organization🔒 JWT
PUT/v1/organizations/{orgId}Update organization🔒 JWT
DELETE/v1/organizations/{orgId}Delete organization🔒 JWT

Members ​

MethodPathDescriptionAuth
GET/v1/organizations/{orgId}/membersList members🔒 JWT
POST/v1/organizations/{orgId}/members/inviteInvite member🔒 JWT
DELETE/v1/organizations/{orgId}/members/{userId}Remove member🔒 JWT
PUT/v1/organizations/{orgId}/members/{userId}/roleUpdate role🔒 JWT
GET/v1/organizations/{orgId}/members/{userId}/permissionsGet permissions🔒 JWT
POST/v1/organizations/{orgId}/members/{userId}/permissionsSet permission🔒 JWT
DELETE/v1/organizations/{orgId}/members/{userId}/permissions/{key}Remove permission🔒 JWT

Invites ​

MethodPathDescriptionAuth
GET/v1/organizations/{orgId}/invitesList invites🔒 JWT
DELETE/v1/organizations/{orgId}/invites/{inviteId}Delete invite🔒 JWT
POST/v1/invites/{token}/acceptAccept invite🔒 JWT

Billing Endpoints ​

Plans, subscriptions, usage tracking, and cloud cost management.

MethodPathDescriptionAuth
GET/v1/billing/plansList plans🔒 JWT
GET/v1/billing/org/subscriptionCurrent subscription🔒 JWT
GET/v1/billing/org/usageResource usage🔒 JWT
GET/v1/billing/org/limitsPlan limits🔒 JWT
POST/v1/billing/org/subscribeSubscribe to plan🔒 JWT
POST/v1/billing/org/cancelCancel subscription🔒 JWT
POST/v1/billing/org/portalStripe billing portal🔒 JWT
GET/v1/billing/org/cloud-costsCloud cost tracking🔒 JWT
GET/v1/billing/org/cloud-costs/forecastCost forecast🔒 JWT
POST/v1/billing/org/cloud-costs/refreshRefresh costs🔒 JWT

Backup Configuration Endpoints ​

S3-compatible backup storage configuration.

MethodPathDescriptionAuth
GET/v1/backup-configActive config🔒 JWT
POST/v1/backup-configCreate config🔒 JWT
GET/v1/backup-config/listList all configs🔒 JWT
GET/v1/backup-config/{id}Get config🔒 JWT
PUT/v1/backup-config/{id}Update config🔒 JWT
DELETE/v1/backup-config/{id}Delete config🔒 JWT
POST/v1/backup-config/{id}/activateSet active🔒 JWT
GET/v1/backup-config/s3-bucketsList S3 buckets🔒 JWT
POST/v1/backup-config/s3-bucketsCreate S3 bucket🔒 JWT

Deploy (One-Click) Endpoints ​

One-click deployments and workload templates (including game server templates).

MethodPathDescriptionAuth
GET/v1/deployList deployments🔒 JWT
GET/v1/deploy/{id}Get deployment🔒 JWT
POST/v1/deployCreate deployment🔒 JWT
GET/v1/templatesList deployment templates🔒 JWT
GET/v1/templates/{category}List templates by category🔒 JWT

Migration Endpoints ​

Instance migration between nodes.

MethodPathDescriptionAuth
GET/v1/migrationsList migrations🔒 JWT
GET/v1/migrations/{id}Get migration🔒 JWT
POST/v1/migrations/{id}/cancelCancel migration🔒 JWT

Webhook Endpoints (No Auth) ​

External webhook receivers using signature verification.

MethodPathDescriptionAuth
POST/v1/webhooks/githubGitHub push events🌐 X-Hub-Signature-256
POST/v1/webhooks/gitlabGitLab push events🌐 X-Gitlab-Token
POST/v1/webhooks/stripeStripe events🌐 Stripe-Signature

Webhook Token Endpoints ​

Manage webhook authentication tokens.

MethodPathDescriptionAuth
GET/v1/webhook-tokensList tokens🔒 JWT
POST/v1/webhook-tokensCreate token🔒 JWT
DELETE/v1/webhook-tokens/{id}Delete token🔒 JWT

Settings Endpoints ​

Platform settings and SSH key management.

MethodPathDescriptionAuth
GET/v1/settingsGet settings🔒 JWT
PUT/v1/settingsUpdate settings🔒 JWT
POST/v1/settings/ssh-keysAdd SSH key🔒 JWT
DELETE/v1/settings/ssh-keys/{name}Remove SSH key🔒 JWT
POST/v1/settings/ssh-keys/{name}/defaultSet default key🔒 JWT

Tunnel Endpoints (Admin) ​

Tunnel statistics and agent connections.

MethodPathDescriptionAuth
GET/v1/tunnel/statsTunnel statistics👑 Admin
GET/v1/tunnel/agentsConnected agents👑 Admin

Permissions Endpoint ​

MethodPathDescriptionAuth
GET/v1/permissionsList all available permissions🔒 JWT

Admin Endpoints ​

Platform administration and audit logging.

Platform Administration ​

MethodPathDescriptionAuth
GET/v1/admin/metricsMetrics dashboard👑 Admin
GET/v1/admin/organizationsList all organizations👑 Admin
GET/v1/admin/organizations/{id}Get organization👑 Admin
GET/v1/admin/plansList plans👑 Admin
POST/v1/admin/plansCreate plan👑 Admin
PUT/v1/admin/plans/{id}Update plan👑 Admin
DELETE/v1/admin/plans/{id}Delete plan👑 Admin
GET/v1/admin/subscriptionsList subscriptions👑 Admin
PUT/v1/admin/subscriptions/{id}Update subscription👑 Admin
GET/v1/admin/audit-logsList audit logs👑 Admin
GET/v1/admin/audit-logs/exportExport audit logs👑 Admin
GET/v1/admin/usersList users👑 Admin
POST/v1/admin/users/{id}/suspendSuspend user👑 Admin
POST/v1/admin/users/{id}/unsuspendUnsuspend user👑 Admin

Admin Settings ​

MethodPathDescriptionAuth
GET/v1/admin/settings/logsGet log settings👑 Admin
PUT/v1/admin/settings/logsUpdate log settings👑 Admin

Support Endpoints ​

MethodPathDescriptionAuth
POST/v1/support/messagesSend support message🔒 JWT
GET/v1/support/helpscout/signatureHelpScout widget signature🔒 JWT

System Endpoints ​

MethodPathDescriptionAuth
GET/v1/system/backup-configSystem backup configuration👑 Admin

Health Endpoints ​

MethodPathDescriptionAuth
GET/healthBasic health check (liveness)🌐 Public
GET/health/liveLiveness probe🌐 Public
GET/health/readyReadiness probe🌐 Public
GET/health/detailedDetailed health report🌐 Public
GET/readyReadiness probe (alias)🌐 Public

Readiness checks database connectivity and, when enabled, cache connectivity.

Pterodactyl Import Endpoints ​

Import servers from an existing Pterodactyl panel.

MethodPathDescriptionAuth
POST/v1/pterodactyl/validateValidate Pterodactyl connection🔒 JWT
POST/v1/pterodactyl/serversList Pterodactyl servers🔒 JWT
POST/v1/pterodactyl/importImport server🔒 JWT

Error Responses ​

All errors follow this format:

json
{
  "error": "descriptive error message"
}
CodeMeaning
400Bad Request — invalid input
401Unauthorized — missing or invalid token
403Forbidden — insufficient permissions
404Not Found
409Conflict — resource already exists
429Too Many Requests — rate limit exceeded
500Internal Server Error

Rate Limiting ​

Rate limiting protects the API from abuse:

ScopeLimit
General APIConfigurable requests per second with burst allowance
LoginStricter limits with account lockout after repeated failures
MFA5 attempts per minute
WebSocketConnection limits for logs and console streams

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706745600

Built for teams that want control of their own infrastructure.

Copyright © 2026 Shardlyn