@celigo/api-specs 0.2.16 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.16",
+  "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,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "aad3947",
+		"iasCommit": "c3e34bb",
 		"generatedAt": "2026-09-13"
 	},
 	"roots": {