From ff248079ee74d1b6564474d46c750b442add7262 Mon Sep 17 00:00:00 2001
From: Thomas Soring <tsoring@lilapixel.de>
Date: Thu, 5 Mar 2026 21:20:29 +0100
Subject: [PATCH] fix: API-Doku mit verifizierten Response-Formaten und
 korrekten Feldnamen
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- PATCH domain: 'domains' statt 'fqdn' (fqdn -> 422 Validation Error)
- POST: fqdn nicht im Body erlaubt, Domain separat per PATCH setzen
- GET /deployments/applications/{uuid}: Response ist {count, deployments:[]}
  kein reines Array; Feld heißt deployment_uuid (nicht uuid)
- /deploy Response: {deployments:[{message, resource_uuid, deployment_uuid}]}
- Polling-Beispiel: .deployments[0].deployment_uuid

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/content/docs/api/applications.mdx | 18 ++++++----
 src/content/docs/api/deployments.md   | 47 +++++++++++++++------------
 2 files changed, 38 insertions(+), 27 deletions(-)

diff --git a/src/content/docs/api/applications.mdx b/src/content/docs/api/applications.mdx
index 0d0c2b3..89d7654 100644
--- a/src/content/docs/api/applications.mdx
+++ b/src/content/docs/api/applications.mdx
@@ -111,7 +111,10 @@ Für Repositories auf `git.coolai.btc-ag.cloud`.
 | `build_pack` | string | ja | `dockerfile` \| `nixpacks` \| `static` |
 | `ports_exposes` | string | ja | Port(s) der Anwendung (z. B. `3000`) |
 | `name` | string | nein | Anzeigename |
-| `fqdn` | string | nein | Domain(s), kommagetrennt |
+
+:::note
+`fqdn`/Domain kann **nicht** im POST-Body gesetzt werden — dies geschieht per PATCH nach der Anlage (siehe unten).
+:::
 
 <Tabs>
   <TabItem label="Request">
@@ -129,8 +132,7 @@ curl -s -X POST https://coolai.btc-ag.cloud/api/v1/applications/private-deploy-k
     "git_branch": "main",
     "build_pack": "dockerfile",
     "ports_exposes": "3000",
-    "name": "meine-app",
-    "fqdn": "https://meine-app.btc-ag.cloud"
+    "name": "meine-app"
   }'
 ```
 
@@ -140,7 +142,7 @@ curl -s -X POST https://coolai.btc-ag.cloud/api/v1/applications/private-deploy-k
 ```json
 {
   "uuid": "newly-created-uuid",
-  "message": "Application created."
+  "domains": "http://newly-created-uuid.server-ip.sslip.io"
 }
 ```
 
@@ -162,19 +164,21 @@ Aktualisiert einzelne Felder einer Anwendung. Nur übergebene Felder werden geä
 | Feld | Beschreibung |
 |---|---|
 | `name` | Anzeigename |
-| `fqdn` | Domain(s) |
+| `domains` | Domain(s) setzen — **nicht** `fqdn`! (GET zeigt `fqdn`, PATCH erwartet `domains`) |
 | `git_branch` | Branch wechseln |
+| `git_repository` | Repository-URL ändern |
 | `environment_variables` | Variablen als Newline-getrennter String |
 | `dockerfile_location` | Pfad zum Dockerfile |
 
 <Tabs>
-  <TabItem label="Domain ändern">
+  <TabItem label="Domain setzen">
 
 ```bash
+# Feld heißt "domains" beim Schreiben (GET-Response zeigt "fqdn")
 curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/<uuid> \
   -H "Authorization: Bearer $COOLIFY_TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"fqdn": "https://neue-domain.btc-ag.cloud"}'
+  -d '{"domains": "https://meine-app.btc-ag.cloud"}'
 ```
 
   </TabItem>
diff --git a/src/content/docs/api/deployments.md b/src/content/docs/api/deployments.md
index 26f7725..0081917 100644
--- a/src/content/docs/api/deployments.md
+++ b/src/content/docs/api/deployments.md
@@ -33,8 +33,13 @@ curl -s "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=<app-uuid>&force=true" \
 
 ```json
 {
-  "message": "Deployment queued.",
-  "deployment_uuid": "deploy-abc123"
+  "deployments": [
+    {
+      "message": "Application meine-app deployment queued.",
+      "resource_uuid": "<app-uuid>",
+      "deployment_uuid": "deploy-abc123"
+    }
+  ]
 }
 ```
 
@@ -51,26 +56,28 @@ Gibt alle Deployments einer Anwendung zurück, neueste zuerst.
 ```bash
 curl -s https://coolai.btc-ag.cloud/api/v1/deployments/applications/<app-uuid> \
   -H "Authorization: Bearer $COOLIFY_TOKEN" \
-  | jq '.[] | {uuid, status, created_at}'
+  | jq '.deployments[] | {deployment_uuid, status, created_at}'
 ```
 
-**Response:**
+**Response** — kein reines Array, sondern ein Objekt mit `count` und `deployments`:
 
 ```json
-[
-  {
-    "uuid": "deploy-abc123",
-    "status": "finished",
-    "created_at": "2026-03-05T10:00:00Z",
-    "logs": "..."
-  },
-  {
-    "uuid": "deploy-xyz789",
-    "status": "failed",
-    "created_at": "2026-03-04T15:30:00Z",
-    "logs": "..."
-  }
-]
+{
+  "count": 3,
+  "deployments": [
+    {
+      "deployment_uuid": "deploy-abc123",
+      "status": "finished",
+      "commit": "b2a4ca66...",
+      "created_at": "2026-03-05T20:13:00Z"
+    },
+    {
+      "deployment_uuid": "deploy-xyz789",
+      "status": "failed",
+      "created_at": "2026-03-05T20:10:00Z"
+    }
+  ]
+}
 ```
 
 ---
@@ -142,11 +149,11 @@ Für automatisierte Workflows, die auf den Abschluss eines Deployments warten m
 APP_UUID="<app-uuid>"
 COOLIFY_TOKEN="<token>"
 
-# Deployment starten und UUID merken
+# Deployment starten und UUID merken (deployment_uuid steckt in .deployments[0])
 DEPLOY_UUID=$(curl -s \
   "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=$APP_UUID&force=false" \
   -H "Authorization: Bearer $COOLIFY_TOKEN" \
-  | jq -r '.deployment_uuid')
+  | jq -r '.deployments[0].deployment_uuid')
 
 echo "Deployment gestartet: $DEPLOY_UUID"