feat(API): add key format annotations list endpoint #STRINGS-3028

doc/compiled.json

@@ -112,6 +112,9 @@
     {
       "name": "Jobs"
     },
+    {
+      "name": "Key Format Annotations"
+    },
     {
       "name": "Keys"
     },
@@ -217,6 +220,7 @@
         "Projects",
         "Locales",
         "Keys",
+        "Key Format Annotations",
         "Translations",
         "Uploads",
         "Tags",
@@ -31484,6 +31488,91 @@
         ]
       }
     },
+    "/projects/{project_id}/keys/{id}/format_annotations": {
+      "get": {
+        "summary": "List format annotations for a key",
+        "description": "Returns the format annotations stored on a translation key. Format annotations capture\nfile-format data recorded when the key was imported — for example, an ARB placeholder\nblock or an XLIFF note.\n\nResults are limited to 1,000 entries.\n",
+        "operationId": "key_format_annotations/list",
+        "tags": [
+          "Key Format Annotations"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/X-PhraseApp-OTP"
+          },
+          {
+            "$ref": "#/components/parameters/project_id"
+          },
+          {
+            "$ref": "#/components/parameters/id"
+          },
+          {
+            "$ref": "#/components/parameters/branch"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "file_format": {
+                        "type": "string",
+                        "description": "The file format that produced this annotation.\n",
+                        "example": "xliff_2"
+                      },
+                      "original_representation": {
+                        "type": "string",
+                        "description": "The original file-format snippet captured when the key was imported. Returned as-is, may contain multi-line content.\n",
+                        "example": "<note category=\"meaning\">header</note>"
+                      }
+                    }
+                  }
+                },
+                "example": [
+                  {
+                    "file_format": "xliff_2",
+                    "original_representation": "<note category=\"meaning\">header</note>"
+                  }
+                ]
+              }
+            },
+            "headers": {
+              "X-Rate-Limit-Limit": {
+                "$ref": "#/components/headers/X-Rate-Limit-Limit"
+              },
+              "X-Rate-Limit-Remaining": {
+                "$ref": "#/components/headers/X-Rate-Limit-Remaining"
+              },
+              "X-Rate-Limit-Reset": {
+                "$ref": "#/components/headers/X-Rate-Limit-Reset"
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/400"
+          },
+          "401": {
+            "$ref": "#/components/responses/401"
+          },
+          "403": {
+            "$ref": "#/components/responses/403",
+            "description": "Forbidden. Returned when the access token lacks the `read` scope or when the requesting user is not allowed to access keys in this project."
+          },
+          "404": {
+            "$ref": "#/components/responses/404"
+          },
+          "429": {
+            "$ref": "#/components/responses/429"
+          }
+        },
+        "x-cli-version": "2.5"
+      }
+    },
     "/accounts/{account_id}/automations": {
       "get": {
         "summary": "List automations",

main.yaml

@@ -135,6 +135,7 @@ tags:
   - name: Job Template Locales
   - name: Job Templates
   - name: Jobs
+  - name: Key Format Annotations
   - name: Keys
   - name: Linked Keys
   - name: Locales
@@ -274,6 +275,7 @@ x-tagGroups:
       - Projects
       - Locales
       - Keys
+      - Key Format Annotations
       - Translations
       - Uploads
       - Tags

paths.yaml

@@ -724,6 +724,9 @@
 "/projects/{project_id}/keys/{id}/key_links/{child_key_id}":
   delete:
     "$ref": "./paths/key_links/destroy.yaml"
+"/projects/{project_id}/keys/{id}/format_annotations":
+  get:
+    "$ref": "./paths/key_format_annotations/index.yaml"
 "/accounts/{account_id}/automations":
   get:
     "$ref": "./paths/automations/index.yaml"

paths/key_format_annotations/index.yaml

@@ -0,0 +1,47 @@
+---
+summary: List format annotations for a key
+description: |
+  Returns the format annotations stored on a translation key. Format annotations capture
+  file-format data recorded when the key was imported — for example, an ARB placeholder
+  block or an XLIFF note.
+
+  Results are limited to 1,000 entries.
+operationId: key_format_annotations/list
+tags:
+  - Key Format Annotations
+parameters:
+  - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
+  - "$ref": "../../parameters.yaml#/project_id"
+  - "$ref": "../../parameters.yaml#/id"
+  - "$ref": "../../parameters.yaml#/branch"
+responses:
+  '200':
+    description: OK
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            "$ref": "../../schemas/format_annotation.yaml#/format_annotation"
+        example:
+          - file_format: xliff_2
+            original_representation: '<note category="meaning">header</note>'
+    headers:
+      X-Rate-Limit-Limit:
+        "$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
+      X-Rate-Limit-Remaining:
+        "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining"
+      X-Rate-Limit-Reset:
+        "$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
+  '400':
+    "$ref": "../../responses.yaml#/400"
+  '401':
+    "$ref": "../../responses.yaml#/401"
+  '403':
+    "$ref": "../../responses.yaml#/403"
+    description: Forbidden. Returned when the access token lacks the `read` scope or when the requesting user is not allowed to access keys in this project.
+  '404':
+    "$ref": "../../responses.yaml#/404"
+  '429':
+    "$ref": "../../responses.yaml#/429"
+x-cli-version: "2.5"

schemas/format_annotation.yaml

@@ -0,0 +1,14 @@
+format_annotation:
+  type: object
+  properties:
+    file_format:
+      type: string
+      description: >
+        The file format that produced this annotation.
+      example: xliff_2
+    original_representation:
+      type: string
+      description: >
+        The original file-format snippet captured when the key was imported.
+        Returned as-is, may contain multi-line content.
+      example: '<note category="meaning">header</note>'