@celigo/api-specs 0.2.150 → 0.2.152

package/dist/api.yml

@@ -6366,7 +6366,12 @@ components:
           type: boolean
           description: |
             When true, uses iClient-managed OAuth credentials (clientId/clientSecret)
-            instead of the values in this configuration.
+            instead of the values in this configuration. The iClient is the connection's
+            `_iClientId` — on an HTTP connection `http._iClientId`, beside `auth`, not inside it —
+            and it also supplies the grant type and the authorization and token endpoints, so a
+            create needs only `auth.type: "oauth"`, `auth.oauth.useIClientFields: true` and the
+            iClient id. The connection holds no tokens until a person completes the authorization
+            in a browser.
         oauth1:
           type: object
           description: |-
@@ -6495,7 +6500,7 @@ components:
       x-celigo-ai-guidance:
         - |-
           ## OAUTH 2.0 GRANT TYPES
-          - "authorizationcode" — Authorization Code flow (browser-based user consent).
+          - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
             Requires tokenURI, clientId, clientSecret.
@@ -7086,7 +7091,11 @@ components:
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
                     On update, the mask sent back keeps the stored token; a new value replaces it.
-                    Required unless automatic token refresh is configured.
+                    Required unless automatic token refresh is configured: a token block without a
+                    token must carry a `refreshMethod`, so a create or update that sends neither fails
+                    with 422 `Expected field: refreshMethod to be present.` To create a static-token
+                    connection before the real token is available, send a placeholder value and
+                    replace it later.
                   examples:
                     - my-api-token-EXAMPLE
                 location:
@@ -9292,7 +9301,11 @@ components:
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
             On update, the mask sent back keeps the stored token; a new value replaces it.
-            Required unless automatic token refresh is configured.
+            Required unless automatic token refresh is configured: a token block without a
+            token must carry a `refreshMethod`, so a create or update that sends neither fails
+            with 422 `Expected field: refreshMethod to be present.` To create a static-token
+            connection before the real token is available, send a placeholder value and
+            replace it later.
           examples:
             - my-api-token-EXAMPLE
         location:

package/dist/connection.yml

@@ -5196,7 +5196,12 @@ components:
           type: boolean
           description: |
             When true, uses iClient-managed OAuth credentials (clientId/clientSecret)
-            instead of the values in this configuration.
+            instead of the values in this configuration. The iClient is the connection's
+            `_iClientId` — on an HTTP connection `http._iClientId`, beside `auth`, not inside it —
+            and it also supplies the grant type and the authorization and token endpoints, so a
+            create needs only `auth.type: "oauth"`, `auth.oauth.useIClientFields: true` and the
+            iClient id. The connection holds no tokens until a person completes the authorization
+            in a browser.
         oauth1:
           type: object
           description: |-
@@ -5325,7 +5330,7 @@ components:
       x-celigo-ai-guidance:
         - |-
           ## OAUTH 2.0 GRANT TYPES
-          - "authorizationcode" — Authorization Code flow (browser-based user consent).
+          - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
             Requires tokenURI, clientId, clientSecret.
@@ -5916,7 +5921,11 @@ components:
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
                     On update, the mask sent back keeps the stored token; a new value replaces it.
-                    Required unless automatic token refresh is configured.
+                    Required unless automatic token refresh is configured: a token block without a
+                    token must carry a `refreshMethod`, so a create or update that sends neither fails
+                    with 422 `Expected field: refreshMethod to be present.` To create a static-token
+                    connection before the real token is available, send a placeholder value and
+                    replace it later.
                   examples:
                     - my-api-token-EXAMPLE
                 location:
@@ -8122,7 +8131,11 @@ components:
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
             On update, the mask sent back keeps the stored token; a new value replaces it.
-            Required unless automatic token refresh is configured.
+            Required unless automatic token refresh is configured: a token block without a
+            token must carry a `refreshMethod`, so a create or update that sends neither fails
+            with 422 `Expected field: refreshMethod to be present.` To create a static-token
+            connection before the real token is available, send a placeholder value and
+            replace it later.
           examples:
             - my-api-token-EXAMPLE
         location:

package/dist/enduser.yml

@@ -3308,7 +3308,12 @@ components:
           type: boolean
           description: |
             When true, uses iClient-managed OAuth credentials (clientId/clientSecret)
-            instead of the values in this configuration.
+            instead of the values in this configuration. The iClient is the connection's
+            `_iClientId` — on an HTTP connection `http._iClientId`, beside `auth`, not inside it —
+            and it also supplies the grant type and the authorization and token endpoints, so a
+            create needs only `auth.type: "oauth"`, `auth.oauth.useIClientFields: true` and the
+            iClient id. The connection holds no tokens until a person completes the authorization
+            in a browser.
         oauth1:
           type: object
           description: |-
@@ -3437,7 +3442,7 @@ components:
       x-celigo-ai-guidance:
         - |-
           ## OAUTH 2.0 GRANT TYPES
-          - "authorizationcode" — Authorization Code flow (browser-based user consent).
+          - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
             Requires tokenURI, clientId, clientSecret.
@@ -4028,7 +4033,11 @@ components:
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
                     On update, the mask sent back keeps the stored token; a new value replaces it.
-                    Required unless automatic token refresh is configured.
+                    Required unless automatic token refresh is configured: a token block without a
+                    token must carry a `refreshMethod`, so a create or update that sends neither fails
+                    with 422 `Expected field: refreshMethod to be present.` To create a static-token
+                    connection before the real token is available, send a placeholder value and
+                    replace it later.
                   examples:
                     - my-api-token-EXAMPLE
                 location:
@@ -6234,7 +6243,11 @@ components:
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
             On update, the mask sent back keeps the stored token; a new value replaces it.
-            Required unless automatic token refresh is configured.
+            Required unless automatic token refresh is configured: a token block without a
+            token must carry a `refreshMethod`, so a create or update that sends neither fails
+            with 422 `Expected field: refreshMethod to be present.` To create a static-token
+            connection before the real token is available, send a placeholder value and
+            replace it later.
           examples:
             - my-api-token-EXAMPLE
         location:

package/dist/export.yml

@@ -982,36 +982,40 @@ components:
     Delta:
       type: object
       description: |-
-        Configures incremental exports that retrieve only records created or modified since the last
-        successful run. Required when the export's type is "delta"; omit for other export types.
-        The platform-managed last-successful-run timestamp (exposed as {{lastExportDateTime}}) is the
-        lower bound, and after a failed run the next run reuses the last successful timestamp so
-        changed records are not missed. A first run is not a full export: with no `startDate`, its
-        {{lastExportDateTime}} is the run's own timestamp (the value {{currentExportDateTime}} also
-        holds), so it picks up no earlier changes. Set `startDate` to reach back further. On success,
-        when `POST /v1/flows/{_id}/run` sends `export.endDate`, the flow's checkpoint is left at that
-        value, so an end date in the past moves the next run's lower bound back.
+        Configures incremental exports that retrieve only records created or modified since the
+        flow's delta checkpoint; omit it for other export types. Adaptors that compare a record field
+        name it in `dateField`, while HTTP exports and SQL queries carry {{lastExportDateTime}} in the
+        request and save without a delta object. Each run's window runs from {{lastExportDateTime}}
+        (the checkpoint) to {{currentExportDateTime}} (the time the run started). A first run is not a
+        full export: with no `startDate`, its {{lastExportDateTime}} is the run's own timestamp, so it
+        picks up no earlier changes. The checkpoint moves to a run's window end only when the run
+        exports records, so a run that exports nothing leaves it where it was, and after a failed run
+        the next run reuses the last checkpoint. On success, when `POST /v1/flows/{_id}/run` sends
+        `export.endDate`, the flow's checkpoint is left at that value, so an end date in the past
+        moves the next run's lower bound back.
       x-celigo-ai-guidance:
         - |-
-          This object is REQUIRED when the export's type field is set to "delta" and
-          should not be included for other export types.
+          Omit this object for export types other than "delta". An HTTP export with type
+          "delta" saves without it, since the request carries {{lastExportDateTime}}, but
+          set ``startDate`` anyway: without it the first run's window is empty.
           Delta exports are designed for efficient synchronization by retrieving only
           records that have been created or modified since the last execution.
         - |-
           ## REQUIRED FIELDS
           - ``startDate`` -- the initial cutoff timestamp the platform uses on the
             first run (and as the floor for ``{{lastExportDateTime}}`` thereafter).
-            Adapter-specific validators (e.g. NetSuite's ``transformTwoDotZero``)
-            reject delta configs that omit ``startDate`` with
-            ``missing_delta_startDate``, so this is effectively required for every
-            delta export.
+            Without it, a new flow's first run renders ``{{lastExportDateTime}}`` as
+            the run's own time, so the first run exports nothing (verified on HTTP
+            and RDBMS delta exports). Adapter-specific validators (e.g. NetSuite's
+            ``transformTwoDotZero``) reject delta configs that omit ``startDate``
+            with ``missing_delta_startDate``, so set it on every delta export.
         - |-
           ## DEFAULT CUTOFF BEHAVIOR (NO USER-SUPPLIED CUTOFF)
           When the user prompt does not specify an explicit cutoff timestamp,
           default ``startDate`` to **today at midnight UTC** in ISO-8601 format
           (e.g. ``"2026-05-14T00:00:00.000Z"``).  This means the first run picks
           up records changed today; subsequent runs use the platform-managed
-          ``{{lastExportDateTime}}`` (the last successful run timestamp).
+          ``{{lastExportDateTime}}`` (the end of the last run that exported records).
 
           - First run: filters records changed since ``startDate``.
           - Subsequent runs: uses ``{{lastExportDateTime}}`` as the lower bound;
@@ -1024,18 +1028,28 @@ components:
               - For HTTP exports: Use {{lastExportDateTime}} variable in relativeURI or body
               - For specific application adapters: Use dateField to specify timestamp fields
 
-          2. The system automatically maintains the last successful run timestamp
+          2. The system automatically maintains the checkpoint
               - No need to store or manage timestamps in your own code
               - A first run without ``startDate`` fetches nothing older than the run itself
-              - Subsequent runs use this timestamp as the starting point
+              - A run that exports records moves the checkpoint to its window end
+                ({{currentExportDateTime}}), where the next run starts
+              - Use {{lastExportDateTime}} as the lower bound; {{currentExportDateTime}} as the
+                lower bound asks for records changed after the run started, so every run exports nothing
 
           3. Error handling and recovery:
               - If an export fails, the next run uses the last successful timestamp
               - Records created/modified during a failed run will be included in the next run
+              - A run that exports nothing leaves the checkpoint where it was, so after a stretch of
+                empty runs the next run that finds records reaches back to the last run that exported
+                any: once the cause is fixed, no backfill run is needed
+              - A run given its own window (export.startDate / export.endDate on
+                POST /v1/flows/{_id}/run) that exports records leaves the checkpoint at endDate,
+                even a past one, so the next run re-reads everything after it
               - The lagOffset field can be used to handle edge cases
         - |-
-          This object is REQUIRED when the export's type field is set to "delta" and
-          should not be included for other export types.
+          Omit this object for export types other than "delta". An HTTP export with type
+          "delta" saves without it, since the request carries {{lastExportDateTime}}, but
+          set ``startDate`` anyway: without it the first run's window is empty.
           Delta exports are designed for efficient synchronization by retrieving only
           records that have been created or modified since the last execution.
       properties:
@@ -1051,8 +1065,9 @@ components:
             If the flow's own downstream steps update the exported records, add export criteria
             that exclude already-processed records (or use a creation-time field for process-once
             flows) so each run doesn't re-export what the previous run wrote. Not supported on
-            HTTP exports: embed {{lastExportDateTime}} in the relativeURI or body instead;
-            including dateField there makes the configuration invalid. For Salesforce this
+            HTTP exports: embed {{lastExportDateTime}} in the relativeURI or body instead; an HTTP
+            export saved with dateField is refused with 422 "Unsupported dateField in
+            export.delta.dateField". For Salesforce this
             field is required and defaults to the standard timestamp fields (LastModifiedDate,
             CreatedDate, SystemModstamp, LastActivityDate, LastViewedDate, LastReferencedDate) plus
             any custom timestamp fields.
@@ -1091,7 +1106,8 @@ components:
               ###CRITICAL ADAPTOR-SPECIFIC INSTRUCTION:
               - The adaptor type is HTTP. For HTTP exports, the "dateField" property MUST NOT be included in the delta configuration.
               - HTTP exports use the {{lastExportDateTime}} variable directly in the relativeURI or body instead of dateField.
-              - DO NOT include "dateField" in your response. If you include it, the configuration will be invalid.
+              - DO NOT include "dateField" in your response. If you include it, the save is refused with
+                422 "Unsupported dateField in export.delta.dateField".
 
               Example HTTP query with implicit delta:
               ```
@@ -1151,10 +1167,10 @@ components:
         dateFormat:
           type: string
           description: |-
-            Moment.js format string applied to the cutoff timestamp, including {{lastExportDateTime}}
-            when used in HTTP requests. Leave unset unless the source system requires a non-ISO8601
-            format; ISO 8601 is used by default. Date-only formats truncate the time portion,
-            widening the filter window.
+            Moment.js format string applied to both delta variables, {{lastExportDateTime}} and
+            {{currentExportDateTime}}, in HTTP requests and SQL queries alike. Leave unset unless the
+            source system requires a non-ISO8601 format; by default both render as ISO 8601 UTC with
+            milliseconds. Date-only formats truncate the time portion, widening the filter window.
           x-celigo-ai-guidance:
             - Defines the date/time format expected by the source system's API.
             - |-
@@ -1165,7 +1181,8 @@ components:
               - OPTIONAL: Only needed when the source system doesn't support ISO8601
               - Default: ISO8601 format (YYYY-MM-DDTHH:mm:ss.sssZ)
               - Uses Moment.js formatting tokens
-              - Directly affects the format of {{lastExportDateTime}} when used in HTTP requests
+              - Formats both {{lastExportDateTime}} and {{currentExportDateTime}}, in HTTP requests and in
+                SQL queries (an RDBMS delta query receives the formatted value as a quoted literal)
             - |-
               ## IMPLEMENTATION PATTERNS
 
@@ -1249,13 +1266,15 @@ components:
           format: date-time
           description: |-
             Lower-bound cutoff for the first run. Omitting it doesn't export history: the first run
-            then starts at its own timestamp. Set it to the earliest change the first run should pick
-            up. Subsequent runs use the platform-managed last-successful-run timestamp.
+            then starts at its own timestamp, an empty window. Set it to the earliest change the first
+            run should pick up. Later runs start from the flow's checkpoint, the end of the last run
+            that exported records.
           x-celigo-ai-guidance:
             - |-
               Initial cutoff timestamp for the first export run, in ISO-8601 UTC format (e.g.
               ``"2026-05-14T00:00:00.000Z"``).
-              REQUIRED for every delta export -- adapter-specific validators reject delta
+              Set it on every delta export: without it the first run's window is empty (verified
+              on HTTP and RDBMS delta exports), and adapter-specific validators reject delta
               configs without it (e.g.
               NetSuite returns ``missing_delta_startDate`` from the ``transformTwoDotZero`` processor).
             - |-
@@ -1267,10 +1286,11 @@ components:
               flow is being authored.
             - |-
               ## SUBSEQUENT RUNS
-              After the first successful run, the platform tracks the actual
-              last-run timestamp and exposes it as ``{{lastExportDateTime}}``;
-              ``startDate`` becomes the floor used only when the platform
-              timestamp is absent (e.g. after a reset).
+              After the first run that exports records, the platform keeps the
+              flow's checkpoint at the end of the last run that exported records
+              and exposes it as ``{{lastExportDateTime}}``; runs that export
+              nothing leave it unchanged. ``startDate`` becomes the floor used
+              only when the platform timestamp is absent (e.g. after a reset).
             - |-
               ## EXAMPLES
               - ``"2026-05-14T00:00:00.000Z"`` -- today at midnight UTC.
@@ -1279,7 +1299,8 @@ components:
             - |-
               Initial cutoff timestamp for the first export run, in ISO-8601 UTC format (e.g.
               ``"2026-05-14T00:00:00.000Z"``).
-              REQUIRED for every delta export -- adapter-specific validators reject delta
+              Set it on every delta export: without it the first run's window is empty (verified
+              on HTTP and RDBMS delta exports), and adapter-specific validators reject delta
               configs without it (e.g.
               NetSuite returns ``missing_delta_startDate`` from the ``transformTwoDotZero`` processor).
           examples:
@@ -1420,7 +1441,7 @@ components:
             - exported_to_netsuite
     Webhook:
       type: object
-      description: Configuration for webhook listeners that receive data through incoming HTTP requests. Required when the export's `type` is `webhook`; omit for other export types. The platform generates a unique endpoint URL, validates each incoming request using the configured `verify` method, passes the payload to subsequent flow steps, and returns a configurable HTTP response to the caller.
+      description: Configuration for webhook listeners that receive data through incoming HTTP requests. Required when the export's `type` is `webhook`; omit for other export types. Senders POST to the export's listener URL, `https://api.integrator.io/v1/exports/{_id}/data` (or the same path on the account's regional API host); the platform validates each request using the configured `verify` method, passes the payload to subsequent flow steps, and returns a configurable HTTP response to the caller. A request is answered 204 by default when accepted, 401 when it fails verification, and 403 `unable_to_run_flows` while every flow the export feeds is disabled; a refused request is not queued, so the sender must resend it.
       x-celigo-ai-guidance:
         - Configuration object for real-time event listeners that receive data via incoming HTTP requests.
         - |-
@@ -1794,7 +1815,7 @@ components:
             - sha1
         encoding:
           type: string
-          description: Encoding of the HMAC signature value when `verify` is `hmac`. Must match the encoding the webhook sender uses — a mismatch causes requests to be rejected even when the signature is otherwise correct.
+          description: 'Encoding of the HMAC signature value when `verify` is `hmac`. Must match the encoding the webhook sender uses — a mismatch causes requests to be rejected with a 401 even when the signature is otherwise correct. With `provider: custom`, `hex` is compared as lowercase hex: an uppercase hex signature is rejected.'
           x-celigo-ai-guidance:
             - Specifies the encoding format used for the HMAC signature in webhook requests.
             - |-
@@ -1890,7 +1911,7 @@ components:
             - 9d1a5c6b3e7d9f2a1c5b8e3aEXAMPLE
         header:
           type: string
-          description: Name of the request header that carries the HMAC signature when `verify` is `hmac`. Must match the header name the webhook sender uses (header names are case-insensitive); requests without this header are rejected with a 401. Signature prefixes in the header value (such as `sha256=`) are handled automatically.
+          description: 'Name of the request header that carries the HMAC signature when `verify` is `hmac`. Must match the header name the webhook sender uses (header names are case-insensitive); requests without this header are rejected with a 401. With `provider: custom` the header value must be the bare digest in the configured `encoding`: a value with a `sha256=` prefix is rejected with a 401.'
           x-celigo-ai-guidance:
             - Specifies the HTTP header name that contains the signature for HMAC verification.
             - |-
@@ -1936,8 +1957,9 @@ components:
 
               - The system will look for this exact header name in incoming requests
               - If the header is not found, the request will be rejected with a 401 error
-              - Some platforms may include a prefix in the header value (e.g., "sha256=")
-                which is handled automatically by the system
+              - Some platforms include a prefix in the header value (e.g., "sha256="). With
+                provider "custom" it is not stripped: a prefixed signature is rejected with a 401,
+                so the sender must send the bare digest
 
               IMPORTANT: This must exactly match the header name used by the webhook sender.
               If you're unsure about the correct header name, consult the sender's documentation
@@ -3452,11 +3474,12 @@ components:
             - metadata
         skipDelete:
           type: boolean
+          default: false
           description: |-
             When true, source files remain on the file server after processing; when false (the
             default), files are deleted after successful processing. Files that fail processing are
             never deleted, regardless of this setting. Enable retention when files must be processed
-            by other flows or kept for compliance.
+            by other flows or systems, or kept for compliance.
           x-celigo-ai-guidance:
             - |-
               Controls whether source files are retained or deleted after successful processing.
@@ -4129,8 +4152,10 @@ components:
               type: string
               description: |-
                 Character sequence separating fields within each row; comma when omitted. Use "\t"
-                for tab-delimited files; European-locale exports often use semicolons. An incorrect
-                delimiter is the most common cause of parsing failures.
+                for tab-delimited files; European-locale exports often use semicolons. A wrong
+                delimiter doesn't fail the parse: with a header row, each row becomes one field named
+                after the whole header line (`{"order_id;sku;qty": "1001;TEE-M;2"}`), so the failure
+                shows up in later steps.
               x-celigo-ai-guidance:
                 - |-
                   Specifies the character sequence that separates individual fields (columns)
@@ -6590,6 +6615,8 @@ components:
             Controls how the export requests subsequent pages when the API returns multi-page responses. The `method` field determines which companion fields are required and how each next page is requested. For the page, skip, and token methods, reference the matching pagination variable (`{{export.http.paging.page}}`, `{{export.http.paging.skip}}`, or `{{export.http.paging.token}}`) in the relative URI or request body — misconfigured pagination is a common cause of incomplete data retrieval.
 
             When this export is the first lookup of a builder-mode API with `pagination.enabled` set, it is that API's volume driver: saving the export (even unchanged) invalidates the API's issued cursors, so a caller mid-walk gets an empty final page, and removing `paging` is accepted on save but makes every call to the API fail with `400 api_pagination_source_not_paged` until paging is restored or the API's flag is turned off.
+
+            When a next page's response is identical to the previous one, paging stops: the export records an open error with code `page_response_error` ("Identical response received from next page request. No more page requests will be made.") and the run completes with the pages already read, so later pages are never exported. A request that doesn't change between pages produces this, as observed with `method: page` and the pagination variable missing from the relative URI and body; reference the variable so each request asks for the next page.
           x-celigo-ai-guidance:
             - Configuration object for navigating through multi-page API responses.
             - |-
@@ -9560,19 +9587,25 @@ components:
           description: |-
             Directory on the same server where files are moved after successful export, giving you
             an independent backup; if omitted, files are simply deleted from the source directory
-            after successful export (Celigo also keeps its own copy of processed files for a set
-            period). Supports static paths or handlebars templates.
+            after successful export unless `file.skipDelete` is true (Celigo also keeps its own copy
+            of processed files for a set period). Supports static paths or handlebars templates.
           x-celigo-ai-guidance:
             - Optional directory where files are moved before deletion.
             - |-
               IMPORTANT:
-              Celigo automatically deletes files from the source directory after successful export.
+              Celigo automatically deletes files from the source directory after successful export,
+              unless `file.skipDelete` is true. Moving them to a backup directory also takes them out
+              of the source directory, so when another system still reads them there, set
+              `file.skipDelete: true` instead.
               The backup directory is for users who want to maintain their own independent
               backup of exported files.
               Celigo also maintains its own backup of processed files for a set period of time.
             - |-
               IMPORTANT:
-              Celigo automatically deletes files from the source directory after successful export.
+              Celigo automatically deletes files from the source directory after successful export,
+              unless `file.skipDelete` is true. Moving them to a backup directory also takes them out
+              of the source directory, so when another system still reads them there, set
+              `file.skipDelete: true` instead.
               The backup directory is for users who want to maintain their own independent
               backup of exported files.
               Celigo also maintains its own backup of processed files for a set period of time.
@@ -12044,19 +12077,26 @@ components:
           description: |-
             Bucket in the same region where files are moved after successful export, giving you an
             independent backup; if omitted, files are simply deleted from the source bucket after
-            successful export (Celigo also keeps its own copy of processed files for a set period).
-            The connection's AWS credentials must have s3:PutObject permission on this bucket.
+            successful export unless `file.skipDelete` is true (Celigo also keeps its own copy of
+            processed files for a set period). The connection's AWS credentials must have
+            s3:PutObject permission on this bucket.
           x-celigo-ai-guidance:
             - Optional destination bucket where files are moved before deletion.
             - |-
               IMPORTANT:
-              Celigo automatically deletes files from the source bucket after successful export.
+              Celigo automatically deletes files from the source bucket after successful export,
+              unless `file.skipDelete` is true. Moving them to a backup bucket also takes them out of
+              the source bucket, so when another system still reads them there, set
+              `file.skipDelete: true` instead.
               The backup bucket is for users who want to maintain their own independent backup
               of exported files.
               Celigo also maintains its own backup of processed files for a set period of time.
             - |-
               IMPORTANT:
-              Celigo automatically deletes files from the source bucket after successful export.
+              Celigo automatically deletes files from the source bucket after successful export,
+              unless `file.skipDelete` is true. Moving them to a backup bucket also takes them out of
+              the source bucket, so when another system still reads them there, set
+              `file.skipDelete: true` instead.
               The backup bucket is for users who want to maintain their own independent backup
               of exported files.
               Celigo also maintains its own backup of processed files for a set period of time.
@@ -15914,7 +15954,9 @@ components:
             `NetSuiteExport` and `NetSuiteHTTPExport` both need a `netsuite` connection).
             Server-required unless `type` is `webhook` or `simple` (those receive data instead of
             fetching it) or `adaptorType` is `TopicExport` (Event Streams listeners are delivered
-            by the platform itself and must omit it).
+            by the platform itself and must omit it). A `WebhookExport` saved without `type: webhook`
+            is refused with 422 "_connectionId is required unless type is [webhook|simple]"; a webhook
+            export that does carry a connection saves and updates normally.
           examples:
             - 60a2c4e6f321d800129a1a3c
         adaptorType:
@@ -16035,9 +16077,11 @@ components:
           description: |-
             Operational mode of the export. When omitted, the export retrieves all available records —
             the standard batch mode, which is also the right choice for parsing structured files
-            (CSV/XML/JSON) into records. Each mode requires its matching configuration object
-            (e.g. a `delta` object when `type` is `delta`); use `blob` only to transfer raw files
-            without parsing their contents.
+            (CSV/XML/JSON) into records. Most modes take their matching configuration object (e.g. a
+            `webhook` object when `type` is `webhook`); an HTTP or SQL `delta` export saves without a
+            `delta` object because its request carries `{{lastExportDateTime}}`, though
+            `delta.startDate` sets its first window. Use `blob` only to transfer raw files without
+            parsing their contents.
           x-celigo-ai-guidance:
             - |-
               ## HOW TO PICK THE TYPE VALUE
@@ -17332,16 +17376,22 @@ components:
           properties:
             postData:
               type: object
-              description: Additional data for the export preview
+              description: |-
+                Delta window for this preview. Without it, a document preview renders
+                `{{lastExportDateTime}}` and `{{currentExportDateTime}}` as empty strings (observed on
+                HTTP and RDBMS exports), so the preview doesn't reflect the export's delta window. On an
+                HTTP export these strings are substituted exactly as given; other adaptors weren't
+                checked. On an export without `delta.dateFormat`, a real run renders both as ISO 8601 UTC
+                with milliseconds, so pass them in that form to preview the request such a run would send.
               properties:
                 currentExportDateTime:
                   type: string
-                  description: Current export date time (timestamp)
-                  example: '1751909419'
+                  description: Value `{{currentExportDateTime}}` renders as in this preview (the window's end).
+                  example: '2026-01-16T00:00:00.000Z'
                 lastExportDateTime:
                   type: string
-                  description: Last export date time (timestamp)
-                  example: '1742641523'
+                  description: Value `{{lastExportDateTime}}` renders as in this preview (the window's start).
+                  example: '2026-01-15T00:00:00.000Z'
     PreviewResponse:
       type: object
       description: Response body for export data preview

package/dist/flow.yml

@@ -824,9 +824,10 @@ paths:
 
         The request body is optional. When omitted, the flow runs with its configured schedule behavior —
         for delta flows this means using the current `lastExportDateTime` as the lower bound. Pass
-        `export.startDate` / `export.endDate` to set this run's delta window. On success, when
-        `export.endDate` is sent, the flow's checkpoint is left at that value, so an end date in the past
-        moves the next run's lower bound back. Pass `_exportIds` to limit execution to a subset of the flow's
+        `export.startDate` / `export.endDate` to set this run's delta window (they render as
+        `{{lastExportDateTime}}` / `{{currentExportDateTime}}`). On success, when `export.endDate` is
+        sent, the flow's checkpoint is left at that value, so an end date in the past moves the next
+        run's lower bound back. Pass `_exportIds` to limit execution to a subset of the flow's
         generators (useful for flows with many independent sources).
 
         Flow-level preconditions enforced by the platform:
@@ -838,7 +839,9 @@ paths:
         `_jobId` with the execution-log endpoints. For delta backfills, prefer passing explicit
         `startDate`/`endDate` over editing the export's `lastExportDateTime`, and read the checkpoint
         first (`GET /v1/flows/{_id}/lastExportDateTime`): the override doesn't stay with one run, since
-        a successful run that sends `endDate` leaves the checkpoint there. A flow runs one instance at a time: a run requested while another
+        a successful run that sends `endDate` leaves the checkpoint there. Runs that export nothing
+        leave the checkpoint alone, so a stretch of empty runs needs no backfill once its cause is
+        fixed. A flow runs one instance at a time: a run requested while another
         instance is queued or running is refused with `409 job_already_queued` ("Another instance
         for this flow is already queued or running"), and a run-next-flow trigger that arrives in
         that state is dropped rather than queued.
@@ -862,7 +865,7 @@ paths:
                 summary: Default run (use configured delta window)
                 value: {}
               delta_window:
-                summary: Override the delta window for this run
+                summary: Set this run's delta window (the checkpoint follows endDate)
                 value:
                   export:
                     startDate: '2026-04-01T00:00:00Z'
@@ -1082,7 +1085,9 @@ paths:
         generators (exports) in the flow. This value is what gets substituted into the `{{lastExportDateTime}}`
         Handlebars variable on the next delta run of any export in the flow.
 
-        The checkpoint advances automatically at the end of a successful delta run. On success, when
+        A run moves the checkpoint to its window end (`{{currentExportDateTime}}`) only when it exports
+        records. A run that exports nothing leaves it where it was, so after a stretch of empty runs the
+        next run that finds records reaches back to the last run that exported any. On success, when
         `POST /v1/flows/{_id}/run` sends `export.endDate`, the checkpoint is left at that value, so an end
         date in the past moves the next run's lower bound back.
 
@@ -6302,7 +6307,8 @@ components:
           type: object
           description: |-
             Delta-window override. When present, the run uses these dates in place of the flow's own
-            `lastExportDateTime` / `currentExportDateTime`. Both fields are optional individually.
+            `lastExportDateTime` / `currentExportDateTime`. Both fields are optional individually. The
+            override outlasts the run: a run that exports records leaves the flow's checkpoint at `endDate`.
           properties:
             startDate:
               type: string
@@ -6313,7 +6319,10 @@ components:
             endDate:
               type: string
               format: date-time
-              description: ISO-8601 end of the delta window (maps to `currentExportDateTime`).
+              description: |-
+                ISO-8601 end of the delta window (maps to `currentExportDateTime`). When the run exports
+                records, the flow's checkpoint is left here, even when it is in the past, so the next run
+                starts from it.
               examples:
                 - '2026-01-15T23:59:59.000Z'
         _exportIds: