@celigo/api-specs 0.2.135 → 0.2.136

package/dist/ai-agent.yml

@@ -4329,7 +4329,10 @@ components:
           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.
+          raw response path a transform consumed. A lookup that groups its
+          results returns each group as an array inside `data`
+          (`"data": [[<row>, <row>]]`): `data[0][0].name` (or `data.0.0.name`)
+          reads the first row of the first group, and `data[0]` copies the group.
         - **Import steps**: `{"id": "<destination record id>", "statusCode": 200,
           "ignored": false, "errors": [], "_json": <raw destination response>,
           ...<response body fields flattened at the root>}` — use `id` for the

package/dist/flow.yml

@@ -426,7 +426,7 @@ paths:
         | `/name` | Flow display name |
         | `/description` | Flow description |
         | `/disabled` | Enable or disable the flow |
-        | `/logging/debugUntil` | Debug logging expiry (ISO-8601; the maximum window is license-dependent — 72 hours on standard licenses, 422 beyond the cap) |
+        | `/logging/debugUntil` | Debug logging expiry (ISO-8601; at most the license's `logging.maxDebugDuration` minutes ahead, 422 beyond the cap) |
         | `/logging/mode` | Logging mode |
         | `/runPageGeneratorsInParallel` | Run page generators in parallel |
         | `/aiDescription` | AI-generated description object |
@@ -439,7 +439,8 @@ paths:
 
         PATCH is safer than PUT for toggling `disabled` or arming debug logging because it won't
         accidentally reset other fields. To arm debug logging, `replace` `/logging/debugUntil` with
-        a future ISO timestamp (up to your license's cap — 72 hours on standard licenses); to
+        a future ISO timestamp (up to the plan's cap, `logging.maxDebugDuration` minutes on the license
+        from `GET /v1/licenses`); to
         disarm, set it to a past timestamp or null.
       operationId: patchFlow
       tags:
@@ -1502,7 +1503,8 @@ paths:
         Returns one page of already-resolved errors for a flow step (same shape as the open-errors listing).
 
         Errors arrive here either because a user marked them resolved (`PUT .../resolved`) or because a
-        successful retry auto-resolved them. The platform retains resolved errors through the account's
+        retry was submitted for them — a retry resolves its errors when it is submitted, whatever its
+        outcome. The platform retains resolved errors through the account's
         retention window; use `DELETE .../resolved` to purge them earlier.
 
         `resolvedBy` distinguishes how each error was closed: `auto` means a system-initiated
@@ -1856,9 +1858,9 @@ paths:
         - Flows
       summary: Retry errored records
       description: |-
-        Re-runs the per-record data snapshots captured when the listed errors occurred. A successful retry
-        auto-resolves the underlying open-error record. A retry that fails again stays open (and may
-        accumulate error history, depending on the adaptor).
+        Re-runs the per-record data snapshots captured when the listed errors occurred. Submitting the
+        retry resolves the listed errors at once, before the retry job runs and whatever it does; a record
+        that fails again comes back as a new open error.
 
         Only errors that carry a `retryDataKey` can be retried — typically these are record-level errors
         from imports or transforms. Connection-level errors (`classification: connection`) don't have a
@@ -1867,16 +1869,16 @@ paths:
         **Response behavior splits on whether anything matched:**
         - At least one record matched — a supplied `retryDataKey`, or (in `selectAll` mode) a retriable
           open error on or before `lastErrorAt` → **200** with a `type: "retry"` Job record (the queued
-          retry job; poll it via `GET /v1/jobs/{_id}`). A successful retry clears the original error from
-          `GET .../errors` and moves it into `/resolved` with `resolvedBy` set to the user who triggered
-          the retry. System-initiated auto-retries set `resolvedBy` to `"auto"` instead.
+          retry job; poll it via `GET /v1/jobs/{_id}`). The matched errors move from `GET .../errors` to
+          `/resolved` as the job is queued, with `resolvedBy` set to the user who submitted the retry.
+          System-initiated auto-retries set `resolvedBy` to `"auto"` instead.
         - Nothing matched → **204** silent no-op. There is no per-key validation: the endpoint does not
           400 on bogus keys; callers must poll `GET .../errors` to confirm any change.
 
-        **Retry outcome semantics.** A retry that still fails generates a **new** error record with a new
-        `errorId` (the original one is auto-resolved when the retry ultimately succeeds, or stays open
-        pending next retry). Building a UI on top of this endpoint needs to reconcile the "before" and
-        "after" error lists by `retryDataKey`, not `errorId`.
+        **Retry outcome semantics.** A record that fails again becomes a **new** open error with a new
+        `errorId`, the same `retryDataKey` and `traceKey`, and the retry job's id as `_flowJobId`; the
+        original stays resolved. Reconcile the "before" and "after" error lists by `retryDataKey`, not
+        `errorId`.
 
         To modify a record before retrying, call `GET .../{ retryDataKey}/data`, mutate the payload,
         `PUT` it back, then call this endpoint. Retried records go through the same page-processor
@@ -1884,6 +1886,11 @@ paths:
         listing keys, send `selectAll: true` with a `lastErrorAt` high-water mark instead of
         `retryDataKeys` — one call retries every matching error, no matter how many (errors without a
         `retryDataKey` are skipped).
+      x-celigo-ai-guidance:
+        - |-
+          An error leaving the open list after this call does not mean the retry worked: submitting
+          resolves it before the retry runs. Wait for the returned job to finish, then check its
+          `numError` and the open errors for the same `retryDataKey`.
       parameters:
         - name: _id
           in: path
@@ -2112,8 +2119,8 @@ paths:
         `pathToMany`, `childIndex`, `traceKey`) identify where in the pipeline the record was when it
         failed and how it's structured.
 
-        The `data` field shows exactly the payload the runtime tried to submit — compare it against the
-        source system to pinpoint transformation drift. Use `PUT .../{retryDataKey}/data` to mutate
+        The `data` field is the record as it reached the failing step — on an HTTP import, before the
+        import's mappings, not the request the import sent. Use `PUT .../{retryDataKey}/data` to mutate
         the snapshot before retrying. Only errors with a `retryDataKey` expose this endpoint;
         connection-class errors are rejected with `no_retrydata_found`. The `stage` field indicates
         where the retry will resume: `page_processor_import` re-runs the import (most common),
@@ -2961,9 +2968,10 @@ paths:
         (export or import). Entries carry the `(_expOrImpId, groupId, recordId, traceKey)` tuple needed to
         drill into per-stage metadata and data via the `logs/metadata/query` and `logs/data/query` endpoints.
 
-        Execution logs are populated only when the flow has logging enabled (either full `logMode` or the
-        time-bounded `logging.debugUntil` debug window). Jobs older than the flow's log retention window will
-        return an empty `logs` array.
+        Execution logs are captured only for a run with a logging level — the job's `logMode` — set by the
+        flow's `logging.mode` or an open `logging.debugUntil` window. While the account-level logging
+        preference is off, a flow set to `basic` captures nothing and its jobs carry no `logMode`. Jobs older
+        than the flow's log retention window will return an empty `logs` array.
 
         For per-stage data (an HTTP request and response, or a mapping's or script hook's input and
         output), pick an entry and call `POST .../logs/data/query` with the corresponding `stage`. To stitch an
@@ -3411,6 +3419,9 @@ paths:
         test-run shape also exists for Tools (`/v1/tools/{_id}/test/run`) and
         builder-mode APIs (`/v1/apis/{_id}/test/run`).
 
+        A test run processes only the first page of records: later pages arrive empty, so downstream
+        steps see only the first page's records.
+
         Test-run state is short-lived and ephemeral — capture the `runId` (the
         `flowJob._id`) and read back any step detail soon after the run returns.
       parameters:
@@ -4303,7 +4314,10 @@ components:
           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.
+          raw response path a transform consumed. A lookup that groups its
+          results returns each group as an array inside `data`
+          (`"data": [[<row>, <row>]]`): `data[0][0].name` (or `data.0.0.name`)
+          reads the first row of the first group, and `data[0]` copies the group.
         - **Import steps**: `{"id": "<destination record id>", "statusCode": 200,
           "ignored": false, "errors": [], "_json": <raw destination response>,
           ...<response body fields flattened at the root>}` — use `id` for the
@@ -4627,10 +4641,13 @@ components:
           properties:
             version:
               type: string
-              description: Version of the filter expression language
+              enum:
+                - '1'
+              x-enumDescriptions:
+                '1': Version 1 of the Celigo expression-based filter format.
+              description: Version of the filter format used by `rules`, the same version export and import filters use.
               examples:
-                - '1.0'
-                - '2.0'
+                - '1'
             rules:
               type: array
               description: |
@@ -4900,7 +4917,9 @@ components:
           description: |
             Override configurations for exports in the abstract flow.
 
-            Allows customizing export behavior while maintaining the flow structure.
+            Allows customizing export behavior while maintaining the flow structure. Each entry needs
+            at least one field besides `_abstractId`; an entry with only `_abstractId` fails with 422
+            ("Export override must include at least one field in addition to _abstractId").
           items:
             type: object
             properties:
@@ -4912,7 +4931,10 @@ components:
               _id:
                 type: string
                 x-celigo-refModel: exports
-                description: Concrete export ID to use (if replacing entirely)
+                description: |-
+                  Existing export that replaces the abstract flow's export on this instance. This is
+                  how an instance gets its own webhook URL: instances that keep the abstract flow's
+                  listener share its URL, and one request to it runs every enabled instance.
                 examples:
                   - 60a2c4e6f321d800129a1a3c
               _connectionId:
@@ -5397,7 +5419,11 @@ components:
         Writable flow fields shared by the request and response schemas.
 
         Use `pageProcessors` for simple linear flows or `routers` for conditional branching — never
-        include both. The `schedule` field uses Celigo's 6-field cron format (not standard 5-field).
+        include both: a flow with both arrays non-empty is rejected with 422 `invalid_branched_flow_config`.
+        The same import can be a step only once per flow: a second `pageProcessors` entry with its
+        `_importId`, in the same array or another branch, fails with 422 `invalid_flow` ("… already
+        included as a pageProcessor"). The `schedule` field uses Celigo's 6-field cron format (not
+        standard 5-field).
       properties:
         name:
           type: string
@@ -5528,6 +5554,9 @@ components:
             neither, has exactly one branch, and is not drawn — it is the invisible joint that holds
             the steps before the first branching router (they cannot sit in top-level
             `pageProcessors` once routers exist) and that merges branches back into shared steps.
+            Records enter at `routers[0]` and reach other routers only through `branches[].nextRouterId`,
+            so the order of the rest of the array is not execution order; a flow edited in Flow Builder
+            can list its routers out of execution order.
           x-celigo-ai-guidance:
             - No branching on a non-abstract flow → leave `routers` out and put the steps in top-level `pageProcessors`. No branching on an abstract flow → one pass-through router holding the chain (top-level `pageProcessors` are rejected with 422 `abstract_flow_invalid_fields`).
             - Steps before the first branching router go in a one-branch pass-through router at `routers[0]` with neither `routeRecordsTo` nor `routeRecordsUsing` set, chained to the branching router with `branches[0].nextRouterId`. Branches that rejoin point `nextRouterId` at one shared pass-through router.
@@ -5868,15 +5897,15 @@ components:
                     - detailed
                   x-enumDescriptions:
                     accountLevel: Inherits the account-level logging setting.
-                    basic: Logs record counts and step-level status only.
+                    basic: Logs each record's step status and each HTTP call's method, URL and status code, without headers or bodies; captures nothing while the account-level logging preference is off.
                     detailed: Logs full per-record data including request/response payloads.
                 debugUntil:
                   type: string
                   format: date-time
                   description: |-
-                    Temporary debug-level logging until this timestamp. The maximum window is
-                    license-dependent (72 hours on standard licenses); values beyond the cap are
-                    rejected with 422.
+                    Temporary debug-level logging until this timestamp. The longest window is the
+                    plan's `logging.maxDebugDuration` (minutes) on the account's license
+                    (`GET /v1/licenses`); values beyond the cap are rejected with 422.
                   examples:
                     - '2026-01-15T10:30:00.000Z'
             hidden:
@@ -6524,8 +6553,8 @@ components:
       type: object
       description: |-
         One open-error record on a flow step. Errors accumulate per `(flow, step)` pair as the flow runs;
-        they remain "open" until a user marks them resolved (`PUT .../resolved`) or a successful retry
-        auto-resolves them.
+        they remain "open" until a user marks them resolved (`PUT .../resolved`) or submits a retry for
+        them (`POST .../retry` resolves them at submission, whatever the retry's outcome).
       properties:
         errorId:
           type: string
@@ -6542,7 +6571,11 @@ components:
             - '2026-01-15T09:30:00.000Z'
         source:
           type: string
-          description: Where the error originated.
+          description: |-
+            Step stage or system the error came from, such as `application` (raised from the
+            destination's response), `connection`, a hook (`pre_save_page_hook`,
+            `post_response_map_hook`) or a filter (`output_filter`). `GET /v1/errors/filterMetadata`
+            lists the source values the errors filter accepts.
           examples:
             - application
         code:
@@ -6780,9 +6813,10 @@ components:
                   resolvedBy:
                     type: string
                     description: |-
-                      `"auto"` when the platform auto-resolved (typically because a retry cleared the error
-                      or a connection-class error was auto-resolved at the end of a job), or a Mongo **user
-                      id** (not email) when a human marked it resolved via `PUT .../resolved`.
+                      `"auto"` when the platform resolved it (a system-initiated retry, or a
+                      connection-class error resolved at the end of a job), or the Mongo **user id** (not
+                      email) of the user who resolved it — through `PUT .../resolved`, or by submitting a
+                      retry, which resolves its errors when it is submitted.
                       Cross-reference via `GET /v1/ashares/{_id}` to resolve the id to a profile.
                     examples:
                       - auto
@@ -6895,7 +6929,8 @@ components:
       type: object
       description: |-
         Request body for `POST /v1/flows/{_id}/{_stepId}/retry`. Re-runs the per-record data snapshot
-        captured at the moment each error occurred. A successful retry auto-resolves the underlying error.
+        captured at the moment each error occurred. Submitting it resolves the targeted errors at once; a
+        record that fails again comes back as a new open error.
         Target the records one of two ways: list their snapshot keys in `retryDataKeys`, or set
         `selectAll: true` with a `lastErrorAt` high-water mark to retry every retriable open error on the
         step without enumerating keys.
@@ -7319,11 +7354,15 @@ components:
               type: string
               readOnly: true
               description: |-
-                Effective logging mode for this job, resolved from the flow's `logging.mode`
-                and the account-level logging preference. Common values: `basic` (default),
-                `detailed`, `off`, `on`, `debug`.
+                Execution-logging level the run captured at, resolved from the flow's `logging.mode`,
+                an open debug window (`logging.debugUntil`) and the account-level logging preference:
+                `basic`, `detailed`, or `debug` while a debug window is open. Not set on a run that
+                captured no execution logs, such as one that ran while the account-level preference
+                was off.
               examples:
                 - basic
+                - detailed
+                - debug
             __lastPageGeneratorJob:
               type: boolean
               readOnly: true
@@ -7387,9 +7426,9 @@ components:
         `GET /v1/flows/{_id}/{_stepId}/{retryDataKey}/data` and accepted (full-replace) by the PUT on the
         same path.
 
-        The `data` field carries the actual record payload the runtime tried to submit — its shape is
-        adaptor-specific. The surrounding fields identify where in the pipeline the failure happened and
-        how the record was structured.
+        The `data` field carries the record as it reached the failing step, which a retry runs through
+        that step again — its shape is adaptor-specific. The surrounding fields identify where in the
+        pipeline the failure happened and how the record was structured.
       properties:
         retryDataKey:
           type: string
@@ -7398,13 +7437,16 @@ components:
             - 5f8d43a1b9e5a80011a35f2d-rdk-0
         data:
           description: |-
-            The opaque record payload. For HTTPImport errors this is the HTTP response the target system
-            returned; for data-level failures it's the record as seen by the step. Shape varies by adaptor.
+            The record as it reached the step. On an HTTP import it is the incoming record, before the
+            import's mappings — not the request body the import sent or the response it got back — and a
+            retry maps it again with the import's current mappings, so a mapping fix reaches the retried
+            record. Shape varies by adaptor.
           additionalProperties: true
         stage:
           type: string
           description: Pipeline stage where the record was when the error occurred.
           examples:
+            - page_processor_import
             - importMappingExtract
         pgExportId:
           type: string
@@ -7630,6 +7672,10 @@ components:
           `missing_required_field` even though the field is present. When a tagging scheme needs
           more dimensions than 3 tags allow, encode the extra dimensions in the tag names rather
           than adding tags.
+        - |-
+          Send each error as `{id, rdk}`, and never add the error's trace key (`tk`) beside `rdk`:
+          that fails the request with 400 `invalid_fields` ("Please provide either retryDataKey or
+          traceKey and not both for the error id.").
       properties:
         errors:
           type: array
@@ -7647,7 +7693,10 @@ components:
                   - 5f8d43a1b9e5a80011a35f2d-0
               rdk:
                 type: string
-                description: Retry data key (`retryDataKey` from the listing). Empty string or omitted when the error has none.
+                description: |-
+                  Retry data key (`retryDataKey` from the listing). Required when the error has one: an
+                  entry without it fails with 404 `invalid_errorid`. Send an empty string, or omit it,
+                  only when the error has none.
                 examples:
                   - 5f8d43a1b9e5a80011a35f2d-rdk-0
             required:

package/dist/job.yml

@@ -1618,11 +1618,15 @@ components:
               type: string
               readOnly: true
               description: |-
-                Effective logging mode for this job, resolved from the flow's `logging.mode`
-                and the account-level logging preference. Common values: `basic` (default),
-                `detailed`, `off`, `on`, `debug`.
+                Execution-logging level the run captured at, resolved from the flow's `logging.mode`,
+                an open debug window (`logging.debugUntil`) and the account-level logging preference:
+                `basic`, `detailed`, or `debug` while a debug window is open. Not set on a run that
+                captured no execution logs, such as one that ran while the account-level preference
+                was off.
               examples:
                 - basic
+                - detailed
+                - debug
             __lastPageGeneratorJob:
               type: boolean
               readOnly: true
@@ -1924,13 +1928,13 @@ components:
         numResolvedByAuto:
           type: integer
           minimum: 0
-          description: Errors that were auto-resolved by a successful retry.
+          description: Errors the platform resolved automatically.
           examples:
             - 7
         numResolvedByUser:
           type: integer
           minimum: 0
-          description: Errors that a user manually marked resolved.
+          description: Errors a user resolved.
           examples:
             - 0
         avgRuntime:

package/package.json

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