@celigo/api-specs 0.2.171 → 0.2.173

package/dist/flow.yml

@@ -440,8 +440,10 @@ 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 the plan's cap, `logging.maxDebugDuration` minutes on the license
-        from `GET /v1/licenses`); to
-        disarm, set it to a past timestamp or null.
+        from `GET /v1/licenses`). To disarm it, `remove` `/logging/debugUntil`. A `replace` with a
+        past timestamp is refused with 422 ("Debug logging end time must be in the future.") and
+        leaves the window open, so to end a window early with `replace` alone, set a time a few
+        seconds ahead.
       operationId: patchFlow
       tags:
         - Flows
@@ -475,6 +477,11 @@ paths:
                   - op: replace
                     path: /logging/debugUntil
                     value: '2026-05-02T16:00:00.000Z'
+              disable_debug:
+                summary: Turn debug logging off before the window ends
+                value:
+                  - op: remove
+                    path: /logging/debugUntil
               update_schedule:
                 summary: Change Celigo 6-field schedule cron
                 value:
@@ -1996,7 +2003,7 @@ paths:
                   value:
                     errors:
                       - code: inactive_flow
-                        message: The flow is currently disabled and cannot process retries.
+                        message: The flow is inactive. Please enable the flow before retrying.
                 missing_last_error_at:
                   summary: selectAll without lastErrorAt
                   value:
@@ -3523,7 +3530,22 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
-          $ref: '#/components/responses/404-not-found'
+          description: |-
+            Flow not found ("The flow <_id> does not belong to the user <userId>."). The
+            same answer comes back for a flow that exists and has page generators but no page
+            processor or router yet, even when `_exportId` names one of its page generators: give it
+            a step after the export before test-running it. (An `_exportId` that isn't one of the
+            flow's page generators is the 400.)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  summary: Unknown flow id, or a flow with no page processor or router
+                  value:
+                    errors:
+                      - message: The flow 5f8d43a1b9e5a80011a35f2c does not belong to the user 60a2c4e6f321d800129a1a3c.
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
   /v1/flows/{_id}/test/run/{runId}/{_stepId}:
@@ -4577,7 +4599,22 @@ components:
           properties:
             postResponseMap:
               type: object
-              description: Hook that runs after the step's response mapping completes.
+              description: |-
+                Hook that runs after the step's response mapping completes. The function receives
+                `options.postResponseMapData` (the records, with response mapping applied) and
+                `options.responseData` (the step's per-record results, in the same order) and returns
+                `postResponseMapData`, same length. A record an import step failed is in neither array
+                unless `proceedOnFailure` is true. Then it is included, without the fields response
+                mapping would have added, and its `responseData` entry has `statusCode` 422 and
+                `errors` as an object keyed by index (`"0"`, `"1"`, ...) rather than an array. A
+                successful entry has no `errors`.
+              x-celigo-ai-guidance:
+                - |-
+                  Verified live 2026-10-22 in flow runs of an HTTP import, three records with one
+                  answered 404: with `proceedOnFailure` unset, both arrays held the two written
+                  records; with `proceedOnFailure: true` they held all three, and a hook that called
+                  `.map` on each entry's `errors` threw on the failed one, failing the page. Read
+                  errors with `Object.values(entry.errors || {})`.
               properties:
                 function:
                   type: string
@@ -5523,6 +5560,17 @@ components:
             into a schedule (for example all wildcards, `? * * ? * *`), `422
             schedule_not_supported` when its runs would be less than a minute apart — which
             is also what free text such as `every 5 minutes` produces.
+
+            A save can store a later minute than it was sent. A minute field that is 0, 15,
+            30 or 45, a list made only of those minutes, a range that starts at minute 0, or a
+            `*/N` step with N above 5 is stored 5 minutes later: `? 0 6 ? * *` as
+            `? 5 6 ? * *`, `? 0,15,30,45 * ? * *` as `? 5,20,35,50 * ? * *`, `? 0-10 * ? * *`
+            as `? 5-15 * ? * *`, and `? */15 * ? * *` as `? 5-59/15 * ? * *`. Any other minute
+            field is kept as sent, including `? */5 * * * *` and lists that mix in other
+            minutes (`? 0,10,20,30,40,50 * ? * *`), and the other fields never change. POST,
+            PUT and PATCH all store it this way, the response and later reads return the
+            stored value, and scheduled runs start at the stored minutes, so a flow saved for
+            06:00 runs at 06:05 (live-verified 2026-10-22).
           x-celigo-ai-guidance:
             - |-
               Build `schedule` as a Celigo 6-field cron:
@@ -5544,20 +5592,22 @@ components:
               schedule (`? * * ? * *`) with 422 `invalid_value`. Fix or clear the schedule
               instead of disabling the flow to get past the error.
             - |-
-              Prefer explicit lists when AUTHORING a schedule — hourly or longer:
-              minute `5` with an explicit hour list
+              When AUTHORING a schedule, read `schedule` back after the save and give
+              the user the stored times, not the requested ones: a schedule written
+              for minute 0, 15, 30 or 45 can be stored, and run, 5 minutes later (see
+              the description), and an explicit list is moved the same way as a step
+              form. Hourly or longer: minute `5` with an explicit hour list
               (`? 5 0,4,8,12,16,20 ? * *` = every 4 hours;
-              `? 5 9 ? * 1,2,3,4,5` = weekdays 9 AM; `? 5 0 ? * *` = daily);
-              sub-hourly: an explicit minute list with hour `*`
-              (`? 0,15,30,45 * ? * *` = every 15 minutes). Lists match the UI's
-              schedule builder and make fire times unambiguous — the scheduler can
-              offset step expressions (the UI's sub-hourly presets fire at minutes
-              10/25/40/55).
+              `? 5 9 ? * 1,2,3,4,5` = weekdays 9:05 AM; `? 5 0 ? * *` = daily at
+              00:05); sub-hourly: an explicit minute list with hour `*`
+              (`? 5,20,35,50 * ? * *` = every 15 minutes) or a step form.
             - |-
               Wildcard/step/range forms (`? */5 * * * *`, `? 10-59/30 * * * *`) are
               valid and the scheduler runs them — never claim an existing schedule's
               format is invalid or the cause of missed runs, and never rewrite a
-              working schedule into a different format as a fix. A new scheduled
+              working schedule into a different format as a fix. A minute stored 5
+              minutes after the one written is the save's normal behavior, not a
+              fault, and a rewritten schedule is stored the same way. A new scheduled
               instance is not started while a previous run of the flow is still in
               progress (boundaries skipped during a long run are by design); missed
               runs on an enabled, unchanged flow with nothing running are a
@@ -6655,7 +6705,12 @@ components:
             - '500'
         message:
           type: string
-          description: Human-readable message. Frequently a JSON string that the adaptor received as a response body.
+          description: |-
+            Human-readable message. Frequently a JSON string that the adaptor received as a response body.
+            Stored cut to 500 characters: a longer message keeps its first 497 characters followed by
+            `...`. A template parse error (`handlebars_template_parse_error`) repeats the whole template
+            before its parse detail, so in a long template the detail is cut off; invoking the import
+            (`POST /v1/imports/{_id}/invoke`) with the record returns the full message.
           examples:
             - '{"error":"Internal Server Error"}'
         oIndex:
@@ -6692,6 +6747,7 @@ components:
           x-celigo-ai-guidance:
             - Read the classification off the record; never infer it from the message text — the classifier is heuristic and identical messages can classify differently.
             - There is no setting, mapping, hook, or API that changes a classification; a wrong one is a Celigo Support matter.
+            - '`parse` also covers a request URL template that names a field the record lacks (`handlebars_template_parse_error`, `Failed to generate request url from template: … Details: "<field>" not defined in the model.`). That is missing data, not template syntax: nothing was sent, a retry of the same record fails the same way, and the fix is the record or how the import routes it (see an HTTP import''s `relativeURI`).'
         classifiedBy:
           type: string
           description: '`auto` on every classified error; absent on unclassified ones.'
@@ -7364,7 +7420,11 @@ components:
               type: integer
               readOnly: true
               description: |-
-                Number of records skipped, for example by an import's ignore-existing or ignore-missing rule.
+                Number of records skipped, by a filter or by an import's ignore-existing or ignore-missing
+                rule. Records an import's filter skips count in that import's child job; records an export's
+                output filter drops count in the export's child job, whose `numSuccess` then counts only the
+                records that passed (an export that read 6 records and dropped 3 reads `numSuccess` 3,
+                `numIgnore` 3; live-verified 2026-10-22). Filtered records raise no error.
                 Summed across steps on a parent flow job; per step on a child job.
               examples:
                 - 0
@@ -8072,16 +8132,18 @@ components:
           description: |-
             Execution stage whose data to return. `apiCall` holds the request and response an HTTP
             export or import sent. On a job whose `logMode` is `debug`, an export's transform and
-            output filter record under `transformation` and `outputFilter`, an import's mapping and
-            response mapping under `mapping` and `responseMapping`, and a script hook's `options` and
+            output filter record under `transformation` and `outputFilter`, an import's filter (its
+            `filter` field) under `inputFilter`, an import's mapping and response mapping under
+            `mapping` and `responseMapping`, and a script hook's `options` and
             return value under its hook type plus `Hook` (`preSavePageHook`, `preMapHook`,
             `postMapHook`, `postSubmitHook`, `postResponseMapHook`), whatever the function is called;
             neither the bare hook name (`preMap`) nor `<functionName>Hook` returns them (live-verified
-            2026-10-20).
+            2026-10-20; `inputFilter` 2026-10-22).
           examples:
             - apiCall
             - transformation
             - outputFilter
+            - inputFilter
             - mapping
             - responseMapping
             - preSavePageHook
@@ -8114,8 +8176,11 @@ components:
 
         - `apiCall`: the request's method and URI and the response's status code. A job whose `logMode` is
           `detailed` or `debug` also records each side's headers and body; a `basic` job does not.
-        - `mapping`, `transformation`, `outputFilter`, `responseMapping`: a per-record entry carrying the
-          record's `recordId`, the stage's `input`, and its `output` (`outputFilter` has `success` instead).
+        - `mapping`, `transformation`, `outputFilter`, `inputFilter`, `responseMapping`: a per-record entry
+          carrying the record's `recordId`, the stage's `input`, and its `output`. The filter stages
+          (`outputFilter` for an export's output filter, `inputFilter` for an import's filter) have
+          `success` instead, `false` for a record the filter dropped (`inputFilter` live-verified
+          2026-10-22).
         - `preSavePageHook`, `preMapHook`, `postMapHook`, `postSubmitHook`: one entry for the record's whole
           group, with no `recordId`. `input` is a one-element array holding the `options` the hook received,
           and `output` holds what the hook returned.

package/dist/guardrail.yml

@@ -1940,8 +1940,10 @@ components:
             - A dot path from the record root (e.g. `email`, `address.city`), read from the
               incoming record. A path that matches no field writes nothing.
             - Handlebars template (contains `{{`) for concatenation /
-              formatting / conditional logic (e.g.
-              `{{record.firstName}} {{record.lastName}}`).
+              formatting / conditional logic (e.g. `{{firstName}} {{lastName}}`,
+              `{{#if mobile}}{{mobile}}{{else}}{{phone}}{{/if}}`). The template reads the
+              record's fields by bare name: `{{record.firstName}}` and `{{data.firstName}}`
+              render nothing, so the field is left out even when the record has the value.
 
             A `$.` JSONPath (the Mapper 2.0 `mappings` syntax) reads nothing here, and a bare
             string is read as a field path, not a constant: set constants in `hardCodedValue`.
@@ -1982,8 +1984,9 @@ components:
           x-celigo-ai-guidance:
             - |-
               When true, skip this field entirely when ``extract`` / lookup
-              produces empty / null. Without this flag the destination field
-              receives null and may overwrite existing data.
+              produces an empty string, null or nothing. Without this flag an
+              empty string is written as ``""`` and null as null, either of which
+              may overwrite existing data; a missing source is left out either way.
         immutable:
           type: boolean
           description: When true, the mapped value cannot be overwritten by later mapping steps.
@@ -2000,7 +2003,15 @@ components:
           type:
             - string
             - 'null'
-          description: Fallback value used when the extract yields no value.
+          description: |-
+            Fallback value written when the source value is an empty string, null or
+            missing. Without a default, an empty string and null are written as they are
+            and a missing field is left out.
+          x-celigo-ai-guidance:
+            - |-
+              Use ``default``, not ``hardCodedValue``, for a fallback on a field that is
+              sometimes empty: ``hardCodedValue`` is written on every record and replaces
+              the values that exist.
         extractDateFormat:
           type: string
           description: Date format of the source value, used to parse it before conversion.

package/dist/httpconnector.yml

@@ -1300,15 +1300,30 @@ components:
                 - `"lessthan"`: Value is less than specified value (is less than)
                 - `"lessthanequals"`: Value is less than or equal to specified value (is less than or equals)
                 - `"startswith"`: String starts with specified prefix (starts with)
+                - `"notstartswith"`: String does not start with specified prefix (does not start with)
                 - `"endswith"`: String ends with specified suffix (ends with)
+                - `"notendswith"`: String does not end with specified suffix (does not end with)
                 - `"contains"`: String contains specified substring (contains)
                 - `"doesnotcontain"`: String does not contain specified substring (does not contain)
                 - `"empty"`: Field is missing or empty (is empty)
                 - `"notempty"`: Field contains a value (is not empty)
-                - `"matches"`: Matches a regular expression (matches)
+                - `"matches"`: Matches a regular expression, ignoring case (matches)
 
-                `isempty`, `isnotempty` and `anyof` are not operators: they are refused with 422
-                "Invalid operation: <name>".
+                Operator names are case-insensitive: `NOTEMPTY` and `endsWith` work and are stored
+                as sent. `isempty`, `isnotempty`, `anyof`, `notcontains`, `doesnotstartwith`,
+                `doesnotendwith`, `notmatches`, `doesnotmatch` and `notequal` are not operators:
+                they are refused with 422 "Invalid operation: <name>", with the name in lowercase,
+                both when the filter is saved and by `POST /v1/processors/filter`. To negate a
+                condition, wrap it in `not`.
+
+                The string comparisons (`equals`, `contains`, `startswith`, `endswith` and their
+                negations) are case-sensitive; wrap the field in `lowercase` to compare without case.
+                `matches` is not: every pattern is compiled with the flags `gi`, so `^paid$` also
+                matches `PAID` and `[a-z]` matches capital letters. An inline flag such as `(?i)`
+                makes the pattern invalid. The filter still saves, but in a run every record fails
+                with `FILTER_EVALUATION_FAILED` ("Invalid regular expression: /(?i)…/gi: Invalid
+                group"), and `POST /v1/processors/filter` refuses the call with 422 (live-verified
+                2026-10-22).
 
                 **Logical Operators**
                 - `"and"`: All conditions must be true
@@ -1598,7 +1613,9 @@ components:
               x-celigo-refModel: scripts
               description: |
                 Reference to the Script resource that contains the filtering logic. This must be a valid
-                ObjectId of a Script resource that exists in the system.
+                ObjectId of a Script resource in this account: any other id fails the save with 422
+                ("Only a script owned by the user or a script shared by the Integration App can be used
+                at filter.script._scriptId.").
 
                 The referenced script must contain the function specified in the `function` field
                 and must be written to handle filtering specifically. The script receives

package/dist/httpconnectorresource.yml

@@ -746,15 +746,30 @@ components:
                 - `"lessthan"`: Value is less than specified value (is less than)
                 - `"lessthanequals"`: Value is less than or equal to specified value (is less than or equals)
                 - `"startswith"`: String starts with specified prefix (starts with)
+                - `"notstartswith"`: String does not start with specified prefix (does not start with)
                 - `"endswith"`: String ends with specified suffix (ends with)
+                - `"notendswith"`: String does not end with specified suffix (does not end with)
                 - `"contains"`: String contains specified substring (contains)
                 - `"doesnotcontain"`: String does not contain specified substring (does not contain)
                 - `"empty"`: Field is missing or empty (is empty)
                 - `"notempty"`: Field contains a value (is not empty)
-                - `"matches"`: Matches a regular expression (matches)
-
-                `isempty`, `isnotempty` and `anyof` are not operators: they are refused with 422
-                "Invalid operation: <name>".
+                - `"matches"`: Matches a regular expression, ignoring case (matches)
+
+                Operator names are case-insensitive: `NOTEMPTY` and `endsWith` work and are stored
+                as sent. `isempty`, `isnotempty`, `anyof`, `notcontains`, `doesnotstartwith`,
+                `doesnotendwith`, `notmatches`, `doesnotmatch` and `notequal` are not operators:
+                they are refused with 422 "Invalid operation: <name>", with the name in lowercase,
+                both when the filter is saved and by `POST /v1/processors/filter`. To negate a
+                condition, wrap it in `not`.
+
+                The string comparisons (`equals`, `contains`, `startswith`, `endswith` and their
+                negations) are case-sensitive; wrap the field in `lowercase` to compare without case.
+                `matches` is not: every pattern is compiled with the flags `gi`, so `^paid$` also
+                matches `PAID` and `[a-z]` matches capital letters. An inline flag such as `(?i)`
+                makes the pattern invalid. The filter still saves, but in a run every record fails
+                with `FILTER_EVALUATION_FAILED` ("Invalid regular expression: /(?i)…/gi: Invalid
+                group"), and `POST /v1/processors/filter` refuses the call with 422 (live-verified
+                2026-10-22).
 
                 **Logical Operators**
                 - `"and"`: All conditions must be true
@@ -1044,7 +1059,9 @@ components:
               x-celigo-refModel: scripts
               description: |
                 Reference to the Script resource that contains the filtering logic. This must be a valid
-                ObjectId of a Script resource that exists in the system.
+                ObjectId of a Script resource in this account: any other id fails the save with 422
+                ("Only a script owned by the user or a script shared by the Integration App can be used
+                at filter.script._scriptId.").
 
                 The referenced script must contain the function specified in the `function` field
                 and must be written to handle filtering specifically. The script receives