REST-API: aus CI deployen und Server automatisieren

Mit der API von Vimonto Deploy arbeiten Skripte und CI-Pipelines über HTTPS und JSON mit deinen Organisationen: Server und Sites auflisten, einen Deploy starten und verfolgen, Datenbanken anlegen und entfernen, Backups und Rezepte ausführen. Jede Anfrage wird mit einem persönlichen API-Token authentifiziert, den du in deinem Account erstellst.

Ein Token handelt als du. Er kann nur, was deine Rolle erlaubt, nur auf den Servern, auf die du Zugriff hast, und nur innerhalb der Bereiche, die du ihm gegeben hast.

Einen API-Token erstellen#

1. Öffne das Account-Menü oben rechts und wähle Account-Einstellungen → API-Tokens.
2. Klicke auf Neuer Token.
3. Gib einen Name ein, der sagt, wo er verwendet wird, etwa „GitHub Actions“.
4. Hake unter Bereiche an, was der Token darf (siehe unten).
5. Wähle unter Läuft ab In 30 Tagen, In 90 Tagen (Standard), In 365 Tagen oder Nie.
6. Klicke auf Token erstellen.

Der Token wird einmal angezeigt, unter Dein neuer Token. Klicke auf Kopieren und bewahre ihn an einem sicheren Ort auf, etwa in den Secrets deiner CI; Vimonto Deploy speichert nur einen Hash davon und kann ihn nicht noch einmal anzeigen. Ein Token sieht aus wie 12|, gefolgt von einer langen Folge aus Buchstaben und Ziffern.

Die Liste zeigt für jeden Token den Namen, wann er zuletzt verwendet wurde, wann er abläuft und seine Bereiche. Klicke auf Widerrufen, um einen Token zu löschen: Skripte und Pipelines, die ihn verwenden, funktionieren sofort nicht mehr. Wenn du deinen Account löschst, werden alle deine Tokens widerrufen.

Bereiche#

Ein Token mit nur Deploy kann die Site nachschlagen, die er deployt (siehe Eine Site finden), aber keine Server oder Sites auflisten: Gib einer CI-Pipeline nur diesen Bereich und nutze Lesen oder Schreiben für Skripte, die mehr brauchen.

Der Bereich ist die erste Prüfung. Deine Rolle ist die zweite: Einen Deploy starten, Datenbanken ändern und Backups oder Rezepte ausführen erfordert die Rolle Owner, Administrator, Manager oder Developer. Der Token eines Betrachters kann lesen, aber jede Änderung wird mit 403 abgelehnt.

Basis-URL und Authentifizierung#

Alle Endpunkte liegen unter /api/v1 auf der Adresse, unter der du Vimonto Deploy nutzt. In den Beispielen unten ist das https://deploy.example.com/api/v1; ersetze deploy.example.com durch deine eigene Adresse.

Sende den Token als Bearer-Token im Header Authorization und fordere JSON an:

curl https://deploy.example.com/api/v1/user \
  -H "Authorization: Bearer $VIMONTO_TOKEN" \
  -H "Accept: application/json"

Nur Tokens öffnen die API: Die Anmeldung in der App in deinem Browser reicht nicht. Anfrage-Bodys sind JSON (Content-Type: application/json). Datumsangaben sind ISO 8601 mit Zeitzone. Meldungen in Antworten, etwa Fehler, sind in der Sprache, die in deinem Konto eingestellt ist; hast du keine gewählt, in der Sprache aus dem Accept-Language-Header der Anfrage (Englisch, Niederländisch, Deutsch, Französisch oder Italienisch), sonst auf Englisch.

Organisationen, Server und Sites in der URL#

Endpunkte einer Organisation beginnen mit /orgs/{organization}, wobei {organization} der Slug der Organisation ist: der erste Teil ihrer Adresse in der App (https://deploy.example.com/acme/… hat den Slug acme). GET /user listet die Slugs auf, die dein Token erreicht.

Server, Sites und alles darunter werden über ihre numerische ID angesprochen, dieselbe Zahl wie in der Adresse der App: /acme/servers/12/sites/34 in der App ist /orgs/acme/servers/12/sites/34 in der API. Ein Kind muss zu seinem Elternteil gehören: Site 34 auf Server 12 funktioniert nur, wenn die Site auf diesem Server liegt, sonst antwortet die API mit 404.

Eine Organisation, in der du kein Mitglied bist, und ein Server, auf den deine Teams dir keinen Zugriff geben, antworten mit 404, nicht mit 403.

Endpunkte#

Ein Token braucht einen der aufgeführten Bereiche. Die Pfade unten lassen das Präfix https://deploy.example.com/api/v1 weg.

Den Benutzer des Tokens abrufen#

GET /user gibt zurück, wem der Token gehört, den Namen und die Bereiche des Tokens und die Organisationen, die er erreicht, mit deiner Rolle in jeder davon. Jeder Bereich darf ihn aufrufen, daher ist er ein guter erster Test für einen Token.

curl https://deploy.example.com/api/v1/user \
  -H "Authorization: Bearer $VIMONTO_TOKEN" -H "Accept: application/json"

{
  "data": {
    "id": 7,
    "name": "Sam de Vries",
    "email": "sam@example.com",
    "token": {
      "name": "GitHub Actions",
      "scopes": ["deploy"]
    },
    "organizations": [
      { "slug": "acme", "name": "Acme", "role": "developer" }
    ]
  }
}

Server auflisten#

GET /orgs/{organization}/servers gibt die Server der Organisation zurück, auf die du Zugriff hast, nach Namen sortiert. GET /orgs/{organization}/servers/{server} gibt einen Server zurück.

curl https://deploy.example.com/api/v1/orgs/acme/servers \
  -H "Authorization: Bearer $VIMONTO_TOKEN" -H "Accept: application/json"

{
  "data": [
    {
      "id": 12,
      "name": "web-1",
      "type": "app",
      "status": "active",
      "provider": "hetzner",
      "region": "fsn1",
      "size": "cx32",
      "ip_address": "203.0.113.10",
      "private_ip_address": "10.0.0.2",
      "ssh_port": 22,
      "user": "vimonto",
      "php_version": "8.4",
      "database": "mysql-8.4",
      "ubuntu_version": "24.04",
      "timezone": "UTC",
      "tags": ["production"],
      "created_at": "2026-09-01T09:30:00+00:00"
    }
  ]
}

Geheimnisse wie Passwörter und Schlüssel sind nie Teil einer Antwort.

Sites auflisten#

GET /orgs/{organization}/servers/{server}/sites gibt die Sites des Servers zurück, nach Domain sortiert. GET /orgs/{organization}/servers/{server}/sites/{site} gibt eine Site zurück.

{
  "data": {
    "id": 34,
    "server_id": 12,
    "domain": "shop.example.com",
    "aliases": ["www.shop.example.com"],
    "preview_domain": "kalme-rivier-4821.on-deploy.link",
    "framework": "laravel",
    "status": "installed",
    "php_version": "8.4",
    "repository": "acme/shop",
    "branch": "main",
    "quick_deploy": true,
    "zero_downtime": true,
    "isolated": false,
    "current_release": "20261007143012",
    "deployed_at": "2026-10-07T14:31:40+00:00",
    "created_at": "2026-09-01T10:02:11+00:00"
  }
}

framework ist eines von laravel, symfony, statamic, wordpress, phpmyadmin, php, nextjs, nuxt, html, other und loadbalancer. status ist installed, wenn die Site bereit ist; während sie sich ändert, ist er installing, updating oder removing, und failed, wenn dabei etwas schiefging. quick_deploy ist Push-to-Deploy; isolated sagt, ob die Site als eigener Linux-Benutzer läuft. Die Umgebungsdatei und die Deploy-URL der Site werden nie zurückgegeben.

Eine Site finden#

GET /orgs/{organization}/sites gibt die Sites auf allen Servern zurück, auf die du Zugriff hast, nach Domain sortiert, jede mit ihrem server (ID und Name). Die übrigen Felder sind dieselben wie oben. Grenze die Liste mit Query-Parametern ein:

curl "https://deploy.example.com/api/v1/orgs/acme/sites?domain=shop.example.com" \
  -H "Authorization: Bearer $VIMONTO_TOKEN" -H "Accept: application/json"

{
  "data": [
    {
      "id": 34,
      "server_id": 12,
      "server": { "id": 12, "name": "web-1" },
      "domain": "shop.example.com",
      "status": "installed",
      "branch": "main"
    }
  ]
}

Ein Token mit nur dem Bereich Deploy darf ihn auch aufrufen, um die Site zu finden, die er deployt, muss dann aber domain oder id angeben; ohne ist die Antwort 422. Passt nichts, ist data eine leere Liste.

Deployments auflisten#

GET /orgs/{organization}/servers/{server}/sites/{site}/deployments gibt die Deployments der Site zurück, das neueste zuerst, 25 pro Seite (siehe Paginierung). GET …/deployments/{deployment} gibt eines zurück.

{
  "data": {
    "id": 581,
    "site_id": 34,
    "status": "succeeded",
    "trigger": "api",
    "branch": "main",
    "commit": {
      "hash": "9f2c4e1a7b3d5f60812a9c4e7d1b3a5c7e9f1a2b",
      "author": "Sam de Vries",
      "message": "Add checkout page"
    },
    "release": "20261007143012",
    "task_id": 9120,
    "started_at": "2026-10-07T14:30:12+00:00",
    "finished_at": "2026-10-07T14:31:40+00:00",
    "created_at": "2026-10-07T14:30:11+00:00"
  }
}

Ein Deployment starten#

POST /orgs/{organization}/servers/{server}/sites/{site}/deployments deployt den Branch der Site, genau wie Jetzt deployen in der App. Er braucht keinen Body. Er antwortet mit 202 Accepted und dem neuen Deployment; verfolge es über seine task_id.

curl -X POST https://deploy.example.com/api/v1/orgs/acme/servers/12/sites/34/deployments \
  -H "Authorization: Bearer $VIMONTO_TOKEN" -H "Accept: application/json"

{
  "data": {
    "id": 582,
    "site_id": 34,
    "status": "queued",
    "trigger": "api",
    "branch": "main",
    "commit": null,
    "release": null,
    "task_id": 9121,
    "started_at": null,
    "finished_at": null,
    "created_at": "2026-10-07T15:02:45+00:00"
  }
}

• 409, wenn bereits ein Deploy der Site läuft; task_id in der Antwort ist der laufende Task.
• 422, wenn die Site noch nicht bereit zum Deployen ist oder kein Repository hat.

Was ein Deploy macht, steht unter Deployments.

Datenbanken auflisten und anlegen#

GET /orgs/{organization}/servers/{server}/databases gibt die Datenbanken des Servers zurück, nach Namen sortiert.

{
  "data": [
    { "id": 3, "server_id": 12, "name": "shop", "status": "installed", "created_at": "2026-09-01T10:05:00+00:00" }
  ]
}

POST /orgs/{organization}/servers/{server}/databases legt eine Datenbank auf dem Server an. Der Body hat ein Feld:

curl -X POST https://deploy.example.com/api/v1/orgs/acme/servers/12/databases \
  -H "Authorization: Bearer $VIMONTO_TOKEN" -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "shop_staging"}'

{
  "data": { "id": 4, "server_id": 12, "name": "shop_staging", "status": "installing", "created_at": "2026-10-07T15:10:00+00:00", "task_id": 9122 }
}

Die Antwort ist 202: Die Datenbank wird von einem Task auf dem Server angelegt. Ihr status ist installing, dann installed, oder failed, wenn der Task fehlschlägt. Der Server muss aktiv sein und eine Datenbank installiert haben, sonst ist die Antwort 422.

Eine Datenbank löschen#

DELETE /orgs/{organization}/servers/{server}/databases/{database} löscht die Datenbank auf dem Server. Er antwortet mit 202, der Datenbank, jetzt removing, und dem Task, der sie entfernt, in task_id, innerhalb von data wie bei jedem Endpunkt, der einen Task startet:

{
  "data": { "id": 4, "server_id": 12, "name": "shop_staging", "status": "removing", "created_at": "2026-10-07T15:10:00+00:00", "task_id": 9123 }
}

Siehe Datenbanken.

Backups auflisten und eines ausführen#

GET /orgs/{organization}/servers/{server}/backups gibt die Backup-Konfigurationen des Servers zurück, nach Namen sortiert, jede mit ihren 20 neuesten Backups. size ist in Bytes.

{
  "data": [
    {
      "id": 2,
      "name": "Nightly",
      "databases": ["shop"],
      "frequency": "nightly",
      "schedule": "0 0 * * *",
      "retention": 7,
      "storage": "Backups bucket",
      "backups": [
        {
          "id": 140,
          "status": "succeeded",
          "size": 48213504,
          "databases": ["shop"],
          "task_id": 9050,
          "created_at": "2026-10-07T00:00:02+00:00",
          "finished_at": "2026-10-07T00:01:15+00:00"
        }
      ]
    }
  ]
}

frequency ist minute, hourly, nightly, weekly, monthly, reboot oder custom; schedule ist der Cron-Ausdruck. Der status eines Backups ist running, succeeded oder failed.

POST /orgs/{organization}/servers/{server}/backups/{backup}/run, mit der ID einer Backup-Konfiguration, startet sofort ein Backup. Er braucht keinen Body und antwortet mit 202:

{ "data": { "backup_id": 141, "task_id": 9124 } }

409, wenn bereits ein Backup dieser Konfiguration läuft. Siehe Backups.

Rezepte auflisten und eines ausführen#

GET /orgs/{organization}/recipes gibt die Rezepte der Organisation zurück, nach Namen sortiert. run_as ist root oder server_user.

{
  "data": [
    { "id": 5, "name": "Install htop", "run_as": "root", "script": "apt-get install -y htop", "updated_at": "2026-09-20T08:12:00+00:00" }
  ]
}

POST /orgs/{organization}/recipes/{recipe}/run führt ein Rezept auf einem oder mehreren Servern aus.

curl -X POST https://deploy.example.com/api/v1/orgs/acme/recipes/5/run \
  -H "Authorization: Bearer $VIMONTO_TOKEN" -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"servers": [12, 13], "notify": false}'

{
  "data": {
    "run_id": 77,
    "servers": [
      { "server_id": 12, "task_id": 9125 },
      { "server_id": 13, "task_id": 9126 }
    ]
  }
}

Jeder Server, den du angibst, muss existieren, für dich zugänglich und aktiv sein. Sonst läuft das Rezept nirgends und die Antwort ist 422: errors.servers nennt die Server-IDs, die es nicht gibt oder auf die du keinen Zugriff hast, oder die Namen der Server, die nicht aktiv sind. Die Antwort listet jeden Server mit seinem eigenen Task auf. Siehe Rezepte.

Einen Task verfolgen#

Längere Arbeit (ein Deploy, eine Datenbank, ein Backup, ein Rezept auf einem Server) läuft als Hintergrund-Task, derselbe, den du unter Aktivität siehst. GET /orgs/{organization}/tasks/{task} gibt seinen Zustand und seine Ausgabe zurück:

{
  "data": {
    "id": 9121,
    "type": "site.deploy",
    "name": "Deploying to shop.example.com",
    "status": "running",
    "step": "Run deploy script",
    "progress": 30,
    "error": null,
    "server_id": 12,
    "output": "Cloning into 'releases/20261007150246'...\n",
    "started_at": "2026-10-07T15:02:46+00:00",
    "finished_at": null,
    "created_at": "2026-10-07T15:02:45+00:00"
  }
}

status ist queued, running, succeeded, failed oder cancelled; die letzten drei sind endgültig. progress geht von 0 bis 100. Wenn ein Task fehlschlägt, sagt error, warum. Frage alle paar Sekunden ab, bis der Status endgültig ist.

Paginierung#

Nur die Liste der Deployments ist paginiert, mit 25 Deployments pro Seite, das neueste zuerst. Eine andere Seite fragst du mit ?page=2 ab. Die Antwort hat links und meta neben data:

{
  "data": [ … ],
  "links": {
    "first": "https://deploy.example.com/api/v1/orgs/acme/servers/12/sites/34/deployments?page=1",
    "last": "https://deploy.example.com/api/v1/orgs/acme/servers/12/sites/34/deployments?page=4",
    "prev": null,
    "next": "https://deploy.example.com/api/v1/orgs/acme/servers/12/sites/34/deployments?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 4,
    "path": "https://deploy.example.com/api/v1/orgs/acme/servers/12/sites/34/deployments",
    "per_page": 25,
    "to": 25,
    "total": 92
  }
}

meta enthält außerdem eine Liste links für Seiten-Buttons. Folge links.next, bis es null ist. Alle anderen Listen geben alles in einer Antwort zurück.

Fehler#

Fehler sind JSON mit einer message:

{ "message": "shop.example.com is not ready to deploy yet." }

Ein 409 sieht so aus:

{ "message": "Deploying to shop.example.com is already running.", "task_id": 9121 }

Ein 422 wegen ungültiger Felder listet sie unter errors auf:

{
  "message": "The name field format is invalid.",
  "errors": {
    "name": ["The name field format is invalid."]
  }
}

Rate-Limits#

Jeder Token darf 120 Anfragen pro Minute stellen. Jede Antwort hat die Header X-RateLimit-Limit und X-RateLimit-Remaining. Über dem Limit antwortet die API mit 429 und einem Header Retry-After: der Anzahl Sekunden, die du warten musst.

Wenn du einen Task abfragst, reicht einmal alle paar Sekunden völlig.

Aus GitHub Actions deployen#

Dieser Workflow deployt, nachdem die Tests bestanden sind, und schlägt fehl, wenn der Deploy fehlschlägt. Erstelle einen Token mit nur dem Bereich Deploy und füge ihn als VIMONTO_TOKEN zu den Secrets des Repositorys hinzu (bei GitHub unter Settings → Secrets and variables → Actions). Trage deine eigene Adresse, den Slug der Organisation, die Server-ID und die Site-ID ein.

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    # needs: tests   # erst deployen, wenn dein Test-Job bestanden ist
    steps:
      - name: Deploy to production
        env:
          VIMONTO_TOKEN: ${{ secrets.VIMONTO_TOKEN }}
          API: https://deploy.example.com/api/v1/orgs/acme
          SERVER: 12
          SITE: 34
        run: |
          set -euo pipefail
          auth=(-H "Authorization: Bearer $VIMONTO_TOKEN" -H "Accept: application/json")

          # Deploy starten; curl schlägt bei 4xx/5xx fehl, etwa 409, wenn schon einer läuft.
          task=$(curl -sS --fail-with-body -X POST "${auth[@]}" \
            "$API/servers/$SERVER/sites/$SITE/deployments" | jq -r '.data.task_id')
          echo "Deploy started, task $task"

          # Den Task verfolgen, bis er fertig ist.
          while true; do
            sleep 5
            response=$(curl -sS --fail-with-body "${auth[@]}" "$API/tasks/$task")
            status=$(echo "$response" | jq -r '.data.status')
            echo "Status: $status ($(echo "$response" | jq -r '.data.step // ""'))"
            case "$status" in
              succeeded) exit 0 ;;
              failed|cancelled)
                echo "$response" | jq -r '.data.error // "", .data.output'
                exit 1 ;;
            esac
          done

Schalte Bei jedem Push deployen für die Site aus, wenn CI sie deployt. Sonst startet ein Push selbst einen Deploy, und die Anfrage der Pipeline bekommt dann 409, weil schon ein Deploy läuft.

Oder die CLI nutzen#

Die CLI von Vimonto Deploy fasst diese Anfragen in einem Befehl zusammen: deploy deploy shop.example.com --watch startet den Deploy, verfolgt den Task und beendet sich mit seinem Ergebnis. In CI liest sie den Token aus DEPLOY_TOKEN.

Oder die Deploy-URL nutzen#

Wenn du nur einen Deploy starten musst, ist die geheime Deploy-URL der Site einfacher: ein POST ohne Token und nichts zu verfolgen. Sie sagt deiner Pipeline aber nicht, ob der Deploy erfolgreich war. Siehe Deployments.

Häufige Fragen#

Ist ein Token an eine Organisation gebunden?#

Nein. Ein Token erreicht jede Organisation, in der du Mitglied bist, mit deiner Rolle in jeder davon. GET /user listet sie auf. Lege einen eigenen Account an, wenn eine Pipeline nur eine Organisation erreichen soll.

Was passiert mit meinen Tokens, wenn sich meine Rolle ändert?#

Ein Token folgt immer deiner aktuellen Rolle und deinem aktuellen Serverzugriff. Verlierst du eine Berechtigung oder verlässt du eine Organisation, verliert der Token sie sofort ebenfalls.

Kann ich über die API Server oder Sites anlegen?#

Noch nicht. Die API umfasst das Lesen von Servern, Sites, Deployments, Datenbanken, Backups, Rezepten und Tasks; Deployen; das Anlegen und Entfernen von Datenbanken; und das Ausführen von Backups und Rezepten.

Wo finde ich die Server- und die Site-ID?#

In der Adressleiste der App: Auf den Seiten einer Site lautet die Adresse /{organization}/servers/{server}/sites/{site}/…. Auch GET /orgs/{organization}/servers und GET …/servers/{server}/sites listen sie auf, und GET /orgs/{organization}/sites?domain=shop.example.com findet eine Site samt Server-ID über ihre Domain.