Folder Structure & Zipped Output Documentation

src/pages/contributors.json

@@ -41,11 +41,12 @@
     {
       "page": "/getting-started/changelog/",
       "avatars": [
+        "https://avatars.githubusercontent.com/u/66052604?v=4",
         "https://avatars.githubusercontent.com/u/274493592?v=4",
         "https://avatars.githubusercontent.com/u/264675027?v=4",
         "https://avatars.githubusercontent.com/u/41382203?v=4"
       ],
-      "lastUpdated": "6/2/2026"
+      "lastUpdated": "6/17/2026"
     },
     {
       "page": "/getting-started/concepts/",
@@ -58,9 +59,10 @@
     {
       "page": "/getting-started/usage/",
       "avatars": [
+        "https://avatars.githubusercontent.com/u/66052604?v=4",
         "https://avatars.githubusercontent.com/u/41382203?v=4"
       ],
-      "lastUpdated": "3/16/2026"
+      "lastUpdated": "6/17/2026"
     },
     {
       "page": "/guides/",
@@ -94,12 +96,15 @@
     {
       "page": "/guides/working-with-datamerge-api/",
       "avatars": [
+        "https://avatars.githubusercontent.com/u/160902380?v=4",
+        "https://avatars.githubusercontent.com/u/160902380?v=4",
         "https://avatars.githubusercontent.com/u/274493592?v=4",
         "https://avatars.githubusercontent.com/u/41382203?v=4",
         "https://avatars.githubusercontent.com/u/66052604?v=4",
         "https://avatars.githubusercontent.com/u/195011431?v=4"
       ],
-      "lastUpdated": "5/5/2026"
+      "lastUpdated": "5/25/2026"
+      "lastUpdated": "5/25/2026"
     },
     {
       "page": "/guides/working-with-rendition-api/",

src/pages/getting-started/changelog/index.md

@@ -41,11 +41,18 @@ twitter:
 
 This page contains the release notes and version history for Adobe InDesign APIs. Stay updated with the latest features, improvements, and bug fixes.
 
+## July 29, 2026
+
+### Enhancements
+
+- **Folder Structure and Zipped Output Support in Data Merge API:** The `POST /v4/merge-data` endpoint now supports organizing your outputs in a structured folder hierarchy, and a zipped folder containing all the outputs that have been created from the successful data merge. [Learn more about Folder Structure and Zipped Output support.][16]
+
 ## June 2, 2026
 
 ### Enhancements
 
 - **Variable File Naming Support in Data Merge API:** The `POST /v3/merge-data` endpoint now supports variable file naming. [Learn more about variable file naming support.][14]
+- **Increased Asset Size Limit:** The maximum supported asset size has been increased from 1GB to 2GB, enabling processing of larger InDesign documents and linked assets. [Learn more about file size limits.][15]
 
 ## March 18, 2026
 
@@ -143,3 +150,5 @@ This page contains the release notes and version history for Adobe InDesign APIs
 [12]: ../../guides/pdf-to-indesign-conversion-notes/index.md
 [13]: ../concepts/index.md#api-capability-naming-rules
 [14]: ../../guides/working-with-datamerge-api/index.md#variable-file-naming-support-in-data-merge-api
+[15]: ../usage/index.md#file-size-limits
+[16]: ../../guides/working-with-datamerge-api/index.md#folder-structure-and-zipped-output-in-data-merge-api

src/pages/getting-started/usage/index.md

@@ -38,11 +38,10 @@ To maintain API stability and fair usage across clients, the following limits ar
 
 * Hard limit: 350 requests per minute. Requests beyond this limit are rejected.
 
-### File size
+### File size limits
 
-For the Custom Scripts API, the maximum allowed size for a Custom Script ZIP upload is 5MB.
-
-Otherwise, the maximum supported file size is 1GB.
+* Assets: Maximum supported size is 2GB per asset.
+* Custom Scripts API: Maximum allowed size for a Custom Script ZIP upload is 5MB.
 
 ### Assets
 

src/pages/guides/working-with-datamerge-api/index.md

@@ -120,6 +120,128 @@ repository, and a [pre-signed URL](../../getting-started/concepts/index.md#pre-s
 
 Consult this skeleton [cURL request](https://developer.adobe.com/commerce/webapi/get-started/gs-curl/) for more details.
 
+### Folder Structure and Zipped Output in Data Merge API
+
+The Data Merge API supports organizing your outputs in a structured folder hierarchy, and a zipped folder containing all the outputs that have been created from the successful data merge.
+
+How it works 
+
+- Add a dedicated column in your input CSV for folder names.
+- Prefix the column header with ~ (for example: ~FolderName).
+- Each row value in this column will be used as the folder hierarchy for the output file of that record.
+- Users can opt in for zipped output by setting `outputCompressMediaType`; only `ZIP` is supported for now.
+- Add three input parameters:
+  - **outputCompressMediaType**
+    - **Type:** String
+    - **ENUM:** ["application/zip"]
+    - **Meaning:** The type of compression the user wants (e.g. ZIP, RAR, etc.).
+    - If the user opts for zipped output, the response contains only the zipped output, not individual assets and their links.
+    - If the user does not opt for zipped output, the response is unchanged except that the output path reflects the desired folder hierarchy.
+  - **outputCompressName**
+    - **Type:** String
+    - **Default:** `"Result"`
+    - **Meaning:** Use this value to name the resulting zip.
+  - **outputFolderBaseString**
+    - **Type:** String
+    - **Default:** `mergedFiles`
+    - **Meaning:** Specifies which folder merged files go into and the name of the merged folder; multi-record output files or outputs from empty CSV column values are placed in this folder.
+
+Note:
+- Only one folder name column is allowed. If multiple columns have a ‘~’ prefix, the job will fail.
+- Local or absolute paths (for example, `C:\F1\F2`) are not supported in the `~` column. Provide relative folder hierarchy values (for example, `F1` or `F1\F2`) only. The job will fail if a row uses a local or absolute path.
+
+
+#### Folder Name Constraints
+
+Certain special characters or words are not supported by the platform and are automatically normalized.
+
+- Consecutive unsupported characters (e.g., &lt;, &gt;, :, ", /, \, |, ?, *) are replaced with a single underscore (e.g., `Ab5<>;d` → `Ab5_d`)
+- Windows reserved names (e.g., CON, PRN, AUX, NUL as well as device names like COM1–COM9 and LPT1–LPT9) are wrapped with underscores (e.g., `CON` → `_CON_`)
+- File names (including extension) are limited to 255 characters, with longer names truncated automatically
+
+Here is a sample CSV file demonstrating a column header with prefix ‘~’.
+![Records](./records-foldercsv.png)
+
+Example of input payload which is same as it is currently.
+
+```curl
+curl --location --request POST 'https://indesign.adobe.io/v4/merge-data' \
+--header 'Authorization: Bearer {YOUR_OAUTH_TOKEN}' \
+--header 'x-api-key: {YOUR_API_KEY}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+  "assets": [
+    {
+      "source": {
+        "url": "{PRE-SIGNED_URL}",
+        "storageType": "Azure"
+      },
+      "destination": "dataMergeTemplate.indd"
+    },
+    {
+      "source": {
+        "url": "{PRE-SIGNED_URL}",
+        "storageType": "Azure"
+      },
+      "destination": "FolderNames.csv"
+    }
+  ],
+  "params": {
+    "targetDocument": "dataMergeTemplate.indd",
+    "outputMediaType": "image/png",
+    "outputFolderPath": {OUTPUT_FOLDER_PATH},
+    "outputFileBaseString": "merged",
+    "dataSource": "FolderNames.csv",
+    "recordRange": "All",
+    "outputCompressMediaType": "application/zip", 
+    "outputCompressName": "Works only if outputCompressMediaType is provided",
+    "outputFolderBaseString": "Merged folder name; multi-record outputs and empty ~ values go here. Default: mergedFiles",
+    "hyphenationSettings": {
+      "afterFirst": 3,
+      "beforeLast": 3,
+      "wordsLongerThan": 6,
+      "ladderLimit": 2,
+      "zone": 0.15,
+      "capitalizedWords": false,
+      "lastWord": true,
+      "acrossColumns": false,
+      "dictionarySettings": [
+        {
+          "language": "English: USA",
+          "wordList": ["~word1", "ex~word2"]
+        },
+        {
+          "language": "English: UK",
+          "wordList": ["~word3", "~word4"]
+        }
+      ]
+    }
+  },
+  "outputs": [
+    {
+      "destination": {
+        "url": "{PUT-SIGNED_URL}"
+      },
+      "source": "{OUTPUT_FOLDER_PATH}/{outputs}"
+    }
+  ]
+}'
+```
+
+#### When folder structing is not supported, and output files will move to ‘outputFolderBaseString’
+| outputMediaType                   | params |
+|----------------------------------|--------|
+| JPEG (image/jpeg)                | allowMultipleRecordsPerPage set to true |
+| PNG (image/png)                  | allowMultipleRecordsPerPage set to true |
+| PDF (application/pdf)            | recordsPerFile ≠ 1 and recordRange = "All" |
+|                                  | recordsPerFile ≠ 1 and recordRange = "1-2, 5" |
+|                                  | allowMultipleRecordsPerPage set to true |
+| InDesign (application/x-indesign)| recordsPerFile ≠ 1 and recordRange = "All" |
+|                                  | recordsPerFile ≠ 1 and recordRange = "1-2, 5" |
+|                                  | allowMultipleRecordsPerPage set to true |
+
+**Why:** Folder structuring via the `~` column applies only when the merge job has a clear one-to-one mapping between each data row and its output. In that case, each row’s `~` value defines the folder hierarchy for that record’s output file. If `allowMultipleRecordsPerPage` is true, multiple records can share a page, so per-row folder paths are ambiguous. If `recordsPerFile` is not 1, records are combined into multi-page output documents, so many rows contribute to the same file and per-row folder paths are no longer meaningful. In those situations, folder structuring via the `~` column is not supported for the affected output types, and output files are placed under `outputFolderBaseString` instead.
+
 ### Variable File Naming Support in Data Merge API
 
 The Data Merge API supports variable file naming, allowing you to dynamically assign output file names using values from your input data. 

static/indesignapi.json

@@ -51,7 +51,7 @@
     }
   ],
   "paths": {
-    "/v3/merge-data": {
+    "/v4/merge-data": {
       "post": {
         "summary": "Perform a data merge",
         "description": "Creates InDesign documents or PDFs by merging CSV data with InDesign templates. Supports multiple output formats: JPEG (`image/jpeg`), PNG (`image/png`), PDF (`application/pdf`), and InDesign (`application/x-indesign`).",
@@ -1624,9 +1624,8 @@
                     }
                   },
                   "pagesPerDocument": {
-                    "description": "The maximum number of pages per document.",
-                    "type": "integer",
-                    "default": "By default this would not be applicable."
+                    "description": "Defaults are not applicable here. The maximum number of pages per document.",
+                    "type": "integer"
                   },
                   "removeBlankLines": {
                     "description": "If true, removes blank lines caused by empty fields.",
@@ -1647,6 +1646,24 @@
                     "type": "string",
                     "description": "The path of the output folder.",
                     "default": "A unique temporary folder name would be created."
+                  },
+                  "outputCompressMediaType": {
+                    "type": "string",
+                    "description": "The media type of the output compression.",
+                    "enum": [
+                      "application/zip"
+                    ],
+                    "default": "By default this would not be applicable."
+                  },
+                  "outputCompressName": {
+                    "type": "string",
+                    "description": "The name of the output compression. Works only if outputCompressMediaType is provided",
+                    "default": "Result"
+                  },
+                  "outputFolderBaseString": {
+                    "type": "string",
+                    "description": "Specifies the merged output folder name. Used for multi-record outputs and when the `~` column value is empty.",
+                    "default": "mergedFiles"
                   }
                 }
               }