@celigo/api-specs 0.2.214 → 0.2.216

package/dist/ai-agent.yml

@@ -23,9 +23,11 @@ tags:
 
       Three built-in providers — OpenAI (via the Responses API), Google Gemini (via
       LiteLLM), and Anthropic Claude (via LiteLLM) — run on platform-managed
-      credentials or, with a `_connectionId`, on your own key (BYOK). Catalog
-      providers — Mistral, xAI, Hugging Face, DeepSeek, Cohere, and Groq — use one generic
-      flat configuration format and always run on a BYOK connection.
+      credentials or, with a `_connectionId`, on your own key (BYOK). Every other
+      provider is a catalog provider — Mistral, xAI, Hugging Face, DeepSeek, Cohere, Groq,
+      Together AI, Azure OpenAI, Fireworks AI, AWS Bedrock, NVIDIA NIM, Ollama Cloud and
+      Google Vertex AI today, with new rows seeded without a platform release — and uses
+      one generic flat configuration format and always runs on a BYOK connection.
 
       Every model carries a lifecycle in the platform's model catalog (`active`,
       `deprecated`, `retired`, plus an availability switch). The save and every run
@@ -133,12 +135,16 @@ paths:
         Creates a new AI agent import. The provider decides the configuration
         format: `aiAgent.openai` for OpenAI, `aiAgent.litellm` for Gemini and
         Anthropic Claude, or the generic flat format (`aiAgent.model`,
-        `aiAgent.modelOptions`, …) for the catalog providers Mistral, xAI,
-        Hugging Face, DeepSeek, Cohere, and Groq — a block that does not match the
-        provider is rejected. For a built-in provider, omit `_connectionId` to
-        use platform-managed credentials or include it for BYOK; a catalog
-        provider needs a BYOK connection to save — without one the request
-        fails with 422 `connection_required` on `_connectionId`.
+        `aiAgent.modelOptions`, …) for every other provider (the catalog
+        providers — Mistral, xAI, Hugging Face, DeepSeek, Cohere, Groq, Together
+        AI, Azure OpenAI, Fireworks AI, AWS Bedrock, NVIDIA NIM, Ollama Cloud and
+        Google Vertex AI today) — a block that does not match the provider is
+        rejected. For a built-in provider, omit `_connectionId` to use
+        platform-managed credentials or include it for BYOK; a catalog provider
+        needs a BYOK connection to save — without one the request fails with 422
+        on `aiAgent.model`: `ai_model_not_available` for a catalog-listed model,
+        `ai_model_not_in_catalog` for an id the catalog does not list (the model
+        catalog check answers before any `connection_required`).
       operationId: createAiAgent
       tags:
         - AI Agents
@@ -1047,8 +1053,10 @@ components:
           - **openai**: OpenAI models (GPT-4.1, GPT-5, etc.). Configure via the `openai` object.
           - **gemini**: Google Gemini models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.gemini`.
           - **anthropic**: Anthropic Claude models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.anthropic`.
-        - **Catalog providers** — `mistral`, `xai`, `huggingface`, `deepseek`, `cohere`, `groq`. Added
-          as catalog data rather than platform code, they share one generic flat format:
+        - **Catalog providers** — every other value of `provider` (Mistral, xAI, Hugging Face,
+          DeepSeek, Cohere, Groq, Together AI, Azure OpenAI, Fireworks AI, AWS Bedrock, NVIDIA NIM,
+          Ollama Cloud and Google Vertex AI today; the catalog grows without a platform release).
+          Added as catalog data rather than platform code, they share one generic flat format:
           `model`, `modelOptions`, `instructions`, `output`, and the `tools` / `prompts` /
           `resources` arrays directly on this object.
 
@@ -1094,26 +1102,45 @@ components:
             - deepseek
             - cohere
             - groq
+            - together_ai
+            - azure_ai
+            - fireworks_ai
+            - bedrock
+            - nvidia_nim
+            - ollama_chat
+            - vertex_ai
           x-enumDescriptions:
-            openai: Use OpenAI models via the OpenAI Responses API (built-in; `openai` block).
-            gemini: Use Google Gemini models via the LiteLLM proxy (built-in; `litellm` block).
-            anthropic: Use Anthropic Claude models via the LiteLLM proxy (built-in; `litellm` block).
-            mistral: Use Mistral models (catalog provider; generic flat format, BYOK).
-            xai: Use xAI Grok models (catalog provider; generic flat format, BYOK).
-            huggingface: Use Hugging Face inference endpoint models (catalog provider; generic flat format, BYOK).
-            deepseek: Use DeepSeek models (catalog provider; generic flat format, BYOK).
-            cohere: Use Cohere models (catalog provider; generic flat format, BYOK).
-            groq: Use Groq-hosted models (catalog provider; generic flat format, BYOK).
-          description: AI provider to use.
+            openai: Use OpenAI models via the OpenAI Responses API (built-in; `openai` block; Celigo AI or BYOK)
+            gemini: Use Google Gemini models via the LiteLLM proxy (built-in; `litellm` block; Celigo AI or BYOK)
+            anthropic: Use Anthropic Claude models via the LiteLLM proxy (built-in; `litellm` block; Celigo AI or BYOK)
+            mistral: Use Mistral models (catalog provider; generic flat format, BYOK)
+            xai: Use xAI Grok models (catalog provider; generic flat format, BYOK)
+            huggingface: Use Hugging Face inference endpoint models (catalog provider; generic flat format, BYOK)
+            deepseek: Use DeepSeek models (catalog provider; generic flat format, BYOK)
+            cohere: Use Cohere models (catalog provider; generic flat format, BYOK)
+            groq: Use Groq-hosted models (catalog provider; generic flat format, BYOK)
+            together_ai: Use models served by Together AI (catalog provider; generic flat format, BYOK)
+            azure_ai: Use deployments on an Azure AI Foundry / Azure OpenAI resource — `model` is the deployment name (catalog provider; generic flat format, BYOK)
+            fireworks_ai: Use models served by Fireworks AI (catalog provider; generic flat format, BYOK)
+            bedrock: Use AWS Bedrock models through cross-region inference profile ids such as `global.anthropic.claude-sonnet-4-6` (catalog provider; generic flat format, BYOK)
+            nvidia_nim: Use models served by NVIDIA NIM (catalog provider; generic flat format, BYOK)
+            ollama_chat: Use models served by Ollama Cloud (catalog provider; generic flat format, BYOK)
+            vertex_ai: Use Gemini models on Google Vertex AI with the customer's own GCP project (catalog provider; generic flat format, BYOK)
+          description: |-
+            AI provider to use. Built-in providers run on Celigo AI credentials or on a
+            BYOK connection; every other provider is a catalog row that runs only on a BYOK
+            connection. The catalog is data — a provider can be added without a platform
+            release, and `GET /api/aiproviders` lists the rows currently offered.
           x-celigo-ai-guidance:
             - |-
               The provider decides the configuration format, and the server rejects a
               mismatch with 422 `invalid_provider_config_format`: `openai` needs the
               `openai` block, `gemini` and `anthropic` need the `litellm` block (Gemini- or
-              Claude-specific settings under `litellm._overrides`), and the catalog
-              providers (`mistral`, `xai`, `huggingface`, `deepseek`, `cohere`, `groq`) need the
-              generic flat format — `model` and `modelOptions` directly on this object,
-              never an `openai` or `litellm` block.
+              Claude-specific settings under `litellm._overrides`), and every other
+              provider (the catalog providers) needs the generic flat format — `model` and
+              `modelOptions` directly on this object, never an `openai` or `litellm` block.
+              Switching across that boundary replaces the whole configuration in the target
+              format; nothing is translated field by field.
             - |-
               Catalog providers are BYOK-only, and the save enforces it through the model
               catalog: without a `_connectionId` the agent fails to save with 422
@@ -1122,6 +1149,18 @@ components:
               configuration.") — the model is a catalog row that is not offered on
               platform-managed credentials. Attach an HTTP connection to the vendor's API
               (token auth) before saving a catalog-provider agent.
+            - |-
+              Without a connection, a provider the catalog does not list is refused at the
+              model check — 422 `ai_model_not_in_catalog` on `aiAgent.model` — so the
+              message names the model, not the provider. Check the provider against the
+              catalog before blaming the model.
+            - |-
+              For `azure_ai` and `bedrock` the vendor-specific settings ride the BYOK
+              connection, not this object: an optional connection `baseURI` (the vendor
+              endpoint the connector asks for), and connection settings forwarded to the
+              vendor — Azure's `apiVersion`, Bedrock's `awsRegionName`. `bedrock`
+              authenticates with a Bedrock API key (no IAM role); for `azure_ai`, `model` is
+              the deployment name.
         model:
           type: string
           description: |-
@@ -1594,13 +1633,27 @@ components:
                       web_search: Search the web for real-time information.
                       mcp: Connect to an MCP server for additional external tools.
                       image_generation: Generate images using an AI image model.
-                      code_execution: 'Enable OpenAI''s built-in code-execution tool; carries no configuration block, send `{type: code_execution}` only'
+                      code_execution: 'Let the model write and run code in OpenAI''s sandbox on a BYOK agent; carries no configuration block, send `{type: code_execution}` only'
                       tool: Reference a reusable Celigo Tool resource.
                     description: |-
                       Type of tool. Every type except `code_execution` is configured through the
                       sibling object of the same name; OpenAI spells this one `code_execution`, while
                       the Gemini and Anthropic overrides spell theirs `codeExecution` — the other spelling
-                      fails with 422 `enum`.
+                      fails with 422 `enum`. Code execution runs only on a BYOK agent and only on
+                      models that support it: the code runs in OpenAI's sandbox with no outbound
+                      network access, the session lasts one hour, and each execution is billed as an
+                      AI Action to the connection's OpenAI account rather than as Celigo AI credits.
+                    x-celigo-ai-guidance:
+                      - |-
+                        Add `code_execution` only when the agent has a `_connectionId`. The save does
+                        not check the credential type, but every run and preview of an agent on
+                        Celigo-managed credentials is refused with `Code Execution requires a BYOK
+                        connection.` — switch the agent to a BYOK connection or leave the tool out.
+                      - |-
+                        Send the tool as `{type: code_execution}` with no other key — a sandbox or
+                        options object on it is rejected. Check that the chosen model supports code
+                        execution before adding it; the platform does not verify that at save and
+                        the UI hides the tool for models that lack it.
                   webSearch:
                     type: object
                     description: Web search configuration (empty object to enable)
@@ -1954,12 +2007,28 @@ components:
                               googleSearch: Use Google Search for real-time information grounding.
                               urlContext: Retrieve and use content from specified URLs.
                               fileSearch: Search through previously uploaded files.
-                              codeExecution: 'Enable Gemini''s built-in code-execution tool; carries no configuration block, send `{type: codeExecution}` only'
+                              codeExecution: 'Let the model write and run code in Gemini''s sandbox on a BYOK agent; carries no configuration block, send `{type: codeExecution}` only'
                               mcp: Connect to an MCP server for additional external tools.
                               tool: Reference a reusable Celigo Tool resource.
                             description: |-
                               Type of Gemini tool. `codeExecution` is the Gemini spelling — `code_execution`
-                              fails with 422 `enum`.
+                              fails with 422 `enum`. Code execution runs only on a BYOK agent and only on
+                              models that support it (not on `gemini-2.5-flash-image`): the code runs in
+                              Gemini's sandbox with no outbound network access for up to 30 seconds per
+                              execution and at most 5 executions per API call (the limit resets each turn),
+                              and each execution is billed as an AI Action to the connection's Google
+                              account rather than as Celigo AI credits.
+                            x-celigo-ai-guidance:
+                              - |-
+                                Add `codeExecution` only when the agent has a `_connectionId`. The save does
+                                not check the credential type, but every run and preview of an agent on
+                                Celigo-managed credentials is refused with `Code Execution requires a BYOK
+                                connection.` — switch the agent to a BYOK connection or leave the tool out.
+                              - |-
+                                Send the tool as `{type: codeExecution}` with no other key — any other key on
+                                it is rejected. Check that the chosen model supports code execution before
+                                adding it; the platform does not verify that at save and the UI hides the
+                                tool for models that lack it.
                           googleSearch:
                             type: object
                             description: Google Search configuration (empty object to enable)
@@ -2291,10 +2360,26 @@ components:
                               tool: Reference a reusable Celigo Tool resource.
                               mcp: Connect to an MCP server for additional external tools.
                               webSearch: Search the web for real-time information.
-                              codeExecution: 'Enable Anthropic''s built-in code-execution tool; carries no configuration block, send `{type: codeExecution}` only'
+                              codeExecution: 'Let the model write and run code in Anthropic''s sandbox on a BYOK agent (beta); carries no configuration block, send `{type: codeExecution}` only'
                             description: |-
                               Type of Claude tool. `codeExecution` is the Anthropic spelling — `code_execution`
-                              fails with 422 `enum`.
+                              fails with 422 `enum`. Code execution (beta on Anthropic) runs only on a BYOK
+                              agent and only on models that support it: the code runs per API call in
+                              Anthropic's sandbox (Python 3.11 with pandas, numpy and matplotlib) with no
+                              outbound network access and no state kept between turns, and each execution is
+                              billed as an AI Action to the connection's Anthropic account rather than as
+                              Celigo AI credits.
+                            x-celigo-ai-guidance:
+                              - |-
+                                Add `codeExecution` only when the agent has a `_connectionId`. The save does
+                                not check the credential type, but every run and preview of an agent on
+                                Celigo-managed credentials is refused with `Code Execution requires a BYOK
+                                connection.` — switch the agent to a BYOK connection or leave the tool out.
+                              - |-
+                                Send the tool as `{type: codeExecution}` with no other key — any other key on
+                                it is rejected. Check that the chosen model supports code execution before
+                                adding it; the platform does not verify that at save and the UI hides the
+                                tool for models that lack it.
                           tool:
                             type: object
                             description: Reference to a Celigo Tool resource, used when type is "tool".
@@ -2511,6 +2596,13 @@ components:
                   - deepseek
                   - cohere
                   - groq
+                  - together_ai
+                  - azure_ai
+                  - fireworks_ai
+                  - bedrock
+                  - nvidia_nim
+                  - ollama_chat
+                  - vertex_ai
             required:
               - provider
           then:
@@ -5679,12 +5771,16 @@ components:
                     - |-
                       On a grouped record (the export groups rows, so the record is an
                       array) only `create` can author output — build it from the rows with
-                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`
+                      (`$.rows[0].field` and `$.rows[*]` with `inputContext: envelope`).
                       `modify` has no object to overlay onto an array: the record passes
-                      through untouched and the processor reports success. Either mode
-                      reshapes the inside of one record; neither changes how many records
-                      the page carries (that is the export's `preSavePage` hook) or whether
-                      the export groups at all (that is its grouping setting).
+                      through untouched and the processor reports success. Paths written
+                      for one object record (`$.field`, an entry `$.lines[*]`) resolve
+                      nothing there, so `create` returns `{}` for each record, also with
+                      no error (live, 2026-10-30). Either mode reshapes the inside of one
+                      record; neither changes how many records the page carries (that is
+                      the export's `preSavePage` hook) or whether the export groups at all
+                      (that is its grouping setting).
                   examples:
                     - create
                     - modify
@@ -5749,8 +5845,8 @@ components:
                     - record
                     - envelope
                   x-enumDescriptions:
-                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
-                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
+                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment; a grouped record is the array of rows, `$[0].field`) — the default when absent.
+                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), and a grouped record sits under `rows` instead (`$.rows[0].field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
                   description: |
                     Controls the JSON shape the transformTwoDotZero processor
                     evaluates `mappings[].extract` JSONPath values against at
@@ -5766,24 +5862,38 @@ components:
                         processor sees the FLAT record as its evaluation root.
                         `mappings[].extract` JSONPath MUST anchor directly at
                         `$` with NO `record.` segment — e.g. `"$.orderId"`,
-                        `"$.customer.email"`; PLACEHOLDER extracts use
+                        `"$.customer.email"` on an object record, `"$[0].orderId"`
+                        on a grouped one; PLACEHOLDER extracts use
                         `"$.PLACEHOLDER_<field>"`.
                         This is the dominant Celigo idiom and the right choice for new transforms.
                       - `envelope`: the processor sees a wrapped object
                         `{record: {...}, job, testMode, settings, headers,
                         queryParams}` (plus `fileMeta` on file-provider steps).
                         `mappings[].extract` JSONPath MUST include the
-                        `record.` segment for record fields — e.g.
-                        `"$.record.orderId"` — and reads `headers` and
+                        `record.` segment for an object record's fields — e.g.
+                        `"$.record.orderId"`; a grouped record sits under `rows`
+                        instead (`"$.rows[0].orderId"`) — and reads `headers` and
                         `queryParams` beside it (`$.headers['X-Id']`);
                         PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
                         Pick this only when the transform was authored against
                         the envelope shape on purpose.
                     - |-
-                      Handlebars expressions inside `extract`
-                      (`{{record.field}}`, `{{dateFormat ... record.field}}`)
-                      ALWAYS reference the `record` root regardless of
+                      Handlebars expressions inside `extract` reference the
+                      `record` root on an object record (`{{record.field}}`,
+                      `{{dateFormat ... record.field}}`) and `rows` on a
+                      grouped one (`{{rows.0.field}}`), regardless of
                       `inputContext` — only JSONPath anchoring flips.
+                    - |-
+                      ## Grouped records
+
+                      When the export groups rows, each record is an array of
+                      rows. In `record` mode JSONPath roots at that array
+                      (`$[0].field`, `$[*]`); `envelope` binds it as `rows`,
+                      not `record` — `$.rows[0].field`, and an entry
+                      `$.rows[*]` whose children read `$.rows.field` — while
+                      `$.record[0].field` and `$.record[*]` resolve nothing,
+                      with no error (live, 2026-10-30). Handlebars extracts
+                      read it as `rows` in both modes (`{{rows.0.field}}`).
                     - |-
                       In `envelope` mode the output is still a bare record: a
                       `modify` transform returns the record with its mapped
@@ -5804,7 +5914,8 @@ components:
                         ``mappings[].extract`` JSONPath values MUST anchor
                         directly at ``$`` with NO ``record.`` segment — for
                         example ``"$.orderId"`` or
-                        ``"$.customer.email"``.  PLACEHOLDER extracts use
+                        ``"$.customer.email"`` on an object record, and
+                        ``"$[0].orderId"`` on a grouped one.  PLACEHOLDER extracts use
                         ``"$.PLACEHOLDER_<field>"``.  This is the dominant
                         Celigo idiom and the right choice for new transforms.
 
@@ -5816,9 +5927,10 @@ components:
                         ``record``) — the
                         same runtime-context envelope Handlebars / SQL /
                         GraphQL templates render against.  ``mappings[].extract``
-                        JSONPath values for record fields MUST include the
+                        JSONPath values for an object record's fields MUST include the
                         ``record.`` segment — for example ``"$.record.orderId"``
-                        or ``"$.record.customer.email"`` — while ``headers`` and
+                        or ``"$.record.customer.email"``; a grouped record's rows
+                        sit under ``rows`` instead (``"$.rows[0].orderId"``) — while ``headers`` and
                         ``queryParams`` are read beside it
                         (``"$.headers['X-Id']"``).  PLACEHOLDER extracts
                         use ``"$.record.PLACEHOLDER_<field>"``.  Pick this
@@ -5831,8 +5943,9 @@ components:
 
                       Handlebars expressions inside ``extract``
                       (``{{record.field}}``,
-                      ``{{dateFormat ... record.field}}``, etc.) ALWAYS
-                      reference the runtime context's ``record`` root
+                      ``{{dateFormat ... record.field}}``, etc.) reference the
+                      runtime context's ``record`` root on an object record,
+                      and ``rows`` (``{{rows.0.field}}``) on a grouped one,
                       regardless of ``inputContext`` — the Handlebars runtime
                       always sees the wrapped envelope.  Only JSONPath
                       behavior flips with this field.
@@ -6056,8 +6169,10 @@ components:
         `aiAgent.provider` to choose the LLM backend, then configure the matching format:
         `aiAgent.openai` for OpenAI, `aiAgent.litellm` for Gemini and Anthropic Claude
         (with provider-specific settings under `aiAgent.litellm._overrides`), or the
-        generic flat format (`aiAgent.model`, `aiAgent.modelOptions`, …) for the catalog
-        providers Mistral, xAI, Hugging Face, DeepSeek, Cohere, and Groq.
+        generic flat format (`aiAgent.model`, `aiAgent.modelOptions`, …) for every other
+        provider — the catalog providers (Mistral, xAI, Hugging Face, DeepSeek, Cohere, Groq,
+        Together AI, Azure OpenAI, Fireworks AI, AWS Bedrock, NVIDIA NIM, Ollama Cloud and
+        Google Vertex AI today; the catalog grows without a platform release).
       properties:
         name:
           type: string
@@ -6079,10 +6194,11 @@ components:
           description: |-
             Connection for BYOK (bring your own key) — an HTTP connection to the vendor's API.
             Optional for the built-in providers (`openai`, `gemini`, `anthropic`), which run on
-            platform-managed credentials when it is omitted. Catalog providers (`mistral`, `xai`,
-            `huggingface`, `deepseek`, `cohere`, `groq`) have no platform-managed credentials: the save
-            requires it — without one the agent fails to save with 422 `connection_required` on
-            `_connectionId`.
+            platform-managed credentials when it is omitted. Catalog providers (every other value
+            of `provider`) have no platform-managed credentials: the save requires it — without
+            one the agent fails to save with 422 on `aiAgent.model` (`ai_model_not_available` for
+            a catalog-listed model, `ai_model_not_in_catalog` for an id the catalog does not
+            list; the model catalog check answers before any `connection_required`).
           examples:
             - 662aaa6576bf4040548dbbe4
         _integrationId:

package/dist/api.yml

@@ -5263,12 +5263,16 @@ components:
                     - |-
                       On a grouped record (the export groups rows, so the record is an
                       array) only `create` can author output — build it from the rows with
-                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`
+                      (`$.rows[0].field` and `$.rows[*]` with `inputContext: envelope`).
                       `modify` has no object to overlay onto an array: the record passes
-                      through untouched and the processor reports success. Either mode
-                      reshapes the inside of one record; neither changes how many records
-                      the page carries (that is the export's `preSavePage` hook) or whether
-                      the export groups at all (that is its grouping setting).
+                      through untouched and the processor reports success. Paths written
+                      for one object record (`$.field`, an entry `$.lines[*]`) resolve
+                      nothing there, so `create` returns `{}` for each record, also with
+                      no error (live, 2026-10-30). Either mode reshapes the inside of one
+                      record; neither changes how many records the page carries (that is
+                      the export's `preSavePage` hook) or whether the export groups at all
+                      (that is its grouping setting).
                   examples:
                     - create
                     - modify
@@ -5333,8 +5337,8 @@ components:
                     - record
                     - envelope
                   x-enumDescriptions:
-                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
-                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
+                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment; a grouped record is the array of rows, `$[0].field`) — the default when absent.
+                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), and a grouped record sits under `rows` instead (`$.rows[0].field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
                   description: |
                     Controls the JSON shape the transformTwoDotZero processor
                     evaluates `mappings[].extract` JSONPath values against at
@@ -5350,24 +5354,38 @@ components:
                         processor sees the FLAT record as its evaluation root.
                         `mappings[].extract` JSONPath MUST anchor directly at
                         `$` with NO `record.` segment — e.g. `"$.orderId"`,
-                        `"$.customer.email"`; PLACEHOLDER extracts use
+                        `"$.customer.email"` on an object record, `"$[0].orderId"`
+                        on a grouped one; PLACEHOLDER extracts use
                         `"$.PLACEHOLDER_<field>"`.
                         This is the dominant Celigo idiom and the right choice for new transforms.
                       - `envelope`: the processor sees a wrapped object
                         `{record: {...}, job, testMode, settings, headers,
                         queryParams}` (plus `fileMeta` on file-provider steps).
                         `mappings[].extract` JSONPath MUST include the
-                        `record.` segment for record fields — e.g.
-                        `"$.record.orderId"` — and reads `headers` and
+                        `record.` segment for an object record's fields — e.g.
+                        `"$.record.orderId"`; a grouped record sits under `rows`
+                        instead (`"$.rows[0].orderId"`) — and reads `headers` and
                         `queryParams` beside it (`$.headers['X-Id']`);
                         PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
                         Pick this only when the transform was authored against
                         the envelope shape on purpose.
                     - |-
-                      Handlebars expressions inside `extract`
-                      (`{{record.field}}`, `{{dateFormat ... record.field}}`)
-                      ALWAYS reference the `record` root regardless of
+                      Handlebars expressions inside `extract` reference the
+                      `record` root on an object record (`{{record.field}}`,
+                      `{{dateFormat ... record.field}}`) and `rows` on a
+                      grouped one (`{{rows.0.field}}`), regardless of
                       `inputContext` — only JSONPath anchoring flips.
+                    - |-
+                      ## Grouped records
+
+                      When the export groups rows, each record is an array of
+                      rows. In `record` mode JSONPath roots at that array
+                      (`$[0].field`, `$[*]`); `envelope` binds it as `rows`,
+                      not `record` — `$.rows[0].field`, and an entry
+                      `$.rows[*]` whose children read `$.rows.field` — while
+                      `$.record[0].field` and `$.record[*]` resolve nothing,
+                      with no error (live, 2026-10-30). Handlebars extracts
+                      read it as `rows` in both modes (`{{rows.0.field}}`).
                     - |-
                       In `envelope` mode the output is still a bare record: a
                       `modify` transform returns the record with its mapped
@@ -5388,7 +5406,8 @@ components:
                         ``mappings[].extract`` JSONPath values MUST anchor
                         directly at ``$`` with NO ``record.`` segment — for
                         example ``"$.orderId"`` or
-                        ``"$.customer.email"``.  PLACEHOLDER extracts use
+                        ``"$.customer.email"`` on an object record, and
+                        ``"$[0].orderId"`` on a grouped one.  PLACEHOLDER extracts use
                         ``"$.PLACEHOLDER_<field>"``.  This is the dominant
                         Celigo idiom and the right choice for new transforms.
 
@@ -5400,9 +5419,10 @@ components:
                         ``record``) — the
                         same runtime-context envelope Handlebars / SQL /
                         GraphQL templates render against.  ``mappings[].extract``
-                        JSONPath values for record fields MUST include the
+                        JSONPath values for an object record's fields MUST include the
                         ``record.`` segment — for example ``"$.record.orderId"``
-                        or ``"$.record.customer.email"`` — while ``headers`` and
+                        or ``"$.record.customer.email"``; a grouped record's rows
+                        sit under ``rows`` instead (``"$.rows[0].orderId"``) — while ``headers`` and
                         ``queryParams`` are read beside it
                         (``"$.headers['X-Id']"``).  PLACEHOLDER extracts
                         use ``"$.record.PLACEHOLDER_<field>"``.  Pick this
@@ -5415,8 +5435,9 @@ components:
 
                       Handlebars expressions inside ``extract``
                       (``{{record.field}}``,
-                      ``{{dateFormat ... record.field}}``, etc.) ALWAYS
-                      reference the runtime context's ``record`` root
+                      ``{{dateFormat ... record.field}}``, etc.) reference the
+                      runtime context's ``record`` root on an object record,
+                      and ``rows`` (``{{rows.0.field}}``) on a grouped one,
                       regardless of ``inputContext`` — the Handlebars runtime
                       always sees the wrapped envelope.  Only JSONPath
                       behavior flips with this field.

package/dist/asynchelper.yml

@@ -3158,12 +3158,16 @@ components:
                     - |-
                       On a grouped record (the export groups rows, so the record is an
                       array) only `create` can author output — build it from the rows with
-                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`
+                      (`$.rows[0].field` and `$.rows[*]` with `inputContext: envelope`).
                       `modify` has no object to overlay onto an array: the record passes
-                      through untouched and the processor reports success. Either mode
-                      reshapes the inside of one record; neither changes how many records
-                      the page carries (that is the export's `preSavePage` hook) or whether
-                      the export groups at all (that is its grouping setting).
+                      through untouched and the processor reports success. Paths written
+                      for one object record (`$.field`, an entry `$.lines[*]`) resolve
+                      nothing there, so `create` returns `{}` for each record, also with
+                      no error (live, 2026-10-30). Either mode reshapes the inside of one
+                      record; neither changes how many records the page carries (that is
+                      the export's `preSavePage` hook) or whether the export groups at all
+                      (that is its grouping setting).
                   examples:
                     - create
                     - modify
@@ -3228,8 +3232,8 @@ components:
                     - record
                     - envelope
                   x-enumDescriptions:
-                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
-                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
+                    record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment; a grouped record is the array of rows, `$[0].field`) — the default when absent.
+                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), and a grouped record sits under `rows` instead (`$.rows[0].field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
                   description: |
                     Controls the JSON shape the transformTwoDotZero processor
                     evaluates `mappings[].extract` JSONPath values against at
@@ -3245,24 +3249,38 @@ components:
                         processor sees the FLAT record as its evaluation root.
                         `mappings[].extract` JSONPath MUST anchor directly at
                         `$` with NO `record.` segment — e.g. `"$.orderId"`,
-                        `"$.customer.email"`; PLACEHOLDER extracts use
+                        `"$.customer.email"` on an object record, `"$[0].orderId"`
+                        on a grouped one; PLACEHOLDER extracts use
                         `"$.PLACEHOLDER_<field>"`.
                         This is the dominant Celigo idiom and the right choice for new transforms.
                       - `envelope`: the processor sees a wrapped object
                         `{record: {...}, job, testMode, settings, headers,
                         queryParams}` (plus `fileMeta` on file-provider steps).
                         `mappings[].extract` JSONPath MUST include the
-                        `record.` segment for record fields — e.g.
-                        `"$.record.orderId"` — and reads `headers` and
+                        `record.` segment for an object record's fields — e.g.
+                        `"$.record.orderId"`; a grouped record sits under `rows`
+                        instead (`"$.rows[0].orderId"`) — and reads `headers` and
                         `queryParams` beside it (`$.headers['X-Id']`);
                         PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
                         Pick this only when the transform was authored against
                         the envelope shape on purpose.
                     - |-
-                      Handlebars expressions inside `extract`
-                      (`{{record.field}}`, `{{dateFormat ... record.field}}`)
-                      ALWAYS reference the `record` root regardless of
+                      Handlebars expressions inside `extract` reference the
+                      `record` root on an object record (`{{record.field}}`,
+                      `{{dateFormat ... record.field}}`) and `rows` on a
+                      grouped one (`{{rows.0.field}}`), regardless of
                       `inputContext` — only JSONPath anchoring flips.
+                    - |-
+                      ## Grouped records
+
+                      When the export groups rows, each record is an array of
+                      rows. In `record` mode JSONPath roots at that array
+                      (`$[0].field`, `$[*]`); `envelope` binds it as `rows`,
+                      not `record` — `$.rows[0].field`, and an entry
+                      `$.rows[*]` whose children read `$.rows.field` — while
+                      `$.record[0].field` and `$.record[*]` resolve nothing,
+                      with no error (live, 2026-10-30). Handlebars extracts
+                      read it as `rows` in both modes (`{{rows.0.field}}`).
                     - |-
                       In `envelope` mode the output is still a bare record: a
                       `modify` transform returns the record with its mapped
@@ -3283,7 +3301,8 @@ components:
                         ``mappings[].extract`` JSONPath values MUST anchor
                         directly at ``$`` with NO ``record.`` segment — for
                         example ``"$.orderId"`` or
-                        ``"$.customer.email"``.  PLACEHOLDER extracts use
+                        ``"$.customer.email"`` on an object record, and
+                        ``"$[0].orderId"`` on a grouped one.  PLACEHOLDER extracts use
                         ``"$.PLACEHOLDER_<field>"``.  This is the dominant
                         Celigo idiom and the right choice for new transforms.
 
@@ -3295,9 +3314,10 @@ components:
                         ``record``) — the
                         same runtime-context envelope Handlebars / SQL /
                         GraphQL templates render against.  ``mappings[].extract``
-                        JSONPath values for record fields MUST include the
+                        JSONPath values for an object record's fields MUST include the
                         ``record.`` segment — for example ``"$.record.orderId"``
-                        or ``"$.record.customer.email"`` — while ``headers`` and
+                        or ``"$.record.customer.email"``; a grouped record's rows
+                        sit under ``rows`` instead (``"$.rows[0].orderId"``) — while ``headers`` and
                         ``queryParams`` are read beside it
                         (``"$.headers['X-Id']"``).  PLACEHOLDER extracts
                         use ``"$.record.PLACEHOLDER_<field>"``.  Pick this
@@ -3310,8 +3330,9 @@ components:
 
                       Handlebars expressions inside ``extract``
                       (``{{record.field}}``,
-                      ``{{dateFormat ... record.field}}``, etc.) ALWAYS
-                      reference the runtime context's ``record`` root
+                      ``{{dateFormat ... record.field}}``, etc.) reference the
+                      runtime context's ``record`` root on an object record,
+                      and ``rows`` (``{{rows.0.field}}``) on a grouped one,
                       regardless of ``inputContext`` — the Handlebars runtime
                       always sees the wrapped envelope.  Only JSONPath
                       behavior flips with this field.