@celigo/api-specs 0.2.79 → 0.2.81

package/dist/agent.yml

@@ -600,6 +600,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/ai-agent.yml

@@ -3869,20 +3869,48 @@ components:
         extracts evaluate against that envelope:
 
         - **Lookup steps**: `{"statusCode": 200, "data": [<result records>],
-          "errors": []}` — `data` holds the records the lookup returned, so
-          extracts must start from it: `data[0].name` copies a field of the
-          first result, `data` copies the whole result array. A bare
-          result-record field name (e.g. `name`) resolves to nothing and merges
-          nothing.
+          "errors": []}` — `data` holds the records the lookup step returns,
+          AFTER the export's own `transform` and output `filter` have run, so
+          extracts must start from it and name transformed fields by their
+          transformed name: `data[0].name` copies a field of the first result,
+          `data` copies the whole result array. A bare result-record field name
+          (e.g. `name`) resolves to nothing and merges nothing, and so does the
+          raw response path a transform consumed.
         - **Import steps**: `{"id": "<destination record id>", "statusCode": 200,
-          "ignored": false, "errors": [], "_json": <raw destination response>}` —
-          use `id` for the destination-assigned id and `_json.<path>` for fields
-          inside the destination's response body. The full envelope (including
-          `id`) is present on real runs and in flow-builder previews; flow TEST
-          runs never execute imports, and their mock-built envelope carries no
-          `id` — an `extract: "id"` merges nothing in a test run even though it
-          works on real runs.
+          "ignored": false, "errors": [], "_json": <raw destination response>,
+          ...<response body fields flattened at the root>}` — use `id` for the
+          destination-assigned id and `_json.<path>` (or the flattened
+          `<path>`) for fields inside the destination's response body. The full
+          envelope (including `id`) is present on real runs and in flow-builder
+          previews; flow TEST runs never execute imports, and their mock-built
+          envelope carries no `id` — an `extract: "id"` merges nothing in a test
+          run even though it works on real runs.
+
+        An `extract` may also be a Handlebars expression. It evaluates against
+        the same envelope as a plain path, so every path inside `{{ }}` starts
+        where the plain paths start — `{{data.0.name}}`,
+        `{{#compare data.0.count "==" 1}}yes{{else}}no{{/compare}}`,
+        `{{#if data.length}}found{{/if}}` on a lookup; `{{_json.order.id}}` or
+        `{{id}}` on an import. Index arrays with dots inside Handlebars
+        (`data.0.name` or `data.[0].name`; `data[0].name` renders nothing), and
+        expect a string result (`"1"`, `"false"`). There is no `record` object in
+        this context: `{{record.<anything>}}` renders nothing. Prefer a plain
+        path when the value is simply copied.
       x-celigo-ai-guidance:
+        - |-
+          Handlebars is allowed in `extract` but only rooted at the envelope —
+          `{{data.0.x}}` on a lookup, `{{_json.x}}` / `{{id}}` on an import. The
+          `record.` root belongs to import-mapping templates; here every
+          `{{record.…}}` form renders nothing, silently, and `{{data[0].x}}`
+          (bracket index inside Handlebars) renders nothing too. Use Handlebars
+          only for a derived value (a flag, a concatenation); copy values with a
+          plain path.
+        - |-
+          A lookup's `data[]` is the step's output after its `transform` and
+          `filter`, so author extracts against the transformed records — never
+          against the raw response the transform consumed, and never against a
+          saved `mockOutput` as stored (it is the raw response; the transform
+          runs on top of it in a test run).
         - |-
           Send `fields` and `lists` as bare arrays, exactly as GET returns them.
           Never wrap either in an object (e.g. `"fields": {"type": [...]}`): the
@@ -3924,22 +3952,29 @@ components:
             properties:
               extract:
                 type: string
+                x-celigo-agent:
+                  - handlebars
                 description: |
                   Path within the canonical response envelope to copy the value
-                  from. For lookup steps, paths start from the envelope's `data`
-                  array (`data[0].x` and `data.0.x` are equivalent; `data` alone
-                  copies every result); for import steps, use the envelope fields
-                  `id`, `statusCode`, `ignored`, or `_json.<path>` for the raw
-                  response body. Paths that skip the envelope (bare response
-                  field names) resolve to nothing, and a `[*]` wildcard is not
-                  honored here — `data[*].x` merges nothing; iterate arrays with
-                  `lists` instead.
+                  from, or a Handlebars expression over that same envelope. For
+                  lookup steps, paths start from the envelope's `data` array
+                  (`data[0].x` and `data.0.x` are equivalent; `data` alone
+                  copies every result) — a lookup result field written without
+                  the `data` prefix resolves to nothing. For import steps, use
+                  the envelope fields `id`, `statusCode`, `ignored`, `_json.<path>`
+                  for the raw response body, or the body field itself at the
+                  envelope root (`orderNumber` and `_json.orderNumber` read the
+                  same value). A `[*]` wildcard is not honored here — `data[*].x`
+                  merges nothing; iterate arrays with `lists` instead. Inside
+                  Handlebars, index with dots (`{{data.0.x}}`, never
+                  `{{data[0].x}}`) and never use a `record.` root.
                 examples:
                   - data[0].customer.name
                   - data.0.fields.Product Name
                   - data
                   - id
                   - _json.orderNumber
+                  - '{{#if data.length}}found{{else}}missing{{/if}}'
               generate:
                 type: string
                 description: |
@@ -5425,6 +5460,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/api.yml

@@ -4637,6 +4637,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/asynchelper.yml

@@ -3154,6 +3154,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/connection.yml

@@ -3244,6 +3244,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/connector.yml

@@ -1103,6 +1103,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/ediprofile.yml

@@ -656,6 +656,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/enduser.yml

@@ -1883,6 +1883,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/environment.yml

@@ -393,6 +393,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/eventreport.yml

@@ -351,6 +351,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/export.yml

@@ -15929,19 +15929,38 @@ components:
 
         **Usage**
 
-        When executing a test run or configuring a flow, integrator.io will use this mock output
-        instead of executing the export to retrieve live data. This allows you to:
+        In a flow test run, and for an upstream lookup during a page-processor preview
+        (`previewPageProcessor`), integrator.io substitutes this mock output for the export's live
+        response instead of calling the source. It is not substituted anywhere else: a target lookup
+        in that preview runs its live query, `POST /v1/exports/preview` calls the source, and real
+        runs ignore it. This allows you to:
         - Test mappings with representative data
         - Configure downstream flow steps without waiting for real data
         - Simulate various data scenarios
 
+        Where it is substituted, the records stand in for the RAW parsed response: the export's own
+        `transform` and output `filter` still run on top of them, so downstream steps — and a
+        lookup's results mapping — see the transformed, filtered records, not the shape stored here.
+
         **Limitations**
 
         - Maximum of 10 records
         - Maximum size of 1 MB
         - Must follow the canonical format shown above
 
-        Mock output can be populated automatically from preview data or entered manually.
+        Mock output can be populated automatically from preview data (which is the parsed response,
+        before `transform` / `filter`) or entered manually.
+      x-celigo-ai-guidance:
+        - |-
+          Store the RAW parsed response records here, never transformed ones — the platform runs
+          the export's `transform` and `filter` on the mock exactly as on live data, and a
+          pre-transformed mock would be transformed twice. When you read `mockOutput` to learn
+          what a lookup returns, apply the transform first; a results mapping authored against
+          the stored shape walks paths that do not exist at runtime.
+        - |-
+          A saved mockOutput is read in exactly two places — a flow test run, and an upstream lookup
+          during a page-processor preview. A target lookup's preview, `POST /v1/exports/preview` and
+          every real run call the source and never read it.
       properties:
         page_of_records:
           type: array
@@ -16787,6 +16806,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/filedefinition.yml

@@ -1173,6 +1173,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/flow.yml

@@ -4135,20 +4135,48 @@ components:
         extracts evaluate against that envelope:
 
         - **Lookup steps**: `{"statusCode": 200, "data": [<result records>],
-          "errors": []}` — `data` holds the records the lookup returned, so
-          extracts must start from it: `data[0].name` copies a field of the
-          first result, `data` copies the whole result array. A bare
-          result-record field name (e.g. `name`) resolves to nothing and merges
-          nothing.
+          "errors": []}` — `data` holds the records the lookup step returns,
+          AFTER the export's own `transform` and output `filter` have run, so
+          extracts must start from it and name transformed fields by their
+          transformed name: `data[0].name` copies a field of the first result,
+          `data` copies the whole result array. A bare result-record field name
+          (e.g. `name`) resolves to nothing and merges nothing, and so does the
+          raw response path a transform consumed.
         - **Import steps**: `{"id": "<destination record id>", "statusCode": 200,
-          "ignored": false, "errors": [], "_json": <raw destination response>}` —
-          use `id` for the destination-assigned id and `_json.<path>` for fields
-          inside the destination's response body. The full envelope (including
-          `id`) is present on real runs and in flow-builder previews; flow TEST
-          runs never execute imports, and their mock-built envelope carries no
-          `id` — an `extract: "id"` merges nothing in a test run even though it
-          works on real runs.
+          "ignored": false, "errors": [], "_json": <raw destination response>,
+          ...<response body fields flattened at the root>}` — use `id` for the
+          destination-assigned id and `_json.<path>` (or the flattened
+          `<path>`) for fields inside the destination's response body. The full
+          envelope (including `id`) is present on real runs and in flow-builder
+          previews; flow TEST runs never execute imports, and their mock-built
+          envelope carries no `id` — an `extract: "id"` merges nothing in a test
+          run even though it works on real runs.
+
+        An `extract` may also be a Handlebars expression. It evaluates against
+        the same envelope as a plain path, so every path inside `{{ }}` starts
+        where the plain paths start — `{{data.0.name}}`,
+        `{{#compare data.0.count "==" 1}}yes{{else}}no{{/compare}}`,
+        `{{#if data.length}}found{{/if}}` on a lookup; `{{_json.order.id}}` or
+        `{{id}}` on an import. Index arrays with dots inside Handlebars
+        (`data.0.name` or `data.[0].name`; `data[0].name` renders nothing), and
+        expect a string result (`"1"`, `"false"`). There is no `record` object in
+        this context: `{{record.<anything>}}` renders nothing. Prefer a plain
+        path when the value is simply copied.
       x-celigo-ai-guidance:
+        - |-
+          Handlebars is allowed in `extract` but only rooted at the envelope —
+          `{{data.0.x}}` on a lookup, `{{_json.x}}` / `{{id}}` on an import. The
+          `record.` root belongs to import-mapping templates; here every
+          `{{record.…}}` form renders nothing, silently, and `{{data[0].x}}`
+          (bracket index inside Handlebars) renders nothing too. Use Handlebars
+          only for a derived value (a flag, a concatenation); copy values with a
+          plain path.
+        - |-
+          A lookup's `data[]` is the step's output after its `transform` and
+          `filter`, so author extracts against the transformed records — never
+          against the raw response the transform consumed, and never against a
+          saved `mockOutput` as stored (it is the raw response; the transform
+          runs on top of it in a test run).
         - |-
           Send `fields` and `lists` as bare arrays, exactly as GET returns them.
           Never wrap either in an object (e.g. `"fields": {"type": [...]}`): the
@@ -4190,22 +4218,29 @@ components:
             properties:
               extract:
                 type: string
+                x-celigo-agent:
+                  - handlebars
                 description: |
                   Path within the canonical response envelope to copy the value
-                  from. For lookup steps, paths start from the envelope's `data`
-                  array (`data[0].x` and `data.0.x` are equivalent; `data` alone
-                  copies every result); for import steps, use the envelope fields
-                  `id`, `statusCode`, `ignored`, or `_json.<path>` for the raw
-                  response body. Paths that skip the envelope (bare response
-                  field names) resolve to nothing, and a `[*]` wildcard is not
-                  honored here — `data[*].x` merges nothing; iterate arrays with
-                  `lists` instead.
+                  from, or a Handlebars expression over that same envelope. For
+                  lookup steps, paths start from the envelope's `data` array
+                  (`data[0].x` and `data.0.x` are equivalent; `data` alone
+                  copies every result) — a lookup result field written without
+                  the `data` prefix resolves to nothing. For import steps, use
+                  the envelope fields `id`, `statusCode`, `ignored`, `_json.<path>`
+                  for the raw response body, or the body field itself at the
+                  envelope root (`orderNumber` and `_json.orderNumber` read the
+                  same value). A `[*]` wildcard is not honored here — `data[*].x`
+                  merges nothing; iterate arrays with `lists` instead. Inside
+                  Handlebars, index with dots (`{{data.0.x}}`, never
+                  `{{data[0].x}}`) and never use a `record.` root.
                 examples:
                   - data[0].customer.name
                   - data.0.fields.Product Name
                   - data
                   - id
                   - _json.orderNumber
+                  - '{{#if data.length}}found{{else}}missing{{/if}}'
               generate:
                 type: string
                 description: |
@@ -5609,6 +5644,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/guardrail.yml

@@ -463,6 +463,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/httpconnector.yml

@@ -1850,6 +1850,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/httpconnectorendpoint.yml

@@ -932,6 +932,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/iclient.yml

@@ -4244,6 +4244,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/import.yml

@@ -16261,6 +16261,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/integration.yml

@@ -3531,9 +3531,21 @@ components:
           examples:
             - 1.2.0
           description: |-
-            Integration App version (or template version) associated with this integration.
-
-            Usually system-managed for Integration App installs; omit unless you are explicitly controlling versions.
+            Version of the Integration App (or template) currently installed in this integration.
+            For Integration Apps the connector's update workflow sets it; omit unless you are
+            explicitly controlling versions.
+          x-celigo-ai-guidance:
+            - |-
+              This is the installed version only. No API field carries an Integration App's newest
+              available version (the connector record has none), so whether a newer release exists
+              cannot be read from the platform — say so rather than inferring it from release notes,
+              which are labeled by their own scheme, not by this value.
+            - |-
+              To date an Integration App update, read the integration's audit log
+              (`GET /v1/integrations/{_id}/audit?source=connector`) for `version` field changes —
+              one entry per version step, and an update run usually writes several in a row.
+              `lastModified` moves on any write and `updateInProgress` can flip without a version
+              change, so neither dates an update.
         tag:
           type:
             - string
@@ -3551,6 +3563,9 @@ components:
             API, but normally managed by the platform's update workflow.
           x-celigo-ai-guidance:
             - Typically system-managed; omit unless a workflow explicitly requires setting it.
+            - |-
+              An update run can set and clear it without changing `version`; its audit entries alone
+              do not mean a new release was installed — the `version` changes do.
         celigoAgentAutoRunMode:
           type: boolean
           examples:
@@ -3569,6 +3584,10 @@ components:
             Timestamp indicating when the most recent install/update workflow was resolved/completed.
 
             Typically system-managed; omit in normal create/update payloads.
+          x-celigo-ai-guidance:
+            - |-
+              May be absent on an installed Integration App even after its update workflow has run —
+              date an update from the audit log's `version` changes, not from this field.
         settingsForm:
           description: Settings form definition for the integration.
           allOf:
@@ -4279,6 +4298,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/job.yml

@@ -1189,6 +1189,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/lookupcache.yml

@@ -758,6 +758,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/mcp-oauth-provider.yml

@@ -422,6 +422,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/mcp-server.yml

@@ -3315,6 +3315,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/notification.yml

@@ -244,6 +244,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/tag.yml

@@ -336,6 +336,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/template.yml

@@ -643,6 +643,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/tool.yml

@@ -6033,11 +6033,21 @@ components:
                         can read them. Extracts do NOT read the raw application
                         response — they evaluate against the platform's canonical
                         per-record envelope: for lookups (`type: "export"`) that is
-                        `{"statusCode", "data": [<result records>], "errors"}`, so
-                        paths must start from `data` (e.g. `data[0].name`); for
-                        imports it is `{"id", "statusCode", "ignored", "_json"}`,
-                        so use `id` or `_json.<path>`. Bare result-record field
-                        names resolve to nothing and merge nothing.
+                        `{"statusCode", "data": [<result records>], "errors"}`
+                        where `data` holds the records AFTER the export's own
+                        `transform` and output `filter`, so paths must start from
+                        `data` and name transformed fields by their transformed
+                        name (e.g. `data[0].name`) — a lookup result field
+                        written without the `data` prefix resolves to nothing;
+                        for imports it is `{"id", "statusCode", "ignored",
+                        "_json", ...<body fields flattened>}`, so use `id`,
+                        `_json.<path>`, or the body field itself at the root
+                        (`orderNumber` and `_json.orderNumber` read the same
+                        value). An extract may be a Handlebars expression over
+                        the same envelope (`{{data.0.name}}`,
+                        `{{#if data.length}}found{{/if}}`; dot indexes only; a
+                        string result); there is no `record` object in this
+                        context, so `{{record.…}}` renders nothing.
                       properties:
                         fields:
                           type: array
@@ -6047,15 +6057,20 @@ components:
                             properties:
                               extract:
                                 type: string
+                                x-celigo-agent:
+                                  - handlebars
                                 description: |
                                   Path within the canonical response envelope to
                                   copy the value from (`data[0].x` / `data.0.x`
-                                  for lookups; `id` or `_json.<path>` for
-                                  imports).
+                                  for lookups; `id`, `_json.<path>` or the
+                                  flattened body field `<path>` for imports), or
+                                  a Handlebars expression over that envelope (dot
+                                  indexes inside `{{ }}`, never a `record.` root).
                                 examples:
                                   - data[0].customer.name
                                   - data.0.fields.Product Name
                                   - id
+                                  - '{{#if data.length}}found{{else}}missing{{/if}}'
                               generate:
                                 type: string
                                 description: |
@@ -6273,6 +6288,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:
@@ -36169,19 +36192,38 @@ components:
 
         **Usage**
 
-        When executing a test run or configuring a flow, integrator.io will use this mock output
-        instead of executing the export to retrieve live data. This allows you to:
+        In a flow test run, and for an upstream lookup during a page-processor preview
+        (`previewPageProcessor`), integrator.io substitutes this mock output for the export's live
+        response instead of calling the source. It is not substituted anywhere else: a target lookup
+        in that preview runs its live query, `POST /v1/exports/preview` calls the source, and real
+        runs ignore it. This allows you to:
         - Test mappings with representative data
         - Configure downstream flow steps without waiting for real data
         - Simulate various data scenarios
 
+        Where it is substituted, the records stand in for the RAW parsed response: the export's own
+        `transform` and output `filter` still run on top of them, so downstream steps — and a
+        lookup's results mapping — see the transformed, filtered records, not the shape stored here.
+
         **Limitations**
 
         - Maximum of 10 records
         - Maximum size of 1 MB
         - Must follow the canonical format shown above
 
-        Mock output can be populated automatically from preview data or entered manually.
+        Mock output can be populated automatically from preview data (which is the parsed response,
+        before `transform` / `filter`) or entered manually.
+      x-celigo-ai-guidance:
+        - |-
+          Store the RAW parsed response records here, never transformed ones — the platform runs
+          the export's `transform` and `filter` on the mock exactly as on live data, and a
+          pre-transformed mock would be transformed twice. When you read `mockOutput` to learn
+          what a lookup returns, apply the transform first; a results mapping authored against
+          the stored shape walks paths that do not exist at runtime.
+        - |-
+          A saved mockOutput is read in exactly two places — a flow test run, and an upstream lookup
+          during a page-processor preview. A target lookup's preview, `POST /v1/exports/preview` and
+          every real run call the source and never read it.
       properties:
         page_of_records:
           type: array

package/dist/tradingpartnerconnector.yml

@@ -1307,6 +1307,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/dist/user.yml

@@ -737,6 +737,14 @@ components:
           description: Timestamp when the resource was last updated. Changes whenever any property is modified.
           x-celigo-ai-guidance:
             - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
           examples:
             - '2023-04-15T14:30:15Z'
         deletedAt:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.79",
+  "version": "0.2.81",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "8b3a38c",
+		"iasCommit": "83152dc",
 		"generatedAt": "2026-10-08"
 	},
 	"roots": {