API-Überblick

Alles, was du im Dashboard tun kannst, geht auch über HTTP: Workspaces, Anwendungen, Deploys, Domains, Variablen, Mitglieder. Es ist dieselbe API, die das Dashboard selbst aufruft.

Basis-URL

https://cloady.com/api

Alle Anfragen und Antworten sind application/json. Sende bei jeder Anfrage mit Body den Header Content-Type: application/json mit.

Authentifizierung

Authentifiziere dich mit einem persönlichen API-Token. Übergib es als Bearer-Token:

Authorization: Bearer cldy_...

Ein Token handelt in deinem Namen: Es erreicht die Workspaces, zu denen du gehörst, mit deiner jeweiligen Rolle dort. Das Secret wird einmal angezeigt, beim Erstellen, und lässt sich danach nicht mehr abrufen – wenn du es verlierst, widerrufe das Token und erstelle ein neues.

Ein Token kann ein Ablaufdatum haben (never, 30d, 90d, 1y) und jederzeit widerrufen werden. Ein fehlendes, fehlerhaftes, abgelaufenes oder widerrufenes Token bekommt 401 unauthorized.

Ein Token kann außerdem an einen Workspace gebunden sein. Anfragen an jeden anderen Workspace liefern dann 403 forbidden, egal welche Rolle du dort hast.

Dein Konto braucht eine verifizierte Telefonnummer; ohne sie liefert jeder authentifizierte Endpunkt 403 phone_required. Verifiziere sie einmalig im Dashboard unter Account → Security.

Token erstellen

Im Dashboard: Account → API tokens (siehe den Dashboard-Leitfaden). Wähle einen Namen, einen Scope und ein Ablaufdatum – das Secret wird nur einmal angezeigt, kopiere es also sofort. Das Erstellen eines Tokens erfordert selbst den Scope full oder eine angemeldete Browser-Session.

Token-Scopes

Jedes Token wird mit genau einem Scope erstellt, der festlegt, was es darf:

• read – nur lesen. Workspaces, Anwendungen, Deploys und Logs auflisten und ansehen. Keine Änderungen.
• deploy – alles, was read kann, plus das, was ein Developer tut: deployen, neu deployen, starten, stoppen und neu starten, Domains und Variablen verwalten und eine Anwendung löschen (wobei ihre Daten endgültig gelöscht werden).
• full – ohne Einschränkung. Alles, was deploy kann, plus administrative Aktionen: Workspaces anlegen, Workspace-Einstellungen, Mitglieder, Integrationen und Abrechnung.

Wähle den engsten Scope, der deinen Anwendungsfall abdeckt – ein Deploy-Schlüssel für CI braucht deploy, nicht full.

Workspace-Rollen

Der Scope begrenzt das Token, deine Rolle im Workspace begrenzt die Anfrage. Workspace-Endpunkte verlangen eine Mindestrolle, hier von der niedrigsten zur höchsten:

• viewer – den Workspace und seine Anwendungen lesen.
• developer – Anwendungen deployen und betreiben: Deploy, Neustart, Logs, Shell, Datenbank, Domains und Variablen sowie das Löschen einer Anwendung.
• admin – Workspace-Einstellungen, Mitglieder, Integrationen und Single Sign-on verwalten.
• owner – alles, einschließlich Abrechnung und Löschen des Workspaces.

Eine Anfrage unterhalb der Mindestrolle des Endpunkts liefert 403 forbidden. Ein Workspace, in dem du kein Mitglied bist, liefert 404 not_found – eine Mitgliedschaft wird nie offengelegt.

Env + Region als Query-Parameter

Jede Anwendung läuft in einer Region und einer Umgebung – production, preview oder development –, und ihr Name ist innerhalb eines Workspaces und einer Umgebung eindeutig. Dashboard-URLs enthalten Region und Umgebung als Pfadsegmente, API-Anfragen dagegen als Query-Parameter:

?env=<production|preview|development>&region=<regionId>

• env ist standardmäßig production, wenn du es weglässt.
• region ist optional und selten nötig. Gib es nur an, wenn derselbe Name in mehr als einer Region existiert: Solche Anfragen liefern 400 region_required, und du wiederholst sie mit ?region=.

GET /api/workspaces/acme/apps/my-blog?env=production&region=usw1

Die Region-IDs liefert GET /api/regions. Jeder Workspace kann in jede davon deployen; die Region wählst du beim Deploy der Anwendung.

Anwendungen und Workspaces werden in diesen Pfaden über ihren Namen angesprochen, und auch die öffentliche Adresse einer Anwendung folgt ihrem Namen – eine Umbenennung ändert also sowohl die URL, die du aufrufst, als auch die URL, unter der deine App erreichbar ist. Passe alle Skripte an, die den alten Namen verwenden. Umbenennen bleibt trotzdem der sichere Weg: Wenn du eine Anwendung löschst, werden ihre Daten endgültig gelöscht.

Streaming-Endpunkte

App-Status, Metriken, Deploy-Fortschritt, Deploy-Logs und Ticket-Nachrichten werden als Server-Sent Events gestreamt. Sende Accept: text/event-stream für den Live-Stream; ohne diesen Header bekommst du den aktuellen Stand einmal als normales JSON – genau das, was ein Skript braucht. Service-Logs verhalten sich genauso und beantworten eine einfache Anfrage mit den letzten 200 Zeilen.

Fehlerformat

Fehler enthalten einen maschinenlesbaren code:

{ "error": { "code": "not_found", "message": "App my-blog not found" } }

Lies den Code aus body.error.code und verzweige anhand dieses Werts, nie nur anhand der Nachricht oder des Status. Validierungsfehler (bad_body) enthalten zusätzlich ein Array details, das die fehlerhaften Felder nennt.

Beispiel

Liste deine Workspaces auf:

curl https://cloady.com/api/workspaces \
  -H "Authorization: Bearer cldy_..."

{
  "workspaces": [ /* ... */ ]
}

Den vollständigen Katalog der Endpunkte – Pfade, Methoden, Parameter und Bodys – findest du auf den Endpunkt-Seiten in der Seitenleiste, beginnend mit listWorkspaces.