API reference
API Reference
The Webgune API is a REST API in JSON. Two surfaces exist:
https://api.webgune.cloud/api/*is used internally by the dashboard and is unversioned.https://api.webgune.cloud/api/v1/*is the public surface, stable, designed for third-party integrations (CI/CD, scripts, your own tooling). Use this one.
The interactive reference, generated from the OpenAPI spec (GET /api/v1/openapi.json), lists every endpoint with its exact request and response schemas.
Authentication
Two methods, your choice:
API key, recommended for a script or third-party integration (creation and scopes: API keys):
curl https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx"
Session cookie (used by the dashboard itself):
POST /api/auth/login
Content-Type: application/json
{ "email": "you@example.com", "password": "..." }
The response sets the sid cookie; it must be sent on every subsequent call (credentials: "include" on the fetch side). A session is not limited by scopes, since it represents your logged-in account.
Errors
Every error response follows the same format:
{ "error": "Human-readable message", "code": "optional_machine_code" }
Standard HTTP codes: 400 invalid payload, 401 missing/invalid authentication, 403 insufficient scope or role, 404 resource not found or inaccessible (the two are not distinguished, so as not to reveal the existence of a resource to someone without access to it), 409 conflict, 429 rate limit exceeded.
Rate limit
Each API key has its own limit (60 requests/minute by default, configurable up to 6000 at creation). Every response carries the headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1732549800
A session cookie is never limited by this mechanism.
Projects
GET /api/v1/projects list your projects (owner or member)
POST /api/v1/projects create a project
GET /api/v1/projects/:id project detail (services, canvas)
PUT /api/v1/projects/:id rename / edit the description
DELETE /api/v1/projects/:id delete a project
curl -X POST https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "name": "my-project" }'
Managing members, the canvas (positions/links), and project-level domain redirections: see the interactive reference, not yet covered by the generated spec.
Services
GET /api/v1/services/project/:projectId services of a project
GET /api/v1/services/:id service detail (live K8s status)
POST /api/v1/services create a service (GitHub, upload, Docker, database)
DELETE /api/v1/services/:id delete a service
POST /api/v1/services/:id/redeploy redeploy
GET /api/v1/services/:id/logs recent runtime logs
GET /api/v1/services/:id/metrics instant CPU / memory
GET /api/v1/services/:id/env environment variables
PUT /api/v1/services/:id/env replace variables (restarts the service)
PUT /api/v1/services/:id/scale set the number of replicas
GET /api/v1/services/:id/deployments deployment history
POST /api/v1/services/:id/deployments/:deploymentId/rollback revert to a previous deployment
curl -X POST https://api.webgune.cloud/api/v1/services/svc_123/redeploy \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx"
Per-branch previews, database exposure, volumes, custom ports, autoscaling, Discord bots: existing endpoints, not yet in the generated OpenAPI spec. See Databases, Autoscaling, Deployments & rollback.
Domains
POST /api/v1/domains/check check a domain's availability
GET /api/v1/domains list your domains
POST /api/v1/domains/register register an available domain
GET /api/v1/domains/:id domain detail
DELETE /api/v1/domains/:id delete a domain
GET /api/v1/domains/:id/dns list DNS records
POST /api/v1/domains/:id/dns add a DNS record
DELETE /api/v1/domains/:id/dns/:idx delete a DNS record
Nameservers, auto-renewal, manual renewal: see the interactive reference.
Billing
GET /api/v1/billing/plans list available plans
GET /api/v1/billing/subscription active subscription (account, or ?projectId= for a dedicated project)
GET /api/v1/billing/invoices list your invoices
Subscribing, payment, and webhooks remain flows internal to the dashboard (Mollie), not exposed as third-party API operations.
Dashboard
GET /api/v1/dashboard/stats aggregated stats (services, CPU/memory vs plan limits)
GET /api/v1/dashboard/deployment-history deployment history, last 30 days
API Keys
GET /api/v1/api-keys list your keys
POST /api/v1/api-keys create a key
DELETE /api/v1/api-keys/:id revoke a key
GET /api/v1/api-keys/:id/audit-log audit log (last 100 requests)
Details on scopes, rate limits, and the X-Act-As-User-Id header (resellers): see API keys.
Reseller
Reserved for accounts that own an organization (isOrgOwner):
GET /api/v1/reseller/organization my organization
GET /api/v1/reseller/sub-clients list my sub-clients
GET /api/v1/reseller/overview overview (counters per sub-client)
Creating/deleting sub-clients and reseller billing: see the interactive reference.
WebSocket: live logs
const ws = new WebSocket("wss://api.webgune.cloud/ws/services/:id/logs");
ws.onmessage = (e) => console.log(e.data); // one log line per message
WebSocket: live metrics
const ws = new WebSocket("wss://api.webgune.cloud/ws/projects/:id/metrics");
ws.onmessage = (e) => {
const metrics = JSON.parse(e.data);
// { "service-id": { cpu: 1.2, memory: 256 }, ... }
};
WebSockets require a browser session: an API key cannot connect to them (see API keys).