fix(API): improve get /projects/{project_id}/keys/{id}/key_links documentation

doc/compiled.json

@@ -30879,7 +30879,7 @@
       },
       "get": {
         "summary": "List child keys of a parent key",
-        "description": "Returns detailed information about a parent key, including its linked child keys.",
+        "description": "Returns the key link record for a parent key, including all child keys associated with it. Key linking lets translation keys share translations — a child key inherits content from its designated parent. Use this endpoint to inspect which keys are linked under a given parent before unlinking them or auditing translation consistency across related keys.\n\nThe key identified by {id} must be designated as a parent key (it must have at least one child key linked to it). Error codes use lowercase snake_case format.\n",
         "operationId": "key_links/index",
         "tags": [
           "Linked Keys"
@@ -30895,31 +30895,88 @@
             "$ref": "#/components/parameters/key_id_as_id"
           }
         ],
+        "x-code-samples": [
+          {
+            "lang": "Curl",
+            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/keys/:id/key_links\" \\\n  -u USERNAME_OR_ACCESS_TOKEN"
+          }
+        ],
         "responses": {
           "200": {
             "description": "OK",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/key_link"
+                },
+                "example": {
+                  "created_at": "2024-03-12T09:15:00.000Z",
+                  "updated_at": "2024-05-20T14:32:00.000Z",
+                  "created_by": {
+                    "id": "a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4",
+                    "username": "jane.doe",
+                    "name": "Jane Doe",
+                    "gravatar_uid": "abcdef1234567890"
+                  },
+                  "updated_by": {
+                    "id": "a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4",
+                    "username": "jane.doe",
+                    "name": "Jane Doe",
+                    "gravatar_uid": "abcdef1234567890"
+                  },
+                  "account": {
+                    "id": "abcd1234abcd1234abcd1234abcd1234",
+                    "name": "Acme Corp",
+                    "slug": "acme-corp",
+                    "company": "Acme Corporation",
+                    "created_at": "2023-01-10T08:00:00.000Z",
+                    "updated_at": "2024-01-10T08:00:00.000Z"
+                  },
+                  "parent": {
+                    "id": "f1e2d3c4f1e2d3c4f1e2d3c4f1e2d3c4",
+                    "name": "button.submit",
+                    "plural": false,
+                    "use_ordinal_rules": false
+                  },
+                  "children": [
+                    {
+                      "id": "9a8b7c6d9a8b7c6d9a8b7c6d9a8b7c6d",
+                      "name": "button.submit.mobile",
+                      "plural": false,
+                      "use_ordinal_rules": false
+                    },
+                    {
+                      "id": "1a2b3c4d1a2b3c4d1a2b3c4d1a2b3c4d",
+                      "name": "button.submit.web",
+                      "plural": false,
+                      "use_ordinal_rules": false
+                    }
+                  ]
                 }
               }
             }
           },
           "400": {
-            "description": "Bad Request",
+            "description": "Bad request. Returned when the key identified by {id} is not designated as a parent key. To resolve, promote the key to parent status by linking child keys to it first, or supply the code of an existing parent key.",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
+                  "title": "key_links/index/bad_request",
                   "properties": {
                     "message": {
-                      "type": "string"
+                      "type": "string",
+                      "description": "Human-readable description of the error."
+                    },
+                    "error": {
+                      "type": "string",
+                      "description": "Stable machine-readable error code in lowercase snake_case format (e.g. key_not_a_parent). Branch on this field rather than the message string."
                     }
-                  },
-                  "example": {
-                    "message": "Key <parent_key_code> is not a parent key"
                   }
+                },
+                "example": {
+                  "message": "Key button.submit is not a parent key",
+                  "error": "key_not_a_parent"
                 }
               }
             }
@@ -30928,8 +30985,7 @@
             "$ref": "#/components/responses/401"
           },
           "403": {
-            "$ref": "#/components/responses/403",
-            "description": "Forbidden. Returned when the access token lacks the `write` scope or when the requesting user is not allowed to read key links for this key."
+            "$ref": "#/components/responses/403"
           },
           "404": {
             "$ref": "#/components/responses/404"

paths/key_links/index.yaml

@@ -1,36 +1,83 @@
 ---
 summary: List child keys of a parent key
-description: Returns detailed information about a parent key, including its linked child keys.
+description: |
+  Returns the key link record for a parent key, including all child keys associated with it. Key linking lets translation keys share translations — a child key inherits content from its designated parent. Use this endpoint to inspect which keys are linked under a given parent before unlinking them or auditing translation consistency across related keys.
+
+  The key identified by {id} must be designated as a parent key (it must have at least one child key linked to it). Error codes use lowercase snake_case format.
 operationId: key_links/index
 tags:
 - Linked Keys
 parameters:
 - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
 - "$ref": "../../parameters.yaml#/project_id"
 - "$ref": "../../parameters.yaml#/key_id_as_id"
+x-code-samples:
+- lang: Curl
+  source: |-
+    curl "https://api.phrase.com/v2/projects/:project_id/keys/:id/key_links" \
+      -u USERNAME_OR_ACCESS_TOKEN
 responses:
   '200':
     description: OK
     content:
       application/json:
         schema:
           $ref: "../../schemas/key_link.yaml#/key_link"
+        example:
+          created_at: "2024-03-12T09:15:00.000Z"
+          updated_at: "2024-05-20T14:32:00.000Z"
+          created_by:
+            id: "a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4"
+            username: "jane.doe"
+            name: "Jane Doe"
+            gravatar_uid: "abcdef1234567890"
+          updated_by:
+            id: "a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4"
+            username: "jane.doe"
+            name: "Jane Doe"
+            gravatar_uid: "abcdef1234567890"
+          account:
+            id: "abcd1234abcd1234abcd1234abcd1234"
+            name: "Acme Corp"
+            slug: "acme-corp"
+            company: "Acme Corporation"
+            created_at: "2023-01-10T08:00:00.000Z"
+            updated_at: "2024-01-10T08:00:00.000Z"
+          parent:
+            id: "f1e2d3c4f1e2d3c4f1e2d3c4f1e2d3c4"
+            name: "button.submit"
+            plural: false
+            use_ordinal_rules: false
+          children:
+          - id: "9a8b7c6d9a8b7c6d9a8b7c6d9a8b7c6d"
+            name: "button.submit.mobile"
+            plural: false
+            use_ordinal_rules: false
+          - id: "1a2b3c4d1a2b3c4d1a2b3c4d1a2b3c4d"
+            name: "button.submit.web"
+            plural: false
+            use_ordinal_rules: false
   '400':
-    description: Bad Request
+    description: Bad request. Returned when the key identified by {id} is not designated as a parent key. To resolve, promote the key to parent status by linking child keys to it first, or supply the code of an existing parent key.
     content:
       application/json:
         schema:
           type: object
+          title: key_links/index/bad_request
           properties:
             message:
               type: string
-          example:
-            message: "Key <parent_key_code> is not a parent key"
+              description: Human-readable description of the error.
+            error:
+              type: string
+              description: Stable machine-readable error code in lowercase snake_case format (e.g. key_not_a_parent). Branch on this field rather than the message string.
+        example:
+          message: "Key button.submit is not a parent key"
+          error: "key_not_a_parent"
   '401':
     "$ref": "../../responses.yaml#/401"
   '403':
     "$ref": "../../responses.yaml#/403"
-    description: Forbidden. Returned when the access token lacks the `write` scope or when the requesting user is not allowed to read key links for this key.
   '404':
     "$ref": "../../responses.yaml#/404"
   '429':