livingdocsIO · marcbachmann · Dec 17, 2024
diff --git a/content/guides/editor/menus/index.md b/content/guides/editor/menus/index.md
@@ -4,9 +4,8 @@ description: Model menus with data records
 weight: 4
 ---
 
-{{< info >}}
-As of {{< release "release-2024-11" >}}, the Menu Tool has been deprecated in favor of modeling menus with data records. Please reach out for assistance with migrating from the Menu Tool to data records.
-{{< /info >}}
+>[!WARNING] {{< deprecated-in "release-2024-11" >}}
+The Menu Tool has been deprecated in favor of modeling menus with data records. Please reach out for assistance with migrating from the Menu Tool to data records.
 
 Menus can be conveniently modeled using data records, which can be included in dashboards and referenced in other documents. Like all documents in Livingdocs, they define the content but not the presentation.
 
@@ -146,4 +145,4 @@ const filters = JSON.stringify([
   {key: 'metadata.name.id', term: 'menu:main'}
 ])
 const response = await fetch(`api/v1/publications/search?filters=${filters}`)
-```
+```
diff --git a/content/operations/releases/release-2022-09.md b/content/operations/releases/release-2022-09.md
@@ -5,7 +5,6 @@ description: Release notes for release-2022-09
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2022-09/
   - /operations/releases/release-2022-09/release-2022-09/
 ---
 

diff --git a/content/operations/releases/release-2022-11.md b/content/operations/releases/release-2022-11.md
@@ -5,7 +5,6 @@ description: Release notes for release-2022-11
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2022-11/
   - /operations/releases/release-2022-11/release-2022-11/
 ---
 

diff --git a/content/operations/releases/release-2023-01.md b/content/operations/releases/release-2023-01.md
@@ -5,7 +5,6 @@ description: Technical Release Notes for release-2023-01
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2023-01/
   - /operations/releases/release-2023-01/release-2023-01/
 ---
 

diff --git a/content/operations/releases/release-2023-03.md b/content/operations/releases/release-2023-03.md
@@ -5,7 +5,6 @@ description: Technical Release Notes for release-2023-03
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2023-03/
   - /operations/releases/release-2023-03/release-2023-03/
 ---
 

diff --git a/content/operations/releases/release-2023-05.md b/content/operations/releases/release-2023-05.md
@@ -5,7 +5,6 @@ description: Technical Release Notes for release-2023-05
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2023-05/
   - /operations/releases/release-2023-05/release-2023-05/
 ---
 

diff --git a/content/operations/releases/release-2023-07.md b/content/operations/releases/release-2023-07.md
@@ -5,7 +5,6 @@ description: Technical Release Notes for release-2023-07
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2023-07/
   - /operations/releases/release-2023-07/release-2023-07/
 ---
 

diff --git a/content/operations/releases/release-2023-09.md b/content/operations/releases/release-2023-09.md
@@ -5,7 +5,6 @@ description: Technical Release Notes for release-2023-09
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2023-09/
   - /operations/releases/release-2023-09/release-2023-09/
 ---
 

diff --git a/content/operations/releases/release-2023-11.md b/content/operations/releases/release-2023-11.md
@@ -5,7 +5,6 @@ description: Technical Release Notes for release-2023-11
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2023-11/
   - /operations/releases/release-2023-11/release-2023-11/
 ---
 

diff --git a/content/operations/releases/release-2024-01.md b/content/operations/releases/release-2024-01.md
@@ -5,7 +5,6 @@ description: Technical Release Notes for release-2024-01
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2024-01/
   - /operations/releases/release-2024-01/release-2024-01/
 ---
 

diff --git a/content/operations/releases/release-2024-03.md b/content/operations/releases/release-2024-03.md
@@ -5,7 +5,6 @@ description: Technical Release Notes for release-2024-03
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2024-03/
   - /operations/releases/release-2024-03/release-2024-03/
 ---
 

diff --git a/content/operations/releases/release-2024-05.md b/content/operations/releases/release-2024-05.md
@@ -5,7 +5,6 @@ description: Technical Release Notes for release-2024-05
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2024-05/
   - /operations/releases/release-2024-05/release-2024-05/
 ---
 

diff --git a/content/operations/releases/release-2024-07.md b/content/operations/releases/release-2024-07.md
@@ -5,7 +5,6 @@ description: Technical Release Notes for release-2024-07
 excludeFromSearch: false
 hideSectionTeaser: true
 aliases:
-  - /operations/releases/release-2024-07/
   - /operations/releases/release-2024-07/release-2024-07/
 ---
 

diff --git a/content/operations/releases/release-2024-09.md b/content/operations/releases/release-2024-09.md
@@ -4,8 +4,6 @@ title: September 2024 Release
 description: Technical Release Notes for release-2024-09
 excludeFromSearch: false
 hideSectionTeaser: true
-aliases:
-  - /operations/releases/release-2024-09/
 ---
 
 {{< release-header

diff --git a/content/operations/releases/release-2024-11.md b/content/operations/releases/release-2024-11.md
@@ -4,8 +4,6 @@ title: November 2024 Release
 description: Technical Release Notes for release-2024-11
 excludeFromSearch: false
 hideSectionTeaser: true
-aliases:
-  - /operations/releases/release-2024-11/
 ---
 
 {{< release-header

diff --git a/content/operations/releases/release-2025-01.md b/content/operations/releases/release-2025-01.md
@@ -4,8 +4,6 @@ title: January 2025 Release
 description: Technical Release Notes for release-2025-01
 excludeFromSearch: true
 hideSectionTeaser: true
-aliases:
-  - /operations/releases/release-2025-01/
 ---
 
 {{< release-header

diff --git a/content/reference/public-api/add-delivery-status.md b/content/reference/public-api/add-delivery-status.md
@@ -8,57 +8,4 @@ menus:
     parent: Public API
 ---
 
-{{< api-example
-  title="Add Delivery Status"
-  scopes="public-api:write"
->}}
-
---query--
-
-```bash
-ACCESS_TOKEN=ey1234
-curl -k -X POST "https://server.livingdocs.io/api/v1/documents/:documentId/addDeliveryStatus" \
-  -H "Authorization: Bearer $ACCESS_TOKEN" \
-  -H "Content-Type: application/json; charset=utf-8" \
-  --data-binary @- << EOF
-  {
-    "reportId": "2SG2MAA9RwPn",
-    "publicationId": 524,
-    "deliveryHandle": "web",
-    "status": "success",
-    "message": "Message with <strong>html</strong>"
-  }
-EOF
-```
-
---endpoint--
-```
-POST api/v1/documents/:documentId/addDeliveryStatus
-```
-
---parameters--
-| Name           | Type                                  | Required | Notes                                                                                                                                                            |
-|----------------|---------------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| :documentId    | integer                               | x        |                                                                                                                                                                  |
-| reportId       | string                                |          | If provided, this will update the matching delivery build; otherwise, it will create a new one.                                                                  |
-| publicationId  | integer                               | (x)      | Required for delivery builds of type `publication`                                                                                                               |
-| deliveryHandle | string                                | x        |                                                                                                                                                                  |
-| status         | string                                | x        | One of: "success", "failed", "aborted" ({{< added-in "release-2024-07" >}}), "in-progress"                                                                       |
-| message        | string                                |          | String or sanitized HTML (supports `<em>`, `<strong>`, `<a>` and `<br>` tags)                                                                                    |
-| userChoices    | Array<{label: string, value: string}> |          | An array of options given to the user to choose from. This parameter is only allowed when `status` is set to "in-progress". ({{< added-in "release-2024-07" >}}) |
-
---description--
-This endpoint allows an external system to send updates about a delivery build to Livingdocs.
-
-Delivery builds are initiated by users within the Livingdocs editor and can be configured to notify an external system. Through this endpoint, external systems can report back to Livingdocs regarding the status of a triggered task or request further clarification by providing user choices. For more information on how to set up and use delivery builds, please refer to our [guide]({{< ref "/guides/editor/publish-control/delivery" >}}).
-
---response--
-200
----
-api/v1/documents/222/addDeliveryStatus
----
-```js
-{reportId: '0TAW2ORdNjuM'}
-```
-
-{{< /api-example >}}
+{{< api-example-resource file="add-delivery-status.yaml" >}}
diff --git a/content/reference/public-api/add-delivery-status.yaml b/content/reference/public-api/add-delivery-status.yaml
@@ -0,0 +1,64 @@
+title: Add Delivery Status
+description: |
+  This endpoint allows an external system to send updates about a delivery build to Livingdocs.
+
+  Delivery builds are initiated by users within the Livingdocs editor and can be configured to notify an external system. Through this endpoint, external systems can report back to Livingdocs regarding the status of a triggered task or request further clarification by providing user choices. For more information on how to set up and use delivery builds, please refer to our [guide]({{< ref "/guides/editor/publish-control/delivery" >}}).
+
+scopes: public-api:write
+query: |
+  ACCESS_TOKEN=ey1234
+  curl -k -X POST "https://server.livingdocs.io/api/v1/documents/:documentId/addDeliveryStatus" \
+    -H "Authorization: Bearer $ACCESS_TOKEN" \
+    -H "Content-Type: application/json; charset=utf-8" \
+    --data-binary @- << EOF
+    {
+      "reportId": "2SG2MAA9RwPn",
+      "publicationId": 524,
+      "deliveryHandle": "web",
+      "status": "success",
+      "message": "Message with <strong>html</strong>"
+    }
+    EOF
+endpoint:
+  method: POST
+  path: /api/v1/documents/:documentId/addDeliveryStatus
+parameters:
+  - name: :documentId
+    type: integer
+    required: true
+    notes: ""
+  - name: reportId
+    type: string
+    required: false
+    notes: "If provided, this will update the matching delivery build; otherwise, it will create a new one."
+  - name: publicationId
+    type: integer
+    required: conditional
+    notes: "Required for delivery builds of type `publication`"
+  - name: deliveryHandle
+    type: string
+    required: true
+    notes: ""
+  - name: status
+    type: string
+    required: true
+    notes: |
+      One of: `success`, `failed`, `aborted` ({{< added-in "release-2024-07" >}}), `in-progress`
+  - name: message
+    type: string
+    required: false
+    notes: "String or sanitized HTML (supports `<em>`, `<strong>`, `<a>` and `<br>` tags)"
+  - name: userChoices
+    type: |
+      Array<{label: string, value: string}>
+    required: false
+    notes: An array of options given to the user to choose from. This parameter is only allowed when `status` is set to `in-progress`. ({{< added-in "release-2024-07" >}})
+
+responses:
+  - code: "200"
+    name: OK
+    endpoint: /api/v1/documents/222/addDeliveryStatus
+    body: |
+      {
+        "reportId": "0TAW2ORdNjuM"
+      }