@celigo/api-specs 0.2.19 → 0.2.20

package/dist/job.yml

@@ -333,9 +333,9 @@ paths:
         `canceled`, `retried`) are not returned; use `POST /v1/flows/runs/stats` for run history.
 
         The request body contains all filters -- there are no query-string parameters. Narrow to a specific flow or
-        integration with `_flowIds` / `_integrationIds` (AND-combined). The time bounds `time_gt` and `time_lte`
-        are accepted but do not narrow this list; to find long-running jobs, compare each job's `createdAt` or
-        `startedAt` on the client.
+        integration with `_flowIds` / `_integrationIds` (not both — sending both is rejected with HTTP 400).
+        `time_gt` and `time_lte` are not filters on this endpoint; use `POST /v1/flows/runs/stats`. To find
+        long-running jobs, compare each job's `createdAt` or `startedAt` on the client.
       requestBody:
         required: true
         content:
@@ -363,12 +363,11 @@ paths:
                 $ref: '#/components/schemas/JobsCurrentResponse'
               examples:
                 one_page:
-                  summary: One queued retry job — single page, so no pagingPostBody
+                  summary: One queued flow job — single page, so no pagingPostBody
                   value:
                     jobs:
                       - _id: 69e9958f815ae7eae3d9146b
-                        type: retry
-                        _importId: 69e9953d7a8373d88147b5ec
+                        type: flow
                         _flowId: 69e99544f3a2ac489d0f7953
                         status: queued
                         numSuccess: 0
@@ -377,6 +376,11 @@ paths:
                         numOpenError: 0
                         createdAt: '2026-04-23T03:44:15.515Z'
                         lastModified: '2026-04-23T03:44:15.532Z'
+                        flow:
+                          _id: 69e99544f3a2ac489d0f7953
+                          name: Shopee
+                          _integrationId: 69496f01615f724066afaac2
+                          integrationName: Shopee
         '204':
           description: No in-progress jobs match the filter.
         '400':
@@ -390,10 +394,9 @@ paths:
           application.  The platform requires ``sandbox`` in the body; Ora is
           production-only so it always sends ``false``.
         - |-
-          time_gt and time_lte are accepted but do not narrow this endpoint: a time_lte a week
-          in the past still returns jobs created seconds ago. To find jobs stuck for longer than
-          a threshold, compare each job's createdAt or startedAt yourself, and never describe the
-          result as bounded by a time filter you sent.
+          Do not send time_gt or time_lte; they are not on this request. To find jobs
+          stuck for longer than a threshold, compare each job's createdAt or startedAt
+          on the client.
   /v1/flows/runs/stats:
     post:
       x-internal: false
@@ -1443,15 +1446,29 @@ components:
             triggeredBy:
               type: string
               readOnly: true
-              description: Who/what triggered the job (free-form string).
+              description: |-
+                What started the run. On a `flow` job: `system` for a scheduled run, the `_id` of
+                the user who ran the flow, or the `_id` of the upstream flow whose `_runNextFlowIds`
+                chained into this one; absent on event-driven runs (webhook, real-time listener, and
+                stream page generators), which the inbound event starts. On a `retry` job: `auto`
+                for the platform's automatic intermittent-error retry, otherwise the `_id` of the
+                user who submitted the retry. Absent on `export` and `import` child jobs — the
+                parent flow job carries it.
               examples:
-                - scheduler
+                - system
             canceledBy:
               type: string
               readOnly: true
-              description: Who/what requested cancellation (free-form string).
+              description: |-
+                Who canceled the run: the `_id` of the user who requested the cancel, or `system` for
+                every platform-initiated cancel — stuck-run recovery after a worker exit or crash or
+                when a run stops making progress, stale-run cleanup, a scheduler that could not
+                re-queue the run, and the cancels that follow deleting the flow or replacing one of
+                its connections. The record does not say which of these it was.
+              x-celigo-ai-guidance:
+                - A `system` cancel is not something the user did and not a verdict on the flow's configuration, and by itself it does not prove the run was stuck — deleting the flow or replacing one of its connections cancels in-flight runs the same way; read the run's age and progress counters for that.
               examples:
-                - user
+                - system
             flowExecutionGroupId:
               type: string
               readOnly: true
@@ -1656,43 +1673,58 @@ components:
             type: string
             examples:
               - netsuite
-        category:
+        createdOnAndAfter:
           type: string
-          description: Optional category filter (e.g., `edi`).
+          format: date-time
+          description: Paging cursor. The server sets this on `pagingPostBody` to the last row's `createdAt`.
           examples:
-            - edi
-        time_gt:
-          type: integer
-          format: int64
-          description: |-
-            Start of the time window, in epoch milliseconds (exclusive). `POST /v1/flows/runs/stats`
-            aggregates only runs inside the window. `POST /v1/jobs/current` accepts the field but does
-            not apply it: in-progress jobs are returned regardless of when they were created.
+            - '2026-05-02T01:03:51.757Z'
+      required: []
+    DashboardFlow:
+      type: object
+      description: Minimal flow metadata inlined for rendering convenience — equivalent to `GET /v1/flows/{_flowId}` with most fields stripped.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          x-celigo-refModel: flows
+          description: Flow id (matches the outer `_flowId`).
           examples:
-            - 1745366400000
-        time_lte:
-          type: integer
-          format: int64
-          description: |-
-            End of the time window, in epoch milliseconds (inclusive). `POST /v1/flows/runs/stats`
-            aggregates only runs inside the window. `POST /v1/jobs/current` accepts the field but does
-            not apply it. To find jobs that have been queued or running longer than a threshold, compare
-            each returned job's `createdAt` (queued) or `startedAt` (running) on the client.
+            - 69497fc443fc1f9a03d31bd9
+        name:
+          type: string
+          description: Flow name.
           examples:
-            - 1746147600000
-      required: []
-    JobWithChildren:
+            - Shopee
+        _abstractFlowId:
+          type: string
+          format: objectId
+          x-celigo-refModel: flows
+          description: Abstract flow this instance was created from. Omitted for ordinary flows.
+          examples:
+            - 69497fc443fc1f9a03d31bd0
+        abstractFlowName:
+          type: string
+          description: Name of the abstract flow. Omitted when `_abstractFlowId` is absent.
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          description: Parent integration id. Omitted for standalone flows.
+          examples:
+            - 69496f01615f724066afaac2
+        integrationName:
+          type: string
+          description: Parent integration name. Omitted for standalone flows.
+          examples:
+            - Shopee
+    CurrentJobEntry:
       allOf:
         - $ref: '#/components/schemas/Job'
         - type: object
-          description: Job plus any child jobs (job family view).
           properties:
-            children:
-              type: array
-              readOnly: true
-              description: Child jobs (export/import) that are part of this job family.
-              items:
-                $ref: '#/components/schemas/Job'
+            flow:
+              $ref: '#/components/schemas/DashboardFlow'
     JobsCurrentResponse:
       type: object
       description: Response envelope for `POST /v1/jobs/current`.
@@ -1701,45 +1733,91 @@ components:
           type: array
           description: Current (in-progress) jobs.
           items:
-            $ref: '#/components/schemas/JobWithChildren'
+            $ref: '#/components/schemas/CurrentJobEntry'
         pagingPostBody:
-          type: object
           description: |-
             Cursor for the next page. Absent on the last (or only) page. Pagination is **body-based**:
             POST this object back to the same endpoint as the next request body to fetch the next page.
-            Echoes the caller's filter plus a server-added watermark (`endedOnOrBefore`). Single-page
+            Echoes the caller's filter plus a server-added watermark (`createdOnAndAfter`). Single-page
             responses omit this field entirely.
-          properties:
-            endedOnOrBefore:
-              type: string
-              format: date-time
-              description: Server-added cursor watermark — only jobs with `endedAt <= this` are included on the next page.
-              examples:
-                - '2026-05-02T01:03:51.757Z'
+          allOf:
+            - $ref: '#/components/schemas/JobsCurrentRequest'
     FlowRunsStatsRequest:
-      allOf:
-        - $ref: '#/components/schemas/JobsCurrentRequest'
-        - type: object
-          description: |-
-            Request body for `POST /v1/flows/runs/stats`. Shares its filter shape with `POST /v1/jobs/current`
-            (`_integrationIds`, `_flowIds`, `time_gt`, `time_lte`, …), but the response is a set of
-            **per-flow aggregates** rather than individual job records. Filters narrow which runs are rolled
-            up into each aggregate.
+      type: object
+      description: |-
+        Request body for `POST /v1/flows/runs/stats`. Shares common filters with `POST /v1/jobs/current`
+        (`_integrationIds`, `_flowIds`, …), but the response is a set of
+        **per-flow aggregates** rather than individual job records. Filters narrow which runs are rolled
+        up into each aggregate.
 
-            Omitting `time_gt` does not mean "all history" — the endpoint falls back to the dashboard's
-            default window (approximately the last 24 hours), and runs older than that silently drop out
-            of every aggregate. Send `time_gt` (epoch milliseconds) explicitly for any other range.
+        Omitting `time_gt` does not mean "all history" — the endpoint falls back to the dashboard's
+        default window (approximately the last 24 hours), and runs older than that silently drop out
+        of every aggregate. Send `time_gt` (epoch milliseconds) explicitly for any other range.
 
-            `time_lte` must not be later than the current time: a future value is rejected with
-            `400 invalid_filter_request_body` (unlike `POST /v1/jobs/current`, which accepts it). Omit
-            `time_lte` to end the window at now. When both bounds are sent they must be at least one hour
-            apart (`time_lte - time_gt >= 3600000`), or the request is rejected with
-            `400 invalid_time_filter`; a window with `time_gt` alone has no minimum span.
-          x-celigo-ai-guidance:
-            - Always send an explicit time_gt matching the window you intend to report, and never present the aggregates as covering a longer period than the time filter you sent. Without time_gt the default window (~24 hours) applies — an empty result then means "nothing ran recently", never "no runs exist".
-            - For a window that runs through the present, omit time_lte rather than computing an end bound — a value even seconds ahead of the server clock (a rounded-up "now", end of today) fails the whole request with 400 invalid_filter_request_body.
-            - A closed window narrower than one hour cannot be queried; widen time_lte to time_gt + one hour (and say so when reporting) rather than sending the narrower range.
-            - A flow absent from stats[] had no runs in the window; it does not mean the flow does not exist. numOpenError counts errors open NOW, which may predate the window.
+        `time_lte` must not be later than the current time: a future value is rejected with
+        `400 invalid_filter_request_body`. Omit
+        `time_lte` to end the window at now. When both bounds are sent they must be at least one hour
+        apart (`time_lte - time_gt >= 3600000`), or the request is rejected with
+        `400 invalid_time_filter`; a window with `time_gt` alone has no minimum span.
+      x-celigo-ai-guidance:
+        - Always send an explicit time_gt matching the window you intend to report, and never present the aggregates as covering a longer period than the time filter you sent. Without time_gt the default window (~24 hours) applies — an empty result then means "nothing ran recently", never "no runs exist".
+        - For a window that runs through the present, omit time_lte rather than computing an end bound — a value even seconds ahead of the server clock (a rounded-up "now", end of today) fails the whole request with 400 invalid_filter_request_body.
+        - A closed window narrower than one hour cannot be queried; widen time_lte to time_gt + one hour (and say so when reporting) rather than sending the narrower range.
+        - A flow absent from stats[] had no runs in the window; it does not mean the flow does not exist. numOpenError counts errors open NOW, which may predate the window.
+      properties:
+        _integrationIds:
+          type: array
+          description: Optional filter to only return jobs for these integration ids.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        _flowIds:
+          type: array
+          description: Optional filter to only return jobs for these flow ids.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: flows
+            examples:
+              - 69497fc443fc1f9a03d31bd9
+        applicationIds:
+          type: array
+          description: Optional filter by application ids.
+          items:
+            type: string
+            examples:
+              - netsuite
+        category:
+          type: string
+          description: Optional category filter (e.g., `edi`).
+          examples:
+            - edi
+        time_gt:
+          type: integer
+          format: int64
+          description: |-
+            Start of the time window, in epoch milliseconds (exclusive). `POST /v1/flows/runs/stats`
+            aggregates only runs inside the window.
+          examples:
+            - 1745366400000
+        time_lte:
+          type: integer
+          format: int64
+          description: |-
+            End of the time window, in epoch milliseconds (inclusive). `POST /v1/flows/runs/stats`
+            aggregates only runs inside the window.
+          examples:
+            - 1746147600000
+        endedOnOrBefore:
+          type: string
+          format: date-time
+          description: Paging cursor. The server sets this on `pagingPostBody` to the last row's `lastExecutedAt`.
+          examples:
+            - '2026-04-23T02:51:52.551Z'
+      required: []
     FlowRunStatsEntry:
       type: object
       description: |-
@@ -1822,7 +1900,7 @@ components:
         lastExecutedAt:
           type: string
           format: date-time
-          description: Timestamp of the most recent matching run (any status).
+          description: Timestamp of the most recent matching terminal run (`completed`, `canceled`, or `failed`).
           examples:
             - '2026-04-23T02:51:52.551Z'
         lastErrorAt:
@@ -1832,33 +1910,7 @@ components:
           examples:
             - '2026-04-21T10:51:13.221Z'
         flow:
-          type: object
-          description: Minimal flow metadata inlined for rendering convenience — equivalent to `GET /v1/flows/{_flowId}` with most fields stripped.
-          properties:
-            _id:
-              type: string
-              format: objectId
-              x-celigo-refModel: flows
-              description: Flow id (matches the outer `_flowId`).
-              examples:
-                - 69497fc443fc1f9a03d31bd9
-            name:
-              type: string
-              description: Flow name.
-              examples:
-                - Shopee
-            _integrationId:
-              type: string
-              format: objectId
-              x-celigo-refModel: integrations
-              description: Parent integration id. Omitted for standalone flows.
-              examples:
-                - 69496f01615f724066afaac2
-            integrationName:
-              type: string
-              description: Parent integration name. Omitted for standalone flows.
-              examples:
-                - Shopee
+          $ref: '#/components/schemas/DashboardFlow'
     FlowRunsStatsResponse:
       type: object
       description: |-
@@ -1877,20 +1929,14 @@ components:
           items:
             $ref: '#/components/schemas/FlowRunStatsEntry'
         pagingPostBody:
-          type: object
           description: |-
             Cursor for the next page. Absent on the last (or only) page. Pagination is **body-based**:
             POST this object back to the same endpoint as the next request body to fetch the next page.
             The object echoes the caller's filter plus a server-added watermark
             (`endedOnOrBefore`) that carries the cursor position. Single-page responses (typical for
             normal account sizes) omit this field entirely.
-          properties:
-            endedOnOrBefore:
-              type: string
-              format: date-time
-              description: Server-added cursor watermark — only runs with `endedAt <= this` are included on the next page.
-              examples:
-                - '2026-04-23T02:51:52.551Z'
+          allOf:
+            - $ref: '#/components/schemas/FlowRunsStatsRequest'
     JobsFamilyBatchRequest:
       type: array
       description: Array of job ids to fetch family information for (max 1000 ids per request).
@@ -1900,6 +1946,18 @@ components:
         x-celigo-refModel: jobs
         examples:
           - 69e981ee18808f3e5ed1b2fd
+    JobWithChildren:
+      allOf:
+        - $ref: '#/components/schemas/Job'
+        - type: object
+          description: Job plus any child jobs (job family view).
+          properties:
+            children:
+              type: array
+              readOnly: true
+              description: Child jobs (export/import) that are part of this job family.
+              items:
+                $ref: '#/components/schemas/Job'
     JobFilesSignedUrlRequest:
       type: object
       description: |