@celigo/api-specs 0.2.15 → 0.2.17

package/dist/connection.yml

@@ -1003,6 +1003,202 @@ paths:
           - Test network connectivity
           - Verify permissions for basic operations
           - Return connection status and any error details
+  /v1/connections/{_id}/proxy:
+    post:
+      x-internal: false
+      summary: Send a request through a connection (proxy)
+      description: |-
+        Sends one HTTP request to the system behind a saved connection, using that connection's
+        base URI and stored authentication, and returns the target's response as-is. Use it to call
+        an endpoint the connection's exports and imports do not expose — a metadata or describe call,
+        an ad-hoc read, a one-off write — without copying credentials out of integrator.io.
+
+        The proxy call is always `POST`; the request to the target is shaped by headers:
+
+        - `Integrator-Method` (required) is the HTTP method used against the target. One of `HEAD`,
+          `GET`, `PUT`, `PATCH`, `POST`, `DELETE`; any other value is rejected with
+          `405 method_not_allowed`, and omitting the header returns `400 missing_header`.
+        - `Integrator-Relative-URI` (optional) is appended to the connection's base URI, query string
+          included. Omitted, the request goes to the base URI itself.
+        - The proxy request body is forwarded to the target as its body. Send an empty JSON object
+          when the target expects no body.
+
+        Only these headers are read. Any other header on the proxy request — a custom
+        `X-Correlation-Id`, an `Authorization` meant for the target — is dropped, not forwarded; the
+        target receives the connection's authentication plus the standard request headers
+        (`Accept`, `Content-Type`, `Content-Length`).
+
+        The response is the target's response: its status code, body, and headers come back
+        unchanged, so a `404` or `422` here is the target's answer, not the proxy's. Non-JSON bodies
+        (XML, text) pass through with their own `Content-Type`. Only two statuses are the proxy's
+        own: `400 missing_header` and `404 invalid_ref` when `_id` is not a connection in the account.
+
+        NetSuite connections route to a RESTlet instead of a relative URI: send
+        `Integrator-NetSuite-ScriptId` and `Integrator-NetSuite-DeployId` with the script and
+        deployment ids of the RESTlet to call. See
+        [Connect to custom NetSuite RESTlets](https://docs.celigo.com/hc/en-us/articles/360059639272-Connect-to-custom-NetSuite-RESTlets)
+        and
+        [Connect to Salesforce REST relative URIs via proxy](https://docs.celigo.com/hc/en-us/articles/19906581226779-Connect-to-Salesforce-REST-relative-URIs-via-proxy)
+        for the flow-step form of the same call (an integrator.io export or import whose relative URI
+        is this path).
+      operationId: proxyConnectionRequest
+      tags:
+        - Connections
+      parameters:
+        - in: path
+          name: _id
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+          description: Connection whose base URI and authentication the request is sent with.
+        - in: header
+          name: Integrator-Method
+          required: true
+          description: HTTP method to use against the target. Header names are case-insensitive.
+          schema:
+            type: string
+            enum:
+              - HEAD
+              - GET
+              - PUT
+              - PATCH
+              - POST
+              - DELETE
+            x-enumDescriptions:
+              HEAD: Headers only; the body returned to the caller is empty.
+              GET: Read from the target.
+              PUT: Replace a target resource with the forwarded body.
+              PATCH: Partially update a target resource with the forwarded body.
+              POST: Create or invoke on the target with the forwarded body.
+              DELETE: Delete a target resource.
+            examples:
+              - GET
+        - in: header
+          name: Integrator-Relative-URI
+          required: false
+          description: |-
+            Path and query string appended to the connection's base URI, for example
+            `/v1/flows?limit=1`. Omit to send the request to the base URI. Not used by NetSuite
+            connections, which route by RESTlet script and deployment id instead.
+          schema:
+            type: string
+            examples:
+              - /services/data/v58.0/sobjects/account/describe
+        - in: header
+          name: Integrator-NetSuite-ScriptId
+          required: false
+          description: |-
+            NetSuite connections only — the script id of the RESTlet to call
+            (`customscript_…`). Send together with `Integrator-NetSuite-DeployId`.
+          schema:
+            type: string
+            examples:
+              - customscript_celigo_myrestlet
+        - in: header
+          name: Integrator-NetSuite-DeployId
+          required: false
+          description: |-
+            NetSuite connections only — the deployment id of the RESTlet to call
+            (`customdeploy_…`). Send together with `Integrator-NetSuite-ScriptId`.
+          schema:
+            type: string
+            examples:
+              - customdeploy_celigo_myrestlet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              description: |-
+                Forwarded to the target as the request body. Send `{}` when the target method takes
+                no body (`GET`, `HEAD`, `DELETE`).
+              additionalProperties: true
+            examples:
+              read:
+                summary: GET through an HTTP connection — no body
+                value: {}
+              write:
+                summary: POST a record to the target
+                value:
+                  name: Acme Corp
+                  status: active
+      responses:
+        '200':
+          description: |-
+            The target's response, passed through. The status is whatever the target returned —
+            a `2xx` here, or the target's own `4xx`/`5xx` — with its body and headers unchanged.
+          content:
+            application/json:
+              schema:
+                description: The target's response body, as returned by the target.
+              examples:
+                list:
+                  summary: Target returned a JSON array
+                  value:
+                    - _id: 69f4b2cb95ec28be9ca1a88d
+                      name: Shopify orders
+            application/xml:
+              schema:
+                type: string
+                description: Non-JSON target bodies pass through with the target's `Content-Type`.
+        '400':
+          description: '`missing_header` — `Integrator-Method` was not sent.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missingMethod:
+                  value:
+                    errors:
+                      - code: missing_header
+                        message: Integrator-Method header missing in the Request
+                        source: resource
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            `invalid_ref` — `_id` is not a connection in this account. A `404` with any other body
+            is the target's response to the forwarded request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unknownConnection:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Connection not found for the given id.
+        '405':
+          description: '`method_not_allowed` — `Integrator-Method` is not one of the allowed values.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                badMethod:
+                  value:
+                    errors:
+                      - code: method_not_allowed
+                        message: HTTP Method 'FETCH' not allowed. Allowed methods are HEAD, GET, PUT, PATCH, POST, DELETE
+                        source: resource
+        default:
+          description: |-
+            Any other status is the target's response to the forwarded request, returned unchanged
+            with its body and headers.
+      x-celigo-ai-guidance:
+        - |-
+          Custom headers are not forwarded to the target: only Integrator-Method,
+          Integrator-Relative-URI, and the NetSuite RESTlet id headers are read, and the target
+          receives the connection's own authentication. If the target needs a header the connection
+          does not send, the proxy cannot supply it.
+        - |-
+          Read the status as the target's, not the proxy's: a 422 or 404 with a non-invalid_ref
+          body is the downstream system's validation result for the forwarded request.
   /v1/connections/{_id}/debug:
     get:
       x-internal: false

package/dist/export.yml

@@ -10298,8 +10298,11 @@ components:
             batchSize:
               type: number
               description: |-
-                Number of records the RESTlet returns per page. Larger pages reduce round-trips but
-                raise NetSuite governance and memory use per call; tune to the record's size.
+                Number of records the RESTlet returns per request (default 1000). This, not the
+                export's `pageSize`, sizes each NetSuite call; the export keeps requesting until the
+                search is exhausted. Larger batches reduce round-trips but raise NetSuite governance
+                and memory use per call; tune to the record's size. In a test run or preview the
+                request is capped at the export's `pageSize` (default 20) instead.
               examples:
                 - 100
                 - 200
@@ -15886,9 +15889,13 @@ components:
             - integer
             - 'null'
           description: |-
-            Number of records per page streamed to downstream flow steps. Pages are additionally
-            capped at 5 MB regardless of record count, so very large records may produce smaller
-            pages. The server does not validate the value.
+            Number of records per page streamed to downstream flow steps when the export is the
+            flow's source step. Pages are additionally capped at 5 MB regardless of record count, so
+            very large records may produce smaller pages. The server does not validate the value.
+            A lookup (`isLookup: true`) runs to completion and hands every result to the incoming
+            record as one response, capped at 5 MB in total, so the value does not change how many
+            results a lookup returns; a result set larger than that belongs in a standalone export
+            step. In a test run or preview the value also caps the records fetched (default 20).
           default: 20
           examples:
             - 100
@@ -15943,7 +15950,11 @@ components:
           description: |-
             When true, the export runs as a mid-flow lookup: it executes once per incoming record,
             using the input record's fields to parameterize the request, and passes the results to
-            subsequent steps. When false, the export runs as a standalone data source.
+            subsequent steps. When false, the export runs as a standalone data source. A lookup's
+            results are not paged through the flow: every page the adaptor fetches is merged into one
+            response for the record, up to 5 MB, so `pageSize` does not limit or extend what a lookup
+            returns. A lookup that must return more than that is better modeled as a standalone
+            export step.
           examples:
             - true
             - false

package/dist/flow.yml

@@ -6737,6 +6737,7 @@ components:
               description: |
                 Total number of errors produced by the job (including resolved ones).
                 Use `numOpenError` for the count of currently unresolved errors.
+                On a parent flow job this is the sum across every step; on a child job it is that step's count.
               examples:
                 - 10
             numOpenError:
@@ -6762,13 +6763,20 @@ components:
             numSuccess:
               type: integer
               readOnly: true
-              description: Number of successful records/pages.
+              description: |-
+                Number of records processed successfully. On a parent flow job (`type: flow`) this is the
+                sum across every step in the run, so one record that passes through an export and an import
+                counts twice. On a child job (`type: export` or `import`) it is that step's count alone.
+                For per-step counts, read the run with `GET /v1/jobs/{_id}/family` or list its children with
+                `GET /v1/jobs?_flowJobId={_id}&type=import`.
               examples:
                 - 10
             numIgnore:
               type: integer
               readOnly: true
-              description: Number of ignored records/pages.
+              description: |-
+                Number of records skipped, for example by an import's ignore-existing or ignore-missing rule.
+                Summed across steps on a parent flow job; per step on a child job.
               examples:
                 - 0
             numExport:

package/dist/import.yml

@@ -1918,7 +1918,9 @@ components:
           description: |-
             Request body template for the import — an array of Handlebars template strings
             positionally aligned with the `method` array (e.g. `["{{{record}}}"]`). A `null`
-            entry means no template for the method at that position.
+            entry means no template for the method at that position. Each entry is a string:
+            write a JSON body as a template string (`["{\"id\": \"{{record.id}}\"}"]`), not as
+            a JSON object, because an object entry does not render as JSON at runtime.
             Leave undefined for standard imports — the Import's mapping step transforms the source record and the mapped data is sent as the request body automatically.
             Set it only when the target API requires XML, SOAP, or a custom structure that mappings cannot produce, or when the user explicitly specifies a request body.
             When set, the mapping step still runs first and the template renders against the post-mapped record — use `{{record.<mappedField>}}` to reference mapping outputs.

package/dist/job.yml

@@ -333,7 +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).
+        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.
       requestBody:
         required: true
         content:
@@ -387,6 +389,11 @@ paths:
           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``.
+        - |-
+          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.
   /v1/flows/runs/stats:
     post:
       x-internal: false
@@ -1457,6 +1464,7 @@ components:
               description: |
                 Total number of errors produced by the job (including resolved ones).
                 Use `numOpenError` for the count of currently unresolved errors.
+                On a parent flow job this is the sum across every step; on a child job it is that step's count.
               examples:
                 - 10
             numOpenError:
@@ -1482,13 +1490,20 @@ components:
             numSuccess:
               type: integer
               readOnly: true
-              description: Number of successful records/pages.
+              description: |-
+                Number of records processed successfully. On a parent flow job (`type: flow`) this is the
+                sum across every step in the run, so one record that passes through an export and an import
+                counts twice. On a child job (`type: export` or `import`) it is that step's count alone.
+                For per-step counts, read the run with `GET /v1/jobs/{_id}/family` or list its children with
+                `GET /v1/jobs?_flowJobId={_id}&type=import`.
               examples:
                 - 10
             numIgnore:
               type: integer
               readOnly: true
-              description: Number of ignored records/pages.
+              description: |-
+                Number of records skipped, for example by an import's ignore-existing or ignore-missing rule.
+                Summed across steps on a parent flow job; per step on a child job.
               examples:
                 - 0
             numExport:
@@ -1649,13 +1664,20 @@ components:
         time_gt:
           type: integer
           format: int64
-          description: Optional filter for jobs with `createdAt`/time greater than this epoch milliseconds.
+          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.
           examples:
             - 1745366400000
         time_lte:
           type: integer
           format: int64
-          description: Optional filter for jobs with `createdAt`/time less than or equal to this epoch milliseconds.
+          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.
           examples:
             - 1746147600000
       required: []

package/dist/template.yml

@@ -507,6 +507,11 @@ paths:
         Installs a template from a previously uploaded zip file. The `runKey`
         in the request body ties this request to the zip upload (obtained from
         `GET /v1/s3SignedURL`).
+
+        The zip carries connection definitions without credentials, and the
+        installed integration receives new connection `_id`s. Configure each
+        connection in the new integration before running its flows; connection
+        `_id`s that existed only in the zip are not preserved.
       requestBody:
         required: true
         content:

package/dist/tool.yml

@@ -10529,7 +10529,9 @@ components:
           description: |-
             Request body template for the import — an array of Handlebars template strings
             positionally aligned with the `method` array (e.g. `["{{{record}}}"]`). A `null`
-            entry means no template for the method at that position.
+            entry means no template for the method at that position. Each entry is a string:
+            write a JSON body as a template string (`["{\"id\": \"{{record.id}}\"}"]`), not as
+            a JSON object, because an object entry does not render as JSON at runtime.
             Leave undefined for standard imports — the Import's mapping step transforms the source record and the mapped data is sent as the request body automatically.
             Set it only when the target API requires XML, SOAP, or a custom structure that mappings cannot produce, or when the user explicitly specifies a request body.
             When set, the mapping step still runs first and the template renders against the post-mapped record — use `{{record.<mappedField>}}` to reference mapping outputs.
@@ -29898,8 +29900,11 @@ components:
             batchSize:
               type: number
               description: |-
-                Number of records the RESTlet returns per page. Larger pages reduce round-trips but
-                raise NetSuite governance and memory use per call; tune to the record's size.
+                Number of records the RESTlet returns per request (default 1000). This, not the
+                export's `pageSize`, sizes each NetSuite call; the export keeps requesting until the
+                search is exhausted. Larger batches reduce round-trips but raise NetSuite governance
+                and memory use per call; tune to the record's size. In a test run or preview the
+                request is capped at the export's `pageSize` (default 20) instead.
               examples:
                 - 100
                 - 200
@@ -32516,9 +32521,13 @@ components:
             - integer
             - 'null'
           description: |-
-            Number of records per page streamed to downstream flow steps. Pages are additionally
-            capped at 5 MB regardless of record count, so very large records may produce smaller
-            pages. The server does not validate the value.
+            Number of records per page streamed to downstream flow steps when the export is the
+            flow's source step. Pages are additionally capped at 5 MB regardless of record count, so
+            very large records may produce smaller pages. The server does not validate the value.
+            A lookup (`isLookup: true`) runs to completion and hands every result to the incoming
+            record as one response, capped at 5 MB in total, so the value does not change how many
+            results a lookup returns; a result set larger than that belongs in a standalone export
+            step. In a test run or preview the value also caps the records fetched (default 20).
           default: 20
           examples:
             - 100
@@ -32573,7 +32582,11 @@ components:
           description: |-
             When true, the export runs as a mid-flow lookup: it executes once per incoming record,
             using the input record's fields to parameterize the request, and passes the results to
-            subsequent steps. When false, the export runs as a standalone data source.
+            subsequent steps. When false, the export runs as a standalone data source. A lookup's
+            results are not paged through the flow: every page the adaptor fetches is merged into one
+            response for the record, up to 5 MB, so `pageSize` does not limit or extend what a lookup
+            returns. A lookup that must return more than that is better modeled as a standalone
+            export step.
           examples:
             - true
             - false

package/package.json

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

package/schemas.json

@@ -1,8 +1,8 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "89fae90",
-		"generatedAt": "2026-09-12"
+		"iasCommit": "c3e34bb",
+		"generatedAt": "2026-09-13"
 	},
 	"roots": {
 		"aiagent": 121,