@celigo/api-specs 0.2.1

package/dist/job.yml

@@ -0,0 +1,2014 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Jobs
+  description: API for querying Celigo job execution state, retrieving job families and artifacts, and cancelling or purging jobs.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Jobs
+    description: |-
+      Jobs are read-only records of flow, export, and import executions, created by the
+      platform whenever a run occurs. A parent flow job aggregates the run's counters while
+      child export/import jobs carry per-step counts, errors, and artifacts. Use these
+      endpoints to monitor running jobs, inspect job families, download result files, and
+      cancel or purge runs.
+
+      ## Job schema
+
+      {% openapi-schemas spec="job" schemas="Job" grouped="true" %}
+paths:
+  /v1/jobs:
+    get:
+      x-internal: false
+      operationId: listJobs
+      tags:
+        - Jobs
+      summary: List all jobs
+      description: |-
+        Returns jobs matching the given query-parameter filters, up to 1001 per
+        page in descending `createdAt` order. Use `createdAt_lte` on the last
+        record's `createdAt` (minus 1 ms) to page forward.
+
+        There are two query modes depending on the `type` parameter:
+
+        - **Parent jobs** (`type` omitted, `flow`, `retry`, or `bulk_retry`) —
+          pass at least one of `_integrationId`, `_flowId`, `_exportId`,
+          `_importId`, `_flowJobId`, `createdAt_gte`, or `createdAt_lte` to
+          scope the query. Omitting all filters returns all jobs in the account.
+        - **Child jobs** (`type=export` or `type=import`) — requires
+          `_flowJobId` or a resource ID filter (`_exportId` / `_importId`).
+          Returns the export/import sub-jobs within a parent flow job.
+
+        Date filters accept ISO 8601, plain date, or epoch milliseconds. When
+        combining `numError_gte`/`numError_lte` with `_integrationId`, use full
+        ISO 8601 with millis (plain-date format may be rejected). To page
+        forward, take the `createdAt` of the last record, subtract 1 ms, and
+        pass it as `createdAt_lte`.
+
+        Active jobs (`queued` or `running`) are pinned to the top of the first
+        page even when they fall outside the date filters; `canceling` jobs are
+        not pinned. Account for this when paging — the first page can contain
+        records older filters would otherwise exclude.
+      parameters:
+        - name: _integrationId
+          in: query
+          schema:
+            type: string
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+          description: Filter by integration ID. Satisfies the required-param check.
+        - name: _exportId
+          in: query
+          schema:
+            type: string
+            x-celigo-refModel: exports
+            examples:
+              - 69f54d6a3469e3f5597848a1
+          description: Filter by export ID. Satisfies the required-param check.
+        - name: _importId
+          in: query
+          schema:
+            type: string
+            x-celigo-refModel: imports
+            examples:
+              - 69e9953d7a8373d88147b5ec
+          description: Filter by import ID. Satisfies the required-param check.
+        - name: _flowId
+          in: query
+          schema:
+            type: string
+            x-celigo-refModel: flows
+            examples:
+              - 69f54d6b7009ea11abad707a
+          description: Filter by flow ID. Satisfies the required-param check.
+        - name: _flowJobId
+          in: query
+          schema:
+            type: string
+            x-celigo-refModel: jobs
+            examples:
+              - 69f54d6f47185f8c7a500597
+          description: |-
+            Filter by parent flow-job ID. Satisfies the required-param check.
+            Required when querying child jobs (`type=export` or `type=import`).
+        - name: _flowId_in
+          in: query
+          schema:
+            type: string
+            examples:
+              - 69f54d6b7009ea11abad707a,69e83e7a75f7f8c14a12916e
+          description: |-
+            Comma-separated list of flow IDs to match. Works as an additional
+            filter but does **not** satisfy the required-param check alone.
+            `flowId_in` (without underscore) is accepted as an alias.
+        - name: status_in
+          in: query
+          schema:
+            type: string
+            examples:
+              - completed,failed
+          description: |-
+            Comma-separated list of status values to match (e.g.
+            `completed,failed`). Works as an additional filter but does
+            **not** satisfy the required-param check alone.
+        - name: createdAt_lte
+          in: query
+          schema:
+            type: string
+            examples:
+              - '2026-05-02T01:03:51.757Z'
+          description: |-
+            Return jobs created at or before this timestamp. Accepts ISO 8601,
+            plain date, or epoch milliseconds. Satisfies the required-param
+            check.
+        - name: createdAt_gte
+          in: query
+          schema:
+            type: string
+            examples:
+              - '2026-05-01T00:00:00.000Z'
+          description: |-
+            Return jobs created at or after this timestamp. Accepts ISO 8601,
+            plain date, or epoch milliseconds. Satisfies the required-param
+            check.
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum:
+              - queued
+              - running
+              - completed
+              - failed
+              - canceled
+              - canceling
+              - retrying
+            x-enumDescriptions:
+              queued: Job is waiting to be picked up for execution.
+              running: Job is currently executing.
+              completed: Job finished successfully.
+              failed: Job finished with a fatal error.
+              canceled: Job was canceled by a user or the system.
+              canceling: Job cancellation has been requested but execution has not yet stopped.
+              retrying: Job is being retried after a previous failure.
+          description: Filter by job status.
+        - name: numSuccess_lte
+          in: query
+          schema:
+            type: integer
+            examples:
+              - 100
+          description: Filter to jobs with success count ≤ this value.
+        - name: numSuccess_gte
+          in: query
+          schema:
+            type: integer
+            examples:
+              - 1
+          description: Filter to jobs with success count ≥ this value.
+        - name: numIgnore_lte
+          in: query
+          schema:
+            type: integer
+            examples:
+              - 10
+          description: Filter to jobs with ignore count ≤ this value.
+        - name: numIgnore_gte
+          in: query
+          schema:
+            type: integer
+            examples:
+              - 1
+          description: Filter to jobs with ignore count ≥ this value.
+        - name: numError_gte
+          in: query
+          schema:
+            type: integer
+            examples:
+              - 1
+          description: |-
+            Filter to jobs with error count ≥ this value. When combined with
+            `_integrationId`, the query may reject plain-date `createdAt`
+            values — use full ISO 8601.
+        - name: numError_lte
+          in: query
+          schema:
+            type: integer
+            examples:
+              - 10
+          description: |-
+            Filter to jobs with error count ≤ this value. Same date-format
+            caveat as `numError_gte`.
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum:
+              - flow
+              - export
+              - import
+              - retry
+              - bulk_retry
+            x-enumDescriptions:
+              flow: A parent flow-run job that orchestrates the full pipeline.
+              export: A child job for an export step within a flow run.
+              import: A child job for an import step within a flow run.
+              retry: A retry of a single failed record from a previous job.
+              bulk_retry: A bulk retry of multiple failed records from a previous job.
+          description: |-
+            Filter by job type. `flow`, `retry`, and `bulk_retry` are
+            parent-level jobs; `export` and `import` are child jobs (require
+            `_flowJobId` or a resource-ID filter). Unrecognized values silently
+            return an empty response.
+      responses:
+        '200':
+          description: Array of job records matching the filters.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Job'
+              examples:
+                parent_flow_jobs:
+                  summary: Two completed flow runs
+                  value:
+                    - _id: 69f54d6f47185f8c7a500597
+                      type: flow
+                      status: completed
+                      _integrationId: 6842261335b64c0bcb308e4f
+                      _flowId: 69f54d6b7009ea11abad707a
+                      _exportId: 69f54d6a3469e3f5597848a1
+                      startedAt: '2026-05-02T01:03:43.640Z'
+                      endedAt: '2026-05-02T01:03:51.757Z'
+                      createdAt: '2026-05-02T01:03:43.640Z'
+                      lastModified: '2026-05-02T01:03:51.757Z'
+                      lastExecutedAt: '2026-05-02T01:03:51.757Z'
+                      numSuccess: 10
+                      numError: 10
+                      numOpenError: 10
+                      numResolved: 0
+                      numIgnore: 0
+                      numExport: 0
+                      numPagesGenerated: 10
+                      numPagesProcessed: 10
+                      doneExporting: false
+                      logMode: basic
+                      flowExecutionGroupId: 70f3bd04a01142b29031e36ccff9242b
+                      purgeAt: '2026-06-01T01:03:43.577Z'
+                      clickhousePurgeAt: '2026-06-01T01:03:43.577Z'
+                    - _id: 69e9820a12e2a80e73166a8a
+                      type: flow
+                      status: failed
+                      _integrationId: 6842261335b64c0bcb308e4f
+                      _flowId: 69f54d6b7009ea11abad707a
+                      _exportId: 69f54d6a3469e3f5597848a1
+                      startedAt: '2026-04-20T14:22:18.000Z'
+                      endedAt: '2026-04-20T14:22:25.412Z'
+                      createdAt: '2026-04-20T14:22:18.000Z'
+                      lastModified: '2026-04-20T14:22:25.412Z'
+                      lastExecutedAt: '2026-04-20T14:22:25.412Z'
+                      numSuccess: 0
+                      numError: 5
+                      numOpenError: 5
+                      numResolved: 0
+                      numIgnore: 0
+                      numExport: 0
+                      numPagesGenerated: 1
+                      numPagesProcessed: 1
+                      doneExporting: true
+                      logMode: basic
+                      flowExecutionGroupId: a3b1c2d4e5f6071829304050
+                      purgeAt: '2026-05-20T14:22:18.000Z'
+        '204':
+          description: No jobs match the given filters.
+        '400':
+          description: Required query parameters are missing or invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                parent_job_missing_params:
+                  summary: Parent job query missing required filter
+                  value:
+                    errors:
+                      - code: invalid_query
+                        message: For parent jobs, query parameters must contain either "_integrationId" or "_jobId" or "createdAt"
+                child_job_missing_params:
+                  summary: Child job query missing required filter
+                  value:
+                    errors:
+                      - code: invalid_query
+                        message: For child jobs, query parameters must contain either "_flowJobId" or "resourceId"
+                invalid_status:
+                  summary: Invalid status enum value
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: The query parameter "status" has invalid value.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/jobs/current:
+    post:
+      x-internal: false
+      operationId: listCurrentJobs
+      tags:
+        - Jobs
+      summary: List in-progress jobs (dashboard)
+      description: |-
+        Returns a paginated list of currently in-progress jobs for the dashboard -- jobs whose `status` is one of
+        `queued`, `running`, or `canceling`. Jobs that have reached a terminal state (`completed`, `failed`,
+        `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).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JobsCurrentRequest'
+            examples:
+              production_all:
+                summary: All in-progress production jobs
+                value: {}
+              specific_flow_queued:
+                summary: In-progress jobs for a specific flow
+                value:
+                  _flowIds:
+                    - 69497fc443fc1f9a03d31bd9
+                  status:
+                    - queued
+                    - running
+      responses:
+        '200':
+          description: One page of in-progress jobs.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobsCurrentResponse'
+              examples:
+                one_page:
+                  summary: One queued retry job — single page, so no pagingPostBody
+                  value:
+                    jobs:
+                      - _id: 69e9958f815ae7eae3d9146b
+                        type: retry
+                        _importId: 69e9953d7a8373d88147b5ec
+                        _flowId: 69e99544f3a2ac489d0f7953
+                        status: queued
+                        numSuccess: 0
+                        numError: 0
+                        numResolved: 0
+                        numOpenError: 0
+                        createdAt: '2026-04-23T03:44:15.515Z'
+                        lastModified: '2026-04-23T03:44:15.532Z'
+        '204':
+          description: No in-progress jobs match the filter.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+      x-celigo-ai-guidance:
+        - |-
+          Returns a paged collection of currently running jobs for the dashboard.
+          The request body supports filtering by integration, flow, status, and
+          application.  The platform requires ``sandbox`` in the body; Ora is
+          production-only so it always sends ``false``.
+  /v1/flows/runs/stats:
+    post:
+      x-internal: false
+      operationId: getFlowRunsStats
+      tags:
+        - Jobs
+      summary: Get per-flow run statistics (dashboard aggregates)
+      description: |-
+        Returns **per-flow aggregate** run statistics — one element of `stats[]` per flow that has at least
+        one run matching the request filter. Each aggregate carries totals (`numRuns`, `numSuccess`,
+        `numError`, `numIgnore`), the currently-open error count (`numOpenError`), resolution attribution
+        (`numResolvedByAuto` / `numResolvedByUser`), average runtime (`avgRuntime`), and timestamps
+        (`lastExecutedAt`, `lastErrorAt`) plus a minimal inlined `flow{}` object for rendering.
+
+        The Celigo dashboard uses this to paint its "All flows" summary in one call. Filters (`_flowIds`,
+        `_integrationIds`, `time_gt`, `time_lte`, …) narrow which runs are rolled up into each aggregate —
+        they do **not** filter which flows appear; flows with zero matching runs are simply omitted.
+
+        **The window is the contract.** When `time_gt` is omitted the endpoint applies its default
+        window (approximately the last 24 hours) rather than aggregating all history — runs older than
+        the window silently drop out of every aggregate. Send `time_gt` explicitly for any other range.
+
+        For individual job records rather than aggregates, use `GET /v1/jobs?_flowId=...`. For in-progress
+        jobs, use `POST /v1/jobs/current`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FlowRunsStatsRequest'
+            examples:
+              default_window:
+                summary: Default window (approximately the last 24 hours)
+                value: {}
+              last_15d_all_flows:
+                summary: All flows, runs in the last 15 days
+                value:
+                  time_gt: 1744070400000
+              last_24h_for_flow:
+                summary: One flow, runs in the last 24 hours
+                value:
+                  _flowIds:
+                    - 69497fc443fc1f9a03d31bd9
+                  time_gt: 1745366400000
+      responses:
+        '200':
+          description: One page of per-flow aggregates.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FlowRunsStatsResponse'
+              examples:
+                two_flows:
+                  summary: Two flows — one healthy, one with open errors
+                  value:
+                    stats:
+                      - _flowId: 69497fc443fc1f9a03d31bd9
+                        _integrationId: 69496f01615f724066afaac2
+                        numRuns: 91
+                        numPages: 92
+                        numSuccess: 184
+                        numError: 0
+                        numIgnore: 0
+                        numOpenError: 3
+                        numResolvedByAuto: 7
+                        numResolvedByUser: 0
+                        avgRuntime: 172327.86
+                        lastExecutedAt: '2026-04-23T02:51:52.551Z'
+                        lastErrorAt: '2026-04-21T10:51:13.221Z'
+                        flow:
+                          _id: 69497fc443fc1f9a03d31bd9
+                          name: Shopee
+                          _integrationId: 69496f01615f724066afaac2
+                          integrationName: Shopee
+                      - _flowId: 69e83e7a75f7f8c14a12916e
+                        numRuns: 2
+                        numPages: 8
+                        numSuccess: 276
+                        numError: 0
+                        numIgnore: 0
+                        numOpenError: 0
+                        numResolvedByAuto: 0
+                        numResolvedByUser: 0
+                        avgRuntime: 20904.5
+                        lastExecutedAt: '2026-04-22T03:27:00.491Z'
+                        flow:
+                          _id: 69e83e7a75f7f8c14a12916e
+                          name: New flow
+        '204':
+          description: No runs match the filter on any flow within the queried window (the ~24-hour default when no `time_gt` was sent).
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/jobs/family:
+    post:
+      x-internal: false
+      operationId: getJobFamilyBatch
+      tags:
+        - Jobs
+      summary: Batch-fetch job families
+      description: |-
+        Returns job families for an array of job ids, in one request. Each item in the response array has the same
+        shape as a single `GET /v1/jobs/{_id}/family` call (a parent job with inlined `children`).
+
+        **Size limit: 1000 ids per request.** The server rejects requests with more than 1000 entries with HTTP
+        **403** (not 400) and `{code: "invalid_request", message: "Number of objects in the request exceeds
+        maximum allowed limit 1000"}`. The Celigo UI chunks at 50 for its own UX reasons, but the API ceiling
+        is 1000.
+
+        **Mixed-id behavior (asymmetric):**
+        - Valid + unknown 24-hex ids in the same array → **200** with only the resolved entries; unknown ids are
+          silently dropped (no `errors[]` alongside).
+        - All ids unknown → **404** with `{errors: [{code: "invalid_ref", source: "internal", message: "Job not
+          found: <id>"}]}`.
+        - Any id that isn't a 24-char hex string anywhere in the array → **400** `invalid_ref "Please provide
+          a valid _id."` — the whole request fails.
+        - Duplicate ids are **deduped** server-side (same id ×N → one entry).
+        - Empty array `[]` or non-array body (e.g. `{}`) → **400** `invalid_request "Request body should be an
+          ObjectID array."`.
+        - Missing `Content-Type: application/json` → **415** `{message: "Content-Type should equal
+          application/json"}`.
+
+        The response array has no guaranteed ordering; match items by `_id` rather than by index. Unknown ids are
+        silently dropped -- callers that need to detect missing ids must diff the request and response id sets.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JobsFamilyBatchRequest'
+            examples:
+              default:
+                value:
+                  - 69e981ee18808f3e5ed1b2fd
+                  - 69e9820a12e2a80e73166a8a
+      responses:
+        '200':
+          description: An array of job families, one per **resolved** id (unknown ids silently dropped).
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/JobWithChildren'
+              examples:
+                resolved_families:
+                  summary: Families for both requested ids (children trimmed for brevity)
+                  value:
+                    - _id: 69e981ee18808f3e5ed1b2fd
+                      type: flow
+                      status: completed
+                      _flowId: 69a9aa5c54e3d9bd11b86d82
+                      createdAt: '2026-04-23T02:51:39.812Z'
+                      lastModified: '2026-04-23T02:52:10.115Z'
+                      startedAt: '2026-04-23T02:51:40.000Z'
+                      endedAt: '2026-04-23T02:52:10.000Z'
+                      numSuccess: 42
+                      numError: 0
+                      numIgnore: 1
+                      children: []
+                    - _id: 69e9820a12e2a80e73166a8a
+                      type: flow
+                      status: failed
+                      _integrationId: 6842261335b64c0bcb308e4f
+                      _flowId: 69f54d6b7009ea11abad707a
+                      _exportId: 69f54d6a3469e3f5597848a1
+                      createdAt: '2026-04-20T14:22:17.804Z'
+                      lastModified: '2026-04-20T14:22:25.598Z'
+                      startedAt: '2026-04-20T14:22:18.000Z'
+                      endedAt: '2026-04-20T14:22:25.412Z'
+                      numSuccess: 0
+                      numError: 5
+                      numOpenError: 5
+                      numResolved: 0
+                      numIgnore: 0
+                      children: []
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '415':
+          description: 'Returned when the request is missing the `Content-Type: application/json` header.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/jobs/{_id}:
+    get:
+      x-internal: false
+      operationId: getJobById
+      tags:
+        - Jobs
+      summary: Get a job
+      description: |-
+        Returns a single job record. Works for both parent jobs (`type=flow`, `retry`, `bulk_retry`) and child jobs
+        (`type=export`, `type=import`). For the full parent+children view of a flow run, use
+        `GET /v1/jobs/{_id}/family` instead. For a multi-job lookup, use `POST /v1/jobs/family`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Job id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: jobs
+            examples:
+              - 69f54d6f47185f8c7a500597
+      responses:
+        '200':
+          description: The job record.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+              examples:
+                completed_flow_job:
+                  summary: A completed parent flow job
+                  value:
+                    _id: 69f54d6f47185f8c7a500597
+                    type: flow
+                    status: completed
+                    _integrationId: 6842261335b64c0bcb308e4f
+                    _flowId: 69f54d6b7009ea11abad707a
+                    _exportId: 69f54d6a3469e3f5597848a1
+                    startedAt: '2026-05-02T01:03:43.640Z'
+                    endedAt: '2026-05-02T01:03:51.757Z'
+                    createdAt: '2026-05-02T01:03:43.640Z'
+                    lastModified: '2026-05-02T01:03:51.757Z'
+                    lastExecutedAt: '2026-05-02T01:03:51.757Z'
+                    numSuccess: 10
+                    numError: 10
+                    numOpenError: 10
+                    numResolved: 0
+                    numIgnore: 0
+                    numExport: 0
+                    numPagesGenerated: 10
+                    numPagesProcessed: 10
+                    doneExporting: false
+                    logMode: basic
+                    flowExecutionGroupId: 70f3bd04a01142b29031e36ccff9242b
+                    purgeAt: '2026-06-01T01:03:43.577Z'
+                    clickhousePurgeAt: '2026-06-01T01:03:43.577Z'
+        '400':
+          description: The `_id` is not a valid ObjectId.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_ref:
+                  summary: Invalid ObjectId format
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _jobId.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: No job exists with the given ID.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  summary: Job does not exist
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Job not found.
+  /v1/jobs/{_id}/family:
+    get:
+      x-internal: false
+      operationId: getJobFamily
+      tags:
+        - Jobs
+      summary: Get a job and its children
+      description: |-
+        Returns a single job record (as parent) with all of its child jobs inlined under `children`.
+
+        A "job family" maps to one flow execution: the parent is a `type: "flow"` job and the children are the
+        `export` / `import` / `retry` jobs that ran as part of it. For non-flow jobs (a standalone export run, or a
+        retry), `children` may be empty.
+
+        For fetching many families at once, batch via `POST /v1/jobs/family`. The parent's counters may not include
+        bulk-retry jobs spawned after the initial run -- aggregate across `children` for an accurate per-run summary.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Job id. Typically a parent flow job id, but any job id is accepted.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: jobs
+            examples:
+              - 69f54d6f47185f8c7a500597
+      responses:
+        '200':
+          description: Job family (parent with inlined children).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobWithChildren'
+              examples:
+                flow_with_children:
+                  summary: Flow run with export and import children
+                  value:
+                    _id: 69f54d6f47185f8c7a500597
+                    type: flow
+                    status: completed
+                    _integrationId: 6842261335b64c0bcb308e4f
+                    _flowId: 69f54d6b7009ea11abad707a
+                    _exportId: 69f54d6a3469e3f5597848a1
+                    startedAt: '2026-05-02T01:03:43.640Z'
+                    endedAt: '2026-05-02T01:03:51.757Z'
+                    createdAt: '2026-05-02T01:03:43.640Z'
+                    lastModified: '2026-05-02T01:03:51.757Z'
+                    lastExecutedAt: '2026-05-02T01:03:51.757Z'
+                    numSuccess: 10
+                    numError: 10
+                    numOpenError: 10
+                    numResolved: 0
+                    numIgnore: 0
+                    numExport: 0
+                    numPagesGenerated: 10
+                    numPagesProcessed: 10
+                    doneExporting: false
+                    logMode: basic
+                    flowExecutionGroupId: 70f3bd04a01142b29031e36ccff9242b
+                    purgeAt: '2026-06-01T01:03:43.577Z'
+                    clickhousePurgeAt: '2026-06-01T01:03:43.577Z'
+                    children:
+                      - _id: 69f54d6f47185f8c7a5005e9
+                        type: export
+                        status: completed
+                        _parentJobId: 69f54d6f47185f8c7a500597
+                        _expOrImpId: 69f54d6a3469e3f5597848a1
+                        startedAt: '2026-05-02T01:03:43.813Z'
+                        endedAt: '2026-05-02T01:03:49.930Z'
+                        createdAt: '2026-05-02T01:03:43.813Z'
+                        lastModified: '2026-05-02T01:03:49.930Z'
+                        lastExecutedAt: '2026-05-02T01:03:49.930Z'
+                        numSuccess: 10
+                        numError: 0
+                        numOpenError: 0
+                        numResolved: 0
+                        numIgnore: 0
+                        numExport: 0
+                        numPagesGenerated: 10
+                        numPagesProcessed: 0
+                        logMode: basic
+                        purgeAt: '2026-06-01T01:03:43.577Z'
+                        clickhousePurgeAt: '2026-06-01T01:03:43.577Z'
+                      - _id: 69f54d6f47185f8c7a500611
+                        type: import
+                        status: completed
+                        _parentJobId: 69f54d6f47185f8c7a500597
+                        _expOrImpId: 69f54d6c1e7f3a22cc7848b2
+                        startedAt: '2026-05-02T01:03:43.948Z'
+                        endedAt: '2026-05-02T01:03:51.736Z'
+                        createdAt: '2026-05-02T01:03:43.948Z'
+                        lastModified: '2026-05-02T01:03:51.736Z'
+                        lastExecutedAt: '2026-05-02T01:03:51.735Z'
+                        numSuccess: 0
+                        numError: 10
+                        numOpenError: 10
+                        numResolved: 0
+                        numIgnore: 0
+                        numExport: 0
+                        numPagesGenerated: 0
+                        numPagesProcessed: 10
+                        logMode: basic
+                        purgeAt: '2026-06-01T01:03:43.577Z'
+                        clickhousePurgeAt: '2026-06-01T01:03:43.577Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/jobs/{_id}/cancel:
+    put:
+      x-internal: false
+      operationId: cancelJob
+      tags:
+        - Jobs
+      summary: Cancel a job
+      description: |-
+        Requests cancellation of a running or queued job. The job's `status` transitions to `canceling` and, once the
+        platform has stopped in-flight work, to `canceled`. This is **not** synchronous — the response returns the
+        updated job record with `status: "canceling"`; consumers should poll (e.g. `GET /v1/jobs/{_id}`) to observe
+        the final `canceled` state.
+
+        Only jobs that are still in progress (`queued`, `running`, `retrying`) can be canceled. Canceling a job
+        that is already terminal returns an error.
+
+        Cancel at the flow-run (parent) level rather than individual export/import children -- child cancellations
+        can leave the parent in an inconsistent state.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Job id to cancel.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: jobs
+            examples:
+              - 69e9958f815ae7eae3d9146b
+      responses:
+        '200':
+          description: 'Updated job record with `status: "canceling"`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+              examples:
+                canceling:
+                  summary: Queued retry job transitioning to canceling
+                  value:
+                    _id: 69e9958f815ae7eae3d9146b
+                    type: retry
+                    _importId: 69e9953d7a8373d88147b5ec
+                    _flowId: 69e99544f3a2ac489d0f7953
+                    status: canceling
+                    numSuccess: 0
+                    numError: 0
+                    numResolved: 0
+                    numOpenError: 0
+                    createdAt: '2026-04-23T03:44:15.515Z'
+                    lastModified: '2026-04-23T03:45:02.118Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            The job is already in a terminal state and cannot be canceled.
+            Error code `job_already_ended`; the message names the job's current
+            terminal state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                job_already_ended:
+                  summary: Cancel attempted on a job that already ended
+                  value:
+                    errors:
+                      - code: job_already_ended
+                        message: The job is already in failed state.
+                        source: internal
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/jobs/{_id}/files/signedURL:
+    post:
+      x-internal: false
+      operationId: getJobFilesSignedUrl
+      tags:
+        - Jobs
+      summary: Get signed URL(s) to download job files
+      description: |-
+        Returns short-lived S3 pre-signed URLs for downloading files produced by the job (e.g. the rows exported to
+        a CSV, an error-record dump, or a page-processor artifact). The URLs are typically valid for ~15 minutes.
+
+        If `fileIds` is omitted in the request body, all of the job's current file artifacts are returned. If
+        provided, only the matching files are included.
+
+        Inspect the job's `files[]` array first (via `GET /v1/jobs/{_id}`) to discover available file IDs. Jobs
+        with no files (common for `import` child jobs or jobs past `purgeAt`) return `204 No Content`. File ids
+        are registered per job: if none of the requested `fileIds` are registered to this job (e.g. the file id
+        belongs to a different job's run), the endpoint also returns `204 No Content` with an empty body rather
+        than an error. The URLs expire after approximately 15 minutes -- fetch immediately, do not persist.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Job id whose files should be downloaded.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: jobs
+            examples:
+              - 69f54d6f47185f8c7a500597
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JobFilesSignedUrlRequest'
+            examples:
+              all_files:
+                summary: Download every file for the job
+                value: {}
+              specific_file:
+                summary: Download a specific file by id
+                value:
+                  fileIds:
+                    - 694b97c4f4f1f4a1b9d9e001
+      responses:
+        '201':
+          description: One or more signed URLs.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobFilesSignedUrlResponse'
+              examples:
+                single_file:
+                  summary: One requested file — signedURLs array with one element
+                  value:
+                    signedURLs:
+                      - https://integrator-templates.s3.us-east-1.amazonaws.com/694b97c4f4f1f4a1b9d9e001.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=...
+        '204':
+          description: |-
+            Job has no downloadable files, or none of the requested `fileIds` are registered to this job; the
+            response body is empty.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/jobs/{_id}/files:
+    delete:
+      x-internal: false
+      operationId: purgeJobFiles
+      tags:
+        - Jobs
+      summary: Purge a job's stored files
+      description: |-
+        Deletes **all** file artifacts associated with the job (exported rows, error-record dumps, page-processor
+        artifacts, etc.) from underlying storage. After a successful call, `GET /v1/jobs/{_id}` will show an empty
+        `files[]` array and `POST /v1/jobs/{_id}/files/signedURL` will return `204 No Content`.
+
+        The job record itself is retained -- only the files are purged. This is irreversible. The platform also
+        purges files automatically at `purgeAt` / `clickhousePurgeAt`; manual purge is only needed for
+        storage-quota management or compliance workflows.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Job id whose files should be purged.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: jobs
+            examples:
+              - 69f54d6f47185f8c7a500597
+      responses:
+        '204':
+          description: Files purged successfully.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/jobs/{_id}/diagnostics:
+    get:
+      x-internal: false
+      operationId: getJobDiagnostics
+      tags:
+        - Jobs
+      summary: Get a signed URL for job diagnostics
+      description: |-
+        Returns a short-lived S3 pre-signed URL pointing to a diagnostic archive (`.zip`) for the given job. The
+        archive contains server-side traces/logs that Celigo support uses to debug execution failures.
+
+        The URL is typically valid for ~15 minutes (enforced by S3). Consumers should fetch the archive immediately
+        rather than storing the URL.
+
+        This is distinct from flow execution logs -- use `GET /v1/flows/{_id}/jobs/{_jobId}/logs` for step-level
+        execution logs. Jobs with no diagnostics (very recent, or past `purgeAt`) return 204.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Job id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: jobs
+            examples:
+              - 69e981ee18808f3e5ed1b2fd
+      responses:
+        '200':
+          description: Signed URL for the diagnostics archive.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobDiagnosticsResponse'
+              examples:
+                default:
+                  value:
+                    signedURL: https://integrator-templates.s3.us-east-1.amazonaws.com/diagnostics-69e981ee18808f3e5ed1b2fd.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=...
+        '204':
+          description: No diagnostics available for this job (archive may be absent or purged).
+        '400':
+          description: |-
+            The job does not support diagnostics downloads (`invalid_request`) —
+            diagnostics can only be downloaded for jobs with an associated
+            diagnostics archive.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/flows/{_id}/jobs/latest:
+    get:
+      x-internal: false
+      operationId: getLatestFlowJobs
+      tags:
+        - Jobs
+      summary: Get the most recent job(s) for a flow
+      description: |-
+        Returns the most recent job record(s) for the given flow. Typically one entry (the latest flow run), though
+        the platform may include related retry jobs depending on account configuration. For a richer parent+children
+        view, feed the returned `_id` into `GET /v1/jobs/{_id}/family`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Flow id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: flows
+            examples:
+              - 69f54d6b7009ea11abad707a
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+      responses:
+        '200':
+          description: Most recent job(s) for the flow. May be a single-element array.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Job'
+              examples:
+                latest_run:
+                  summary: Most recent flow run
+                  value:
+                    - _id: 69f54d6f47185f8c7a500597
+                      type: flow
+                      status: completed
+                      _integrationId: 6842261335b64c0bcb308e4f
+                      _flowId: 69f54d6b7009ea11abad707a
+                      _exportId: 69f54d6a3469e3f5597848a1
+                      startedAt: '2026-05-02T01:03:43.640Z'
+                      endedAt: '2026-05-02T01:03:51.757Z'
+                      createdAt: '2026-05-02T01:03:43.640Z'
+                      lastModified: '2026-05-02T01:03:51.757Z'
+                      lastExecutedAt: '2026-05-02T01:03:51.757Z'
+                      numSuccess: 10
+                      numError: 0
+                      numOpenError: 0
+                      numResolved: 0
+                      numIgnore: 0
+                      numPagesGenerated: 10
+                      numPagesProcessed: 10
+                      doneExporting: true
+                      logMode: basic
+                      flowExecutionGroupId: 70f3bd04a01142b29031e36ccff9242b
+                      purgeAt: '2026-06-01T01:03:43.577Z'
+        '204':
+          description: The flow has no recorded runs.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/jobs/latest:
+    get:
+      x-internal: false
+      operationId: getLatestIntegrationJobs
+      tags:
+        - Jobs
+      summary: Get the most recent job(s) for an integration
+      description: |-
+        Returns the most recent job record(s) across all flows in the given integration. Useful for a top-level
+        status check on an integration. The result is not filtered by status -- inspect each entry's `status` to
+        distinguish success from failure.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Most recent job(s) for the integration.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Job'
+              examples:
+                latest_across_flows:
+                  summary: Most recent jobs from two flows in the integration
+                  value:
+                    - _id: 69f54d6f47185f8c7a500597
+                      type: flow
+                      status: completed
+                      _integrationId: 6842261335b64c0bcb308e4f
+                      _flowId: 69f54d6b7009ea11abad707a
+                      _exportId: 69f54d6a3469e3f5597848a1
+                      startedAt: '2026-05-02T01:03:43.640Z'
+                      endedAt: '2026-05-02T01:03:51.757Z'
+                      createdAt: '2026-05-02T01:03:43.640Z'
+                      lastModified: '2026-05-02T01:03:51.757Z'
+                      numSuccess: 10
+                      numError: 0
+                      numOpenError: 0
+                      numResolved: 0
+                      numIgnore: 0
+                      logMode: basic
+                    - _id: 69e9820a12e2a80e73166a8a
+                      type: flow
+                      status: failed
+                      _integrationId: 6842261335b64c0bcb308e4f
+                      _flowId: 69e83e7a75f7f8c14a12916e
+                      _exportId: 69e83e7a75f7f8c14a129170
+                      startedAt: '2026-04-20T14:22:18.000Z'
+                      endedAt: '2026-04-20T14:22:25.412Z'
+                      createdAt: '2026-04-20T14:22:18.000Z'
+                      lastModified: '2026-04-20T14:22:25.412Z'
+                      numSuccess: 0
+                      numError: 5
+                      numOpenError: 5
+                      numResolved: 0
+                      numIgnore: 0
+                      logMode: basic
+        '204':
+          description: The integration has no recorded runs.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    JobFileRef:
+      type: object
+      description: Reference to a file produced by a job.
+      properties:
+        id:
+          type: string
+          description: File id in the underlying storage provider.
+          examples:
+            - 694b97c4f4f1f4a1b9d9e001
+        host:
+          type: string
+          description: Storage host/provider.
+          enum:
+            - netsuite
+            - s3
+          x-enumDescriptions:
+            netsuite: File stored in the NetSuite file cabinet.
+            s3: File stored in Amazon S3.
+        name:
+          type: string
+          description: Display name for the file (if available).
+          examples:
+            - success_records.csv
+    JobLogRef:
+      type: object
+      description: Reference to a job log artifact.
+      properties:
+        id:
+          type: string
+          description: Log id in the underlying storage provider.
+          examples:
+            - '48217'
+        host:
+          type: string
+          description: Storage host/provider.
+          enum:
+            - netsuite
+          x-enumDescriptions:
+            netsuite: Log stored in the NetSuite file cabinet.
+    JobErrorFileRef:
+      type: object
+      description: Reference to an error file produced by a job.
+      properties:
+        id:
+          type: string
+          description: Error file id in the underlying storage provider.
+          examples:
+            - 694b97c4f4f1f4a1b9d9e001
+        host:
+          type: string
+          description: Storage host/provider.
+          enum:
+            - s3
+          x-enumDescriptions:
+            s3: Error file stored in Amazon S3.
+    Job:
+      type: object
+      required:
+        - _id
+        - type
+        - status
+        - createdAt
+        - lastModified
+      description: |
+        A job represents one execution of a flow/export/import (or a retry) in integrator.io.
+        Jobs are read-only records created by the platform when executions occur.
+
+        Parent jobs (`type: flow`) carry aggregate counters; child jobs (`type: export` or `import`)
+        carry per-step counters -- do not sum both to avoid double-counting. `_exportId` on a parent
+        flow job references the page-generator export, not all exports in the flow.
+      allOf:
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            type:
+              type: string
+              readOnly: true
+              description: Job type.
+              enum:
+                - export
+                - import
+                - flow
+                - retry
+                - bulk_retry
+              x-enumDescriptions:
+                export: A child job for an export step within a flow run.
+                import: A child job for an import step within a flow run.
+                flow: A parent flow-run job that orchestrates the full pipeline.
+                retry: A retry of a single failed record from a previous job.
+                bulk_retry: A bulk retry of multiple failed records from a previous job.
+              x-celigo-ai-guidance:
+                - |-
+                  - `flow`: a flow run (parent job)
+                  - `export` / `import`: child jobs for an export/import step
+                  - `retry` / `bulk_retry`: error management retries
+            status:
+              type: string
+              readOnly: true
+              description: Current job status.
+              enum:
+                - queued
+                - running
+                - retrying
+                - completed
+                - failed
+                - canceled
+                - canceling
+              x-enumDescriptions:
+                queued: Job is waiting to be picked up for execution.
+                running: Job is currently executing.
+                retrying: Job is being retried after a previous failure.
+                completed: Job finished successfully.
+                failed: Job finished with a fatal error.
+                canceled: Job was canceled by a user or the system.
+                canceling: Job cancellation has been requested but execution has not yet stopped.
+            _integrationId:
+              type: string
+              format: objectId
+              x-celigo-refModel: integrations
+              readOnly: true
+              description: Integration id this job belongs to (if applicable).
+              examples:
+                - 6842261335b64c0bcb308e4f
+            _flowId:
+              type: string
+              format: objectId
+              x-celigo-refModel: flows
+              readOnly: true
+              description: Flow id this job belongs to (if applicable).
+              examples:
+                - 69f54d6b7009ea11abad707a
+            _exportId:
+              type: string
+              format: objectId
+              x-celigo-refModel: exports
+              readOnly: true
+              description: |-
+                Export id. Present on child export jobs and also on parent flow
+                jobs (where it references the first page-generator export).
+              examples:
+                - 69f54d6a3469e3f5597848a1
+            _importId:
+              type: string
+              format: objectId
+              x-celigo-refModel: imports
+              readOnly: true
+              description: Import id for import child jobs (if applicable).
+              examples:
+                - 69e9953d7a8373d88147b5ec
+            _expOrImpId:
+              type: string
+              format: objectId
+              readOnly: true
+              description: |-
+                The export or import resource ID for this child job. Present on child
+                jobs (`type: export` or `type: import`) — check `type` to determine
+                whether this references an export or import resource.
+              examples:
+                - 69f54d6c1e7f3a22cc7848b2
+            _retryOfJobId:
+              type: string
+              format: objectId
+              x-celigo-refModel: jobs
+              readOnly: true
+              description: If this is a retry job, the original job id being retried.
+              examples:
+                - 69e9820a12e2a80e73166a8a
+            _flowJobId:
+              type: string
+              format: objectId
+              x-celigo-refModel: jobs
+              readOnly: true
+              description: Parent flow job id (for child jobs).
+              examples:
+                - 69f54d6f47185f8c7a500597
+            _userId:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              readOnly: true
+              description: Owner user id for the job.
+            _parentJobId:
+              type: string
+              format: objectId
+              x-celigo-refModel: jobs
+              readOnly: true
+              description: Parent job id (used for branched flows / hierarchy).
+              examples:
+                - 69f54d6f47185f8c7a500597
+            _bulkJobId:
+              type: string
+              format: objectId
+              x-celigo-refModel: jobs
+              readOnly: true
+              description: Bulk retry parent job id (if applicable).
+              examples:
+                - 69e981ee18808f3e5ed1b2fd
+            startedAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: When execution started.
+              examples:
+                - '2026-05-02T01:03:43.640Z'
+            endedAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: When execution ended.
+              examples:
+                - '2026-05-02T01:03:51.757Z'
+            resolvedAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: When errors for the job were fully resolved (if applicable).
+              examples:
+                - '2026-05-02T02:15:00.000Z'
+            lastExecutedAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: Last time the job executed work (may differ from createdAt/startedAt).
+              examples:
+                - '2026-05-02T01:03:51.757Z'
+            purgeAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: When the job should be purged from primary storage.
+              examples:
+                - '2026-06-01T01:03:43.577Z'
+            clickhousePurgeAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: When the job's analytics data expires.
+              examples:
+                - '2026-06-01T01:03:43.577Z'
+            triggeredBy:
+              type: string
+              readOnly: true
+              description: Who/what triggered the job (free-form string).
+              examples:
+                - scheduler
+            canceledBy:
+              type: string
+              readOnly: true
+              description: Who/what requested cancellation (free-form string).
+              examples:
+                - user
+            flowExecutionGroupId:
+              type: string
+              readOnly: true
+              description: Groups multiple related jobs for a single flow execution.
+              examples:
+                - 70f3bd04a01142b29031e36ccff9242b
+            numError:
+              type: integer
+              readOnly: true
+              description: |
+                Total number of errors produced by the job (including resolved ones).
+                Use `numOpenError` for the count of currently unresolved errors.
+              examples:
+                - 10
+            numOpenError:
+              type: integer
+              readOnly: true
+              description: |
+                Number of unresolved errors (equivalent to `numError - numResolved`).
+                This is the value dashboards surface as "errors needing attention."
+              examples:
+                - 10
+            numResolved:
+              type: integer
+              readOnly: true
+              description: Number of resolved errors.
+              examples:
+                - 0
+            numResolvedByAdaptor:
+              type: integer
+              readOnly: true
+              description: Number of errors resolved by the adaptor.
+              examples:
+                - 0
+            numSuccess:
+              type: integer
+              readOnly: true
+              description: Number of successful records/pages.
+              examples:
+                - 10
+            numIgnore:
+              type: integer
+              readOnly: true
+              description: Number of ignored records/pages.
+              examples:
+                - 0
+            numExport:
+              type: integer
+              readOnly: true
+              description: |
+                Legacy field used by retry logic. May be deprecated.
+              examples:
+                - 0
+            numPagesGenerated:
+              type: integer
+              readOnly: true
+              description: Number of pages generated by an export/page generator.
+              examples:
+                - 10
+            doneExporting:
+              type: boolean
+              readOnly: true
+              description: When true, all export pages have been generated.
+            numPagesProcessed:
+              type: integer
+              readOnly: true
+              description: Number of pages processed by downstream imports.
+              examples:
+                - 10
+            oIndex:
+              type: integer
+              readOnly: true
+              description: Branch/router index for branched flows (if applicable).
+              examples:
+                - 0
+            retriable:
+              type: boolean
+              readOnly: true
+              description: When true, this job is eligible for retry.
+            files:
+              type: array
+              readOnly: true
+              description: Files produced by the job (may be empty).
+              items:
+                $ref: '#/components/schemas/JobFileRef'
+            logs:
+              type: array
+              readOnly: true
+              description: Log artifacts associated with the job (may be empty).
+              items:
+                $ref: '#/components/schemas/JobLogRef'
+            errorFile:
+              description: Error file artifact (if any).
+              allOf:
+                - $ref: '#/components/schemas/JobErrorFileRef'
+                - description: Error file artifact (if any).
+            logMode:
+              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),
+                `off`, `on`, `debug`.
+              examples:
+                - basic
+            __lastPageGeneratorJob:
+              type: boolean
+              readOnly: true
+              description: When true, indicates the last page-generator job in the sequence. Internal use only.
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    JobsCurrentRequest:
+      type: object
+      description: |
+        Request body for `POST /v1/jobs/current`.
+        The UI uses this to fetch in-progress jobs for the dashboard.
+      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
+        status:
+          type: array
+          description: |
+            Optional filter for in-progress job statuses.
+            Terminal statuses (`completed`, `failed`, `canceled`, `retried`) are rejected with HTTP 400 by this endpoint —
+            use `POST /v1/flows/runs/stats` for completed-run history.
+          items:
+            type: string
+            enum:
+              - queued
+              - running
+              - canceling
+            x-enumDescriptions:
+              queued: Job is waiting to be picked up for execution.
+              running: Job is currently executing.
+              canceling: Job cancellation has been requested but execution has not yet stopped.
+        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: Optional filter for jobs with `createdAt`/time greater than this epoch milliseconds.
+          examples:
+            - 1745366400000
+        time_lte:
+          type: integer
+          format: int64
+          description: Optional filter for jobs with `createdAt`/time less than or equal to this epoch milliseconds.
+          examples:
+            - 1746147600000
+      required: []
+    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'
+    JobsCurrentResponse:
+      type: object
+      description: Response envelope for `POST /v1/jobs/current`.
+      properties:
+        jobs:
+          type: array
+          description: Current (in-progress) jobs.
+          items:
+            $ref: '#/components/schemas/JobWithChildren'
+        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
+            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'
+    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.
+
+            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.
+          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".
+            - 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.
+    FlowRunStatsEntry:
+      type: object
+      description: |-
+        Per-flow aggregate across all matching runs. Produced by `POST /v1/flows/runs/stats` and used to
+        populate the Celigo dashboard's per-flow summary cards.
+      properties:
+        _flowId:
+          type: string
+          format: objectId
+          description: Id of the flow this entry aggregates.
+          x-celigo-refModel: flows
+          examples:
+            - 69497fc443fc1f9a03d31bd9
+        _integrationId:
+          type: string
+          format: objectId
+          description: |-
+            Id of the flow's parent integration. Omitted for standalone flows that aren't part of an
+            integration.
+          x-celigo-refModel: integrations
+          examples:
+            - 69496f01615f724066afaac2
+        numRuns:
+          type: integer
+          minimum: 0
+          description: Total number of runs that matched the request filter.
+          examples:
+            - 91
+        numPages:
+          type: integer
+          minimum: 0
+          description: |-
+            Total pages processed across those runs (one run can produce multiple pages when the source
+            export paginates).
+          examples:
+            - 92
+        numSuccess:
+          type: integer
+          minimum: 0
+          description: Records that completed successfully across all matched runs.
+          examples:
+            - 184
+        numError:
+          type: integer
+          minimum: 0
+          description: |-
+            Records that failed across all matched runs. Distinct from `numOpenError` — this is the
+            lifetime-of-those-runs error count, not the currently-unresolved count.
+          examples:
+            - 0
+        numIgnore:
+          type: integer
+          minimum: 0
+          description: Records that were ignored (filtered out by `inputFilter` / `outputFilter`) across all matched runs.
+          examples:
+            - 0
+        numOpenError:
+          type: integer
+          minimum: 0
+          description: Currently **open** (unresolved) errors on this flow. Drops when errors are resolved or retried.
+          examples:
+            - 3
+        numResolvedByAuto:
+          type: integer
+          minimum: 0
+          description: Errors that were auto-resolved by a successful retry.
+          examples:
+            - 7
+        numResolvedByUser:
+          type: integer
+          minimum: 0
+          description: Errors that a user manually marked resolved.
+          examples:
+            - 0
+        avgRuntime:
+          type: number
+          description: Mean job runtime in milliseconds across matched runs.
+          examples:
+            - 172327.86
+        lastExecutedAt:
+          type: string
+          format: date-time
+          description: Timestamp of the most recent matching run (any status).
+          examples:
+            - '2026-04-23T02:51:52.551Z'
+        lastErrorAt:
+          type: string
+          format: date-time
+          description: Timestamp of the most recent open error. Omitted when `numOpenError` is 0.
+          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
+    FlowRunsStatsResponse:
+      type: object
+      description: |-
+        One page of per-flow run-statistics aggregates. Despite the endpoint's location under `flows/runs/`,
+        each element of `stats[]` is **not** an individual job record — it's the aggregated summary for one
+        flow across all matching runs (counts, timings, and the most recent timestamps). The dashboard uses
+        this to render its per-flow "last run / success rate / open errors" cards in a single call.
+
+        To list individual job records (one per run), use `GET /v1/jobs?_flowId=...` instead.
+      properties:
+        stats:
+          type: array
+          description: |-
+            Per-flow aggregate entries. One element per flow that has at least one run matching the request
+            filter.
+          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'
+    JobsFamilyBatchRequest:
+      type: array
+      description: Array of job ids to fetch family information for (max 1000 ids per request).
+      items:
+        type: string
+        format: objectId
+        x-celigo-refModel: jobs
+        examples:
+          - 69e981ee18808f3e5ed1b2fd
+    JobFilesSignedUrlRequest:
+      type: object
+      description: |
+        Request body for `POST /v1/jobs/{_id}/files/signedURL`.
+        Provide `fileIds` to request signed URLs for specific files.
+      properties:
+        fileIds:
+          type: array
+          description: Optional list of job file ids to download.
+          items:
+            type: string
+            examples:
+              - 694b97c4f4f1f4a1b9d9e001
+    JobFilesSignedUrlResponse:
+      type: object
+      description: Signed URL response for downloading job files.
+      properties:
+        signedURL:
+          type:
+            - string
+            - 'null'
+          description: |-
+            A single signed URL. Requests that pass `fileIds` return the `signedURLs` array instead, even for
+            a single file — check both fields.
+          examples:
+            - https://integrator-templates.s3.us-east-1.amazonaws.com/694b97c4f4f1f4a1b9d9e001.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Credential=AKIAEXAMPLE123%2F20260613%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260613T120000Z&X-Amz-SignedHeaders=host&X-Amz-Signature=4f9b2c1e8a3d7f0b5c6e9a2d4f8b1c3e7a0d5f2b9c4e6a8d1f3b7c0e5a9d2f4b
+        signedURLs:
+          type: array
+          description: |-
+            Signed URLs for the returned files, one per file. Returned as an array even when a single file is
+            requested via `fileIds`.
+          items:
+            type: string
+            examples:
+              - https://integrator-templates.s3.us-east-1.amazonaws.com/694b97c4f4f1f4a1b9d9e001.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Credential=AKIAEXAMPLE123%2F20260613%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260613T120000Z&X-Amz-SignedHeaders=host&X-Amz-Signature=4f9b2c1e8a3d7f0b5c6e9a2d4f8b1c3e7a0d5f2b9c4e6a8d1f3b7c0e5a9d2f4b
+    JobDiagnosticsResponse:
+      allOf:
+        - $ref: '#/components/schemas/JobFilesSignedUrlResponse'
+        - type: object
+          description: Signed URL response for downloading diagnostics for a job.
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+  parameters:
+    Include:
+      name: include
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to project into each returned record.
+        Triggers summary projection: the response contains a minimal identity
+        set (`_id`, `name`, plus resource-specific fields) with the requested
+        fields added on top. Supports dot notation for nested fields.
+        Mutually exclusive with `exclude`.
+      schema:
+        type: string
+      example: _integrationId,disabled,lastModified
+    Exclude:
+      name: exclude
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to strip from the default response.
+        Unlike `include`, does not trigger summary projection — returns the
+        full record with the named fields removed. Protected identity fields
+        (e.g. `name`) cannot be stripped. Mutually exclusive with `include`.
+      schema:
+        type: string
+      example: createdAt,lastModified
+x-enable-proxy: true
+x-internal: false