From 8078da0bda7c4f350c5887a9e796e07aaa1ea18a Mon Sep 17 00:00:00 2001
From: GnomeZworc <nicolas.boufidjeline@g3e.fr>
Date: Mon, 24 Aug 2026 22:27:57 +0200
Subject: [PATCH] f-34: doc: update api doc #34

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
---
 api/agent.yaml | 38 +++++++++++++++++++++++++++++++++-----
 1 file changed, 33 insertions(+), 5 deletions(-)

diff --git a/api/agent.yaml b/api/agent.yaml
index 0861353..b9bebf5 100644
--- a/api/agent.yaml
+++ b/api/agent.yaml
@@ -427,11 +427,8 @@ components:
           type: integer
           description: Number of vCPUs (default 1)
           example: 2
-        password:
-          type: string
-        sshkey:
-          type: string
-          example: "ssh-ed25519 AAAA..."
+        metadata:
+          $ref: "#/components/schemas/VMMetadata"
         interfaces:
           type: array
           minItems: 1
@@ -447,6 +444,37 @@ components:
           description: Boot with UEFI firmware (OVMF). Defaults to false (SeaBIOS).
           example: false
 
+    VMMetadata:
+      type: object
+      description: >
+        cloud-init inputs for this VM. Every field is optional. Documents not
+        supplied here fall back to the agent's built-in templates; a document
+        supplied as an empty string is served empty, which is not the same
+        thing.
+      properties:
+        password:
+          type: string
+          description: >
+            Password *hash* for the syonad account, as expected by the
+            cloud-config `passwd` key (e.g. `$6$...`) — not a plaintext
+            password. When omitted, the account is created locked
+            (`lock_passwd: true`); when neither password nor sshkey is given,
+            no account is created at all.
+          example: "$6$rounds=4096$saltsalt$hash..."
+        sshkey:
+          type: string
+          description: Public SSH key added to the syonad account. Sent as-is, not encoded.
+          example: "ssh-ed25519 AAAA..."
+        user_data:
+          type: string
+          format: byte
+          description: >
+            cloud-init user-data, **base64-encoded**. Encoding keeps multi-line
+            documents out of JSON escaping and allows gzip+base64 payloads.
+            Invalid base64 is rejected with 400 rather than silently serving an
+            empty document. The agent never interprets this content.
+          example: "I2Nsb3VkLWNvbmZpZwpwYWNrYWdlczoKICAtIG5naW54Cg=="
+
     VMInterface:
       type: object
       required: [subnet, ip, primary]