From 5d204d74603ce717abda6feeb43a2785de19b310 Mon Sep 17 00:00:00 2001
From: hamed <15238-genius.ha@users.noreply.drupalcode.org>
Date: Mon, 15 Jun 2026 19:02:41 +0330
Subject: [PATCH] docs(api): document user-profile resolve-by-user-uuid and
 lazy-create
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GET/PATCH /api/v1/user-profile/{uuid} now accept either a profile uuid or
the owning user's uuid, and lazily create an empty profile for a user who
has none — documented with the double-nested response note.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/api/user-profile.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/api/user-profile.md b/docs/api/user-profile.md
index 610d0ff6..fa905821 100644
--- a/docs/api/user-profile.md
+++ b/docs/api/user-profile.md
@@ -95,17 +95,19 @@ Get a user profile.
 ### Path Parameters
 | Param | Type | Description |
 |-------|------|-------------|
-| `uuid` | string (UUID) | Profile UUID |
+| `uuid` | string (UUID) | **Profile UUID or the owning User UUID** — both are accepted |
+
+> **Auto-resolve & lazy-create:** `{uuid}` is first looked up as a profile uuid, then as a user uuid. If it is the **current user's** (or, for admins, any user's) uuid and that user has **no profile yet**, an empty profile is created and returned (HTTP 200) — so a freshly registered user always gets an editable profile instead of a 404. The response includes both the profile `uuid` and `user_uuid`; keep the profile `uuid` for subsequent PATCHes.
 
 ### Response `200`
-Full profile object including all fields.
+Full profile object including all fields (all `null` for a newly created empty profile). Response is double-nested: extract with `data.data`.
 
 ### Errors
 | Code | HTTP | Description |
 |------|------|-------------|
 | `ERR_AUTH_001` | 401 | Missing token |
 | `ERR_FORBIDDEN_001` | 403 | Not authorized to view this profile |
-| `ERR_NOT_FOUND_001` | 404 | Profile not found |
+| `ERR_VALIDATION_002` | 404 | No profile or user matches the uuid |
 
 ---
 
@@ -118,7 +120,7 @@ Update a user profile.
 ### Path Parameters
 | Param | Type | Description |
 |-------|------|-------------|
-| `uuid` | string (UUID) | Profile UUID |
+| `uuid` | string (UUID) | **Profile UUID or the owning User UUID** — both accepted; the profile is created if the current user has none yet |
 
 ### Request Body
 Same fields as POST — all optional.