@celigo/api-specs 0.2.138 → 0.2.140

package/dist/api.yml

@@ -45,7 +45,7 @@ tags:
       - **Builder** — visual configuration with request/response mapping, routing, and transformations
       - **Script** — custom JavaScript handler function for full control
 
-      Each API gets a public URL: `https://api.integrator.io/apis/{version}/{relativeURI}`
+      Each API gets a public URL: `https://api.integrator.io/apis/{version}{relativeURI}`
 
       ## API schema
 
@@ -616,7 +616,9 @@ paths:
         Useful for bootstrapping `bodySchema` in builder-mode APIs from real payload samples.
         Input must be a non-empty JSON object -- arrays and primitives are rejected.
         The generated schema is shallow (one level of `properties`); nested objects become
-        `type: "object"` without further property inference.
+        `type: "object"` without further property inference. Fill in or remove those nodes
+        before saving the result as a `bodySchema`: the API Builder editor can't render an
+        object node that has no properties.
       requestBody:
         required: true
         content:
@@ -1686,6 +1688,10 @@ paths:
 
         Test-run invocations do **not** surface in `GET /v1/apis/{_id}/logs`.
 
+        A test run is not free of outside calls: lookups call their sources live. Imports never
+        send; each returns its saved `mockResponse`, or a placeholder response when none is saved
+        (see `mockResponse` on imports).
+
         Test runs never paginate, whatever `pagination.enabled` says: the captured success
         response carries no `pagination` object, and a `Celigo-Next-Cursor` entry in
         `mockRequest.headers` is not validated — a malformed value does not fail the run.
@@ -1707,19 +1713,24 @@ paths:
             schema:
               type: object
               description: |-
-                Optional test request for the run. When the body is empty or
-                omitted, the run replays the API's saved
-                `builder.request.mockRequest`.
+                Optional test request for the run. The saved
+                `builder.request.mockRequest` is never replayed: when the body is
+                empty, omitted, or has no `mockRequest`, the first step receives
+                an empty record.
               properties:
                 mockRequest:
                   type: object
                   description: |-
-                    The simulated request to run instead of the saved
-                    `builder.request.mockRequest`.
+                    The simulated request for this run. Send the saved
+                    `builder.request.mockRequest` here to test with it.
                   properties:
                     body:
                       type: object
-                      description: Request body for the simulated call.
+                      description: |-
+                        Request body for the simulated call. Only the body reaches
+                        the record the steps see. Must be a JSON object: an array
+                        is refused with 400 "Mock request body should be a plain
+                        object."
                     pathParams:
                       type: object
                       description: Path parameter values for the simulated call.
@@ -1731,10 +1742,10 @@ paths:
                       description: Request headers for the simulated call.
               additionalProperties: true
               x-celigo-ai-guidance:
-                - Send explicit test input under the mockRequest key ({body, pathParams, queryParams, headers}); with no body the run replays the saved builder.request.mockRequest.
+                - Send test input under the mockRequest key ({body, pathParams, queryParams, headers}). A run without mockRequest starts from an empty record; the saved builder.request.mockRequest is not replayed, so send it explicitly to test with it.
             examples:
               default:
-                summary: Run with no overrides
+                summary: Run without test input (the first step gets an empty record)
                 value: {}
               withMockRequest:
                 summary: Run with an explicit test request
@@ -2559,6 +2570,59 @@ components:
         - |-
           In script mode, you provide a custom JavaScript function that receives the request
           object and returns the response. This gives you complete control over the API behavior.
+    items:
+      type: object
+      required:
+        - dataType
+      properties:
+        generate:
+          type: string
+          description: Record field the row writes.
+          examples:
+            - customerId
+        extract:
+          type: string
+          description: JSONPath into the request body that the value is read from.
+          examples:
+            - $.id
+        dataType:
+          type: string
+          enum:
+            - string
+            - number
+            - boolean
+            - object
+            - stringarray
+            - numberarray
+            - booleanarray
+            - objectarray
+          x-enumDescriptions:
+            string: Single string value
+            number: Single numeric value
+            boolean: Single boolean value
+            object: Nested object value
+            stringarray: Array of strings
+            numberarray: Array of numbers
+            booleanarray: Array of booleans
+            objectarray: Array of objects
+          description: Data type the row writes.
+          examples:
+            - string
+        sourceDataType:
+          type: string
+          description: Data type of the extracted value.
+          examples:
+            - string
+        status:
+          type: string
+          description: Row status; `Active` rows run.
+          examples:
+            - Active
+        mappings:
+          type: array
+          description: Child rows of an `object` row, with the same shape as this row.
+          items:
+            $ref: '#/components/schemas/items'
     ApiRequest:
       type: object
       description: Request configuration for a builder-mode API endpoint.
@@ -2581,15 +2645,20 @@ components:
           maxLength: 131072
           pattern: ^\/[a-zA-Z0-9:_*\/\-\.]*$
           description: |-
-            URI path relative to the version. Full endpoint becomes
-            `/{version}{relativeURI}`. Use colon notation for path params: `/customers/:id`.
+            URI path relative to the version. Callers reach the API at
+            `https://api.integrator.io/apis/{version}{relativeURI}` (on the account's regional
+            host outside the US), with the account's API token. Use colon notation for path
+            params: `/customers/:id`.
           examples:
             - /customers/:id
             - /orders
             - /products/:productId/variants/:variantId
           x-celigo-ai-guidance:
             - |-
-              Full endpoint URL will be: `/{version}{relativeURI}`
+              The public endpoint is `https://api.integrator.io/apis/{version}{relativeURI}`, for
+              example `/apis/v1/customers/:id`; `relativeURI` already starts with `/`, so add no
+              slash after the version. Without the `/apis` prefix the request goes to the
+              platform's own API and answers `resource_not_found`.
               Can include path parameters using colon notation: `/customers/:id`
               First path segment must be alphanumeric, dash, or underscore only.
         method:
@@ -2722,7 +2791,10 @@ components:
               the empty map never survives the round-trip.
         mockRequest:
           type: object
-          description: Mock request data for testing the API without live calls.
+          description: |-
+            Sample request saved with the API for testing. `POST /v1/apis/{_id}/test/run` doesn't
+            read it; send it as that call's `mockRequest`. A test run still makes outside calls:
+            its lookups call their sources live.
           properties:
             body:
               type: object
@@ -2739,12 +2811,104 @@ components:
           additionalProperties: false
           x-celigo-ai-guidance:
             - |-
-              Provides sample data to test the API without making actual calls.
-              Can include body, headers, pathParams, and queryParams.
+              Saving a mockRequest doesn't make test runs use it: a test run without its own
+              mockRequest starts from an empty record. A test run isn't free of outside calls
+              either: lookups run live, and only imports are kept from sending (each returns its
+              mockResponse or a placeholder). Can include body, headers, pathParams, and
+              queryParams.
         transform:
           type: object
-          description: Optional transformation applied to the incoming request before processing.
+          description: |-
+            Optional transformation applied to the incoming request before processing. The
+            expression form (`type: "expression"` with Transformation 2.0 rules in `expression`)
+            saves and runs. In a test run its rules see only the request body, not `pathParams`,
+            `queryParams` or headers.
           properties:
+            type:
+              type: string
+              description: Selects the transform form; `expression` runs the rules in `expression`.
+              examples:
+                - expression
+            expression:
+              type: object
+              description: Transformation 2.0 rules applied to the request body.
+              properties:
+                version:
+                  type: string
+                  description: Rule format; `"2"` selects the rules in `rulesTwoDotZero`.
+                  examples:
+                    - '2'
+                rulesTwoDotZero:
+                  type: object
+                  description: The rules applied to the request body.
+                  properties:
+                    mode:
+                      type: string
+                      enum:
+                        - create
+                        - modify
+                      x-enumDescriptions:
+                        create: Builds a new record from the mappings, dropping unmapped fields.
+                        modify: Edits the incoming record, keeping unmapped fields.
+                      description: How the mappings apply to the record; `modify` keeps the body's own fields beside the mapped ones.
+                      examples:
+                        - modify
+                    mappings:
+                      type: array
+                      description: Mapper 2.0 rows that write fields onto the record.
+                      items:
+                        type: object
+                        required:
+                          - dataType
+                        properties:
+                          generate:
+                            type: string
+                            description: Record field the row writes.
+                            examples:
+                              - customerId
+                          extract:
+                            type: string
+                            description: JSONPath into the request body that the value is read from.
+                            examples:
+                              - $.id
+                          dataType:
+                            type: string
+                            enum:
+                              - string
+                              - number
+                              - boolean
+                              - object
+                              - stringarray
+                              - numberarray
+                              - booleanarray
+                              - objectarray
+                            x-enumDescriptions:
+                              string: Single string value
+                              number: Single numeric value
+                              boolean: Single boolean value
+                              object: Nested object value
+                              stringarray: Array of strings
+                              numberarray: Array of numbers
+                              booleanarray: Array of booleans
+                              objectarray: Array of objects
+                            description: Data type the row writes.
+                            examples:
+                              - string
+                          sourceDataType:
+                            type: string
+                            description: Data type of the extracted value.
+                            examples:
+                              - string
+                          status:
+                            type: string
+                            description: Row status; `Active` rows run.
+                            examples:
+                              - Active
+                          mappings:
+                            type: array
+                            description: Child rows of an `object` row, with the same shape as this row.
+                            items:
+                              $ref: '#/components/schemas/items'
             _scriptId:
               type: string
               format: objectId
@@ -2926,6 +3090,13 @@ components:
                     hooks:
                       type: object
                       description: Custom scripts for processing
+                    proceedOnFailure:
+                      type: boolean
+                      description: |-
+                        When true, the next step still runs after this step fails, and the request
+                        can still end in the `success` response (`context.success` stays true).
+                        When false, a failure stops the branch and the API returns its `fail`
+                        response.
           x-celigo-ai-guidance:
             - |-
               Each branch has its own criteria and processing steps. Requests are
@@ -2992,6 +3163,75 @@ components:
           The response router determines which response configuration to use based on
           the processing results. This allows you to return different responses based
           on different conditions or outcomes.
+    items-2:
+      type: object
+      required:
+        - dataType
+      properties:
+        generate:
+          type: string
+          description: |-
+            Name of the response-body field this row writes. A dot doesn't nest:
+            `customer.id` makes one key named `customer.id`. To nest, use an `object` row
+            with child `mappings`.
+          examples:
+            - customerId
+        dataType:
+          type: string
+          enum:
+            - string
+            - number
+            - boolean
+            - object
+            - stringarray
+            - numberarray
+            - booleanarray
+            - objectarray
+          x-lowercase: true
+          x-enumDescriptions:
+            string: Single string value
+            number: Single numeric value
+            boolean: Single boolean value
+            object: Nested object value
+            stringarray: Array of strings
+            numberarray: Array of numbers
+            booleanarray: Array of booleans
+            objectarray: Array of objects
+          description: Data type of the value this mapping writes into the response body.
+          examples:
+            - string
+          x-celigo-ai-guidance:
+            - |-
+              Validator-enforced on every mapping entry: writes fail with
+              `422` ("Path 'dataType' is required."), repeated once per
+              entry that omits it.
+        extract:
+          type: string
+          description: |-
+            Where the value comes from, as a JSONPath into the record (`$.id`). A bare string
+            such as `id` or `record.id` is written as that literal text, not read from the
+            record.
+          examples:
+            - $.id
+        mappings:
+          type: array
+          description: |-
+            Child rows of an `object` row, with the same shape as this row. Each writes one
+            field inside the object this row generates.
+          items:
+            $ref: '#/components/schemas/items-2'
+        hardCodedValue:
+          type: string
+          description: |-
+            Static value written to the target field instead of extracting
+            from input data.
+          x-celigo-ai-guidance:
+            - |-
+              The field name is exactly `hardCodedValue` (capital C). The
+              server does not reject unknown mapping keys: a mapping sent
+              with `hardcodedValue` saves successfully with the value
+              silently dropped — no error, and the target field is then
+              simply absent from the API's responses.
     ApiResponse:
       type: object
       description: |-
@@ -3173,7 +3413,9 @@ components:
           additionalProperties: true
         mappings:
           type: array
-          description: Field mappings to transform processing results into the response body.
+          description: |-
+            Mapper 2.0 rows that build the response body from the record the steps produced,
+            under the same rules as the shared Mapper 2.0 schema an import's `mappings` use.
           items:
             type: object
             required:
@@ -3181,9 +3423,12 @@ components:
             properties:
               generate:
                 type: string
-                description: Target field path in the response
+                description: |-
+                  Name of the response-body field this row writes. A dot doesn't nest:
+                  `customer.id` makes one key named `customer.id`. To nest, use an `object` row
+                  with child `mappings`.
                 examples:
-                  - data.customerId
+                  - customerId
               dataType:
                 type: string
                 enum:
@@ -3195,7 +3440,6 @@ components:
                   - numberarray
                   - booleanarray
                   - objectarray
-                  - arrayarray
                 x-lowercase: true
                 x-enumDescriptions:
                   string: Single string value
@@ -3206,7 +3450,6 @@ components:
                   numberarray: Array of numbers
                   booleanarray: Array of booleans
                   objectarray: Array of objects
-                  arrayarray: Array of arrays
                 description: Data type of the value this mapping writes into the response body.
                 examples:
                   - string
@@ -3217,9 +3460,19 @@ components:
                     entry that omits it.
               extract:
                 type: string
-                description: Source field path from input data
+                description: |-
+                  Where the value comes from, as a JSONPath into the record (`$.id`). A bare string
+                  such as `id` or `record.id` is written as that literal text, not read from the
+                  record.
                 examples:
-                  - record.id
+                  - $.id
+              mappings:
+                type: array
+                description: |-
+                  Child rows of an `object` row, with the same shape as this row. Each writes one
+                  field inside the object this row generates.
+                items:
+                  $ref: '#/components/schemas/items-2'
               hardCodedValue:
                 type: string
                 description: |-
@@ -3435,7 +3688,7 @@ components:
           type: string
           default: v1
           pattern: ^[a-zA-Z0-9\-_\.]+$
-          description: Version segment of the public URL (`/{version}/{relativeURI}`).
+          description: Version segment of the public URL (`/apis/{version}{relativeURI}`).
           examples:
             - v1
             - v2
@@ -3483,16 +3736,17 @@ components:
                 - accountLevel
                 - noLogging
               x-enumDescriptions:
-                basic: Log request metadata (method, URI, status, timing) only.
+                basic: Log request metadata and the trace view's step list, with the least per-record payload.
                 standard: Log request metadata plus headers and summary step information.
                 detailed: Full capture including per-step trace logs, viewable in the run-history trace view.
                 accountLevel: Defer to the account's logging settings.
                 noLogging: Disable request logging entirely — no run-history entries are produced.
               description: |-
-                Which logging level applies to requests handled by this API. Only
-                `detailed` (or a temporary debug window) produces the per-step
-                trace data used by `GET /v1/apis/{_id}/requests/{executionId}`.
-                Payload-capturing modes (`standard`, `detailed`) require payload
+                Which logging level applies to requests handled by this API. Every
+                mode that logs records the step list that
+                `GET /v1/apis/{_id}/requests/{executionId}` returns, `basic` included;
+                the level decides how much per-record payload the log-data query can
+                return. Payload-capturing modes (`standard`, `detailed`) require payload
                 storage to be enabled for the account — without it, changing the
                 mode fails with `422` (code `payload_storage_required`).
             debugUntil:
@@ -3835,7 +4089,7 @@ components:
             `/v1/exports/{_exportId}/invoke`, `/v1/imports/{_importId}/invoke`,
             `/v1/connections/{_connectionId}/import` for virtual imports,
             `/v1/apis/{_apiId}/request` for script-mode APIs, and
-            `/apis/v1/<relativeURI>` for builder-mode APIs.
+            `/apis/{version}{relativeURI}` (such as `/apis/v1/orders`) for builder-mode APIs.
           examples:
             - /v1/exports/6878f4a43bc01652c09cdccc/invoke
         metadata:
@@ -4278,7 +4532,7 @@ components:
           description: |-
             Identifier of this request execution (20-character lowercase hex).
             Pass it to `GET /v1/apis/{_id}/requests/{executionId}` to open the
-            trace view when `logMode` is `detailed` or `debug`.
+            trace view, which every `logMode` records.
           examples:
             - a1b2c3d4e5f678901234
         time:
@@ -4384,7 +4638,10 @@ components:
             Identifies what ran: the API's own id for the request-parsing step, the
             export or import id for a lookup or import step, the response `id`
             (for example `success`) for the response step, or `<toolId>_input` /
-            `<toolId>_output` for the boundaries of a nested Tool step.
+            `<toolId>_output` for the boundaries of a nested Tool step. A response
+            step whose `id` was named by the user can't be read through the
+            log-data query, which rejects that id with 400 `invalid_exp_or_imp_id`
+            at every stage; read the step's outcome from this trace.
           examples:
             - 67ee026136f4d1eeb529ad63
             - success