# API reference Source : https://webgune.cloud/en-us/docs/reference-api · Mis à jour le 2026-10-27 # 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](/developers/api-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](/docs/cles-api)): ```bash curl https://api.webgune.cloud/api/v1/projects \ -H "Authorization: Bearer wgk_xxxxxxxxxxxx" ``` **Session cookie** (used by the dashboard itself): ```bash 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: ```json { "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 ```text 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 ``` ```bash 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](/developers/api-reference), not yet covered by the generated spec. ## Services ```text 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 ``` ```bash 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](/docs/bases-de-donnees), [Autoscaling](/docs/autoscaling), [Deployments & rollback](/docs/deploiements-rollback). ## Domains ```text 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](/developers/api-reference). ## Billing ```text 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 ```text 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 ```text 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](/docs/cles-api). ## Reseller Reserved for accounts that own an organization (`isOrgOwner`): ```text 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](/developers/api-reference). ## WebSocket: live logs ```javascript 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 ```javascript 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](/docs/cles-api)).