@celigo/api-specs 0.2.1

package/dist/connector.yml

@@ -0,0 +1,1406 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Connectors
+  description: API for managing Celigo Integration App connectors and their licenses. Partner accounts only.
+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: Connectors
+    description: |-
+      API for managing Integration App connectors and their licenses.
+
+      **These endpoints are only available to Celigo Partners.**
+
+      Connectors are packaged integration applications (e.g. "Shopify –
+      NetSuite Connector") that Partners publish to the Celigo marketplace.
+      Each connector has an install base, license management, and update
+      push capabilities.
+
+      ## Connector schema
+
+      {% openapi-schemas spec="connector" schemas="Connector" grouped="true" %}
+paths:
+  /v1/connectors:
+    get:
+      x-internal: false
+      operationId: listConnectors
+      tags:
+        - Connectors
+      summary: List connectors
+      description: |-
+        Returns all connectors owned by the authenticated Partner account.
+
+        **Partner-only endpoint.**
+      responses:
+        '200':
+          description: Array of connector resources.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Connector'
+              examples:
+                one_connector:
+                  summary: Partner account with one published connector
+                  value:
+                    - _id: 54fa0b38a7044f9252000036
+                      _userId: 54f66374661734964a00011e
+                      name: Shopify - NetSuite
+                      handle: sc4n
+                      description: Sync orders, customers, fulfillments, and inventory between Shopify and NetSuite.
+                      applications:
+                        - netsuite
+                        - 65bb6a09de4fef278556c5fe
+                      published: true
+                      trialEnabled: false
+                      numInstalls: 3672
+                      createdAt: '2015-03-06T20:16:56.000Z'
+                      lastModified: '2026-04-22T07:14:42.124Z'
+        '204':
+          description: No connectors exist.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    post:
+      x-internal: false
+      operationId: createConnector
+      tags:
+        - Connectors
+      summary: Create a connector
+      description: |-
+        Creates a new connector (Integration App).
+
+        **Partner-only endpoint.**
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              minimal:
+                summary: Minimal create (Partner account)
+                value:
+                  name: Shopify - NetSuite
+                  description: Sync orders, customers, fulfillments, and inventory between Shopify and NetSuite.
+                  applications:
+                    - netsuite
+                    - 65bb6a09de4fef278556c5fe
+      responses:
+        '201':
+          description: Connector created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Connector'
+              examples:
+                created:
+                  summary: Newly created connector — unpublished, zero installs
+                  value:
+                    _id: 54fa0b38a7044f9252000036
+                    _userId: 54f66374661734964a00011e
+                    name: Shopify - NetSuite
+                    handle: sc4n
+                    description: Sync orders, customers, fulfillments, and inventory between Shopify and NetSuite.
+                    applications:
+                      - netsuite
+                      - 65bb6a09de4fef278556c5fe
+                    numInstalls: 0
+                    createdAt: '2015-03-06T20:16:56.000Z'
+                    lastModified: '2015-03-06T20:16:56.000Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/connectors/{_id}:
+    get:
+      x-internal: false
+      operationId: getConnectorById
+      tags:
+        - Connectors
+      summary: Get a connector
+      description: |-
+        Returns a single connector by ID.
+
+        **Partner-only endpoint.**
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The connector ID.
+      responses:
+        '200':
+          description: The connector resource.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Connector'
+              examples:
+                published:
+                  summary: Published marketplace connector (Partner-account view)
+                  value:
+                    _id: 54fa0b38a7044f9252000036
+                    _userId: 54f66374661734964a00011e
+                    name: Shopify - NetSuite
+                    handle: sc4n
+                    description: Sync orders, customers, fulfillments, and inventory between Shopify and NetSuite.
+                    applications:
+                      - netsuite
+                      - 65bb6a09de4fef278556c5fe
+                    published: true
+                    trialEnabled: false
+                    numInstalls: 3672
+                    createdAt: '2015-03-06T20:16:56.000Z'
+                    lastModified: '2026-04-22T07:14:42.124Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      operationId: updateConnector
+      tags:
+        - Connectors
+      summary: Update a connector
+      description: |-
+        Full-replaces a connector resource.
+
+        **Partner-only endpoint.**
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The connector ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              update_listing:
+                summary: Update the marketplace listing (Partner account)
+                value:
+                  name: Shopify - NetSuite
+                  description: Sync orders, customers, fulfillments, and inventory between Shopify and NetSuite.
+                  published: true
+                  trialEnabled: false
+                  applications:
+                    - netsuite
+                    - 65bb6a09de4fef278556c5fe
+      responses:
+        '200':
+          description: Updated connector.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Connector'
+              examples:
+                updated:
+                  summary: Updated connector (Partner-account view)
+                  value:
+                    _id: 54fa0b38a7044f9252000036
+                    _userId: 54f66374661734964a00011e
+                    name: Shopify - NetSuite
+                    handle: sc4n
+                    description: Sync orders, customers, fulfillments, and inventory between Shopify and NetSuite.
+                    applications:
+                      - netsuite
+                      - 65bb6a09de4fef278556c5fe
+                    published: true
+                    trialEnabled: false
+                    numInstalls: 3672
+                    createdAt: '2015-03-06T20:16:56.000Z'
+                    lastModified: '2026-04-22T07:14:42.124Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      operationId: deleteConnector
+      tags:
+        - Connectors
+      summary: Delete a connector
+      description: |-
+        Deletes a connector. This does not affect existing installations.
+
+        **Partner-only endpoint.**
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The connector ID.
+      responses:
+        '204':
+          description: Connector deleted.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/connectors/{_id}/installBase:
+    get:
+      x-internal: false
+      operationId: getConnectorInstallBase
+      tags:
+        - Connectors
+      summary: Get the install base for a connector
+      description: |-
+        Returns the list of accounts that have installed this connector.
+
+        **Partner-only endpoint.**
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The connector ID.
+      responses:
+        '200':
+          description: Install base data.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+              examples:
+                one_install:
+                  summary: One account has installed the connector (Partner account)
+                  value:
+                    - _integrationId: 5f7e39a76bb8d813180a9549
+                      user:
+                        _id: 624774a6a7574d3ed9f9a5cc
+                        email: admin@example.com
+                        name: Account Admin
+        '204':
+          description: No installations exist for this connector.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/connectors/{_id}/update:
+    put:
+      x-internal: false
+      operationId: pushConnectorUpdate
+      tags:
+        - Connectors
+      summary: Push update to connector installations
+      description: |-
+        Pushes an update to all (or specified) installations of this connector.
+        Triggers the connector's `updateFunction` on each target integration.
+
+        **Partner-only endpoint.**
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The connector ID.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                _integrationIds:
+                  type: array
+                  items:
+                    type: string
+                  description: |-
+                    Optional list of specific integration IDs to update.
+                    Omit to push to all installations.
+            examples:
+              one_installation:
+                summary: Push the update to a single installation (Partner account)
+                value:
+                  _integrationIds:
+                    - 5f7e39a76bb8d813180a9549
+      responses:
+        '200':
+          description: Update pushed.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/connectors/{_id}/licenses:
+    get:
+      x-internal: false
+      operationId: listConnectorLicenses
+      tags:
+        - Connectors
+      summary: List licenses for a connector
+      description: |-
+        Returns all licenses issued for this connector.
+
+        **Partner-only endpoint.**
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The connector ID.
+      responses:
+        '200':
+          description: Array of license records.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/License'
+              examples:
+                one_license:
+                  summary: One issued license (Partner account)
+                  value:
+                    - _id: 624cb0356309dc3a543733a4
+                      created: '2022-04-05T21:10:13.226Z'
+                      expires: '2027-04-05T00:00:00.000Z'
+                      opts:
+                        connectorEdition: premium
+                        addonLicenses:
+                          - type: store
+                            licenses:
+                              - addOnEdition: premium
+                      user:
+                        _id: 624774a6a7574d3ed9f9a5cc
+                        email: admin@example.com
+                        name: Account Admin
+                      _integrationId: 5f7e39a76bb8d813180a9549
+        '204':
+          description: No licenses exist for this connector.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    post:
+      x-internal: false
+      operationId: createConnectorLicense
+      tags:
+        - Connectors
+      summary: Create a license for a connector
+      description: |-
+        Creates a new license for a connector. Supply the target user's email
+        address in the request body — the backend resolves it to a user
+        account. If the email is not a registered integrator.io user, an
+        `invalid_user` error is returned.
+
+        **Partner-only endpoint.**
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The connector ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/LicenseCreateRequest'
+            examples:
+              issue_license:
+                summary: Issue a premium license to a user (Partner account)
+                value:
+                  email: admin@example.com
+                  expires: '2027-04-05T00:00:00.000Z'
+                  opts:
+                    connectorEdition: premium
+      responses:
+        '201':
+          description: License created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/License'
+              examples:
+                created:
+                  summary: License issued — user has not installed yet (Partner account)
+                  value:
+                    _id: 624cb0356309dc3a543733a4
+                    created: '2022-04-05T21:10:13.226Z'
+                    expires: '2027-04-05T00:00:00.000Z'
+                    opts:
+                      connectorEdition: premium
+                    user:
+                      _id: 624774a6a7574d3ed9f9a5cc
+                      email: admin@example.com
+                      name: Account Admin
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/connectors/{_id}/licenses/{_licenseId}:
+    get:
+      x-internal: false
+      operationId: getConnectorLicenseById
+      tags:
+        - Connectors
+      summary: Get a license
+      description: |-
+        Returns a specific license for a connector.
+
+        **Partner-only endpoint.**
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The connector ID.
+        - name: _licenseId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The license ID.
+      responses:
+        '200':
+          description: The license record.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/License'
+              examples:
+                premium_with_addon:
+                  summary: Premium license with a store add-on (Partner account)
+                  value:
+                    _id: 624cb0356309dc3a543733a4
+                    created: '2022-04-05T21:10:13.226Z'
+                    expires: '2027-04-05T00:00:00.000Z'
+                    opts:
+                      connectorEdition: premium
+                      addonLicenses:
+                        - type: store
+                          licenses:
+                            - addOnEdition: premium
+                    user:
+                      _id: 624774a6a7574d3ed9f9a5cc
+                      email: admin@example.com
+                      name: Account Admin
+                    _integrationId: 5f7e39a76bb8d813180a9549
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      operationId: updateConnectorLicense
+      tags:
+        - Connectors
+      summary: Update a license
+      description: |-
+        Updates an existing license for a connector (e.g. change expiry or
+        edition).
+
+        **Partner-only endpoint.**
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The connector ID.
+        - name: _licenseId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The license ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/License'
+            examples:
+              extend_expiry:
+                summary: Extend expiry and keep the store add-on (Partner account)
+                value:
+                  expires: '2028-04-05T00:00:00.000Z'
+                  opts:
+                    connectorEdition: premium
+                    addonLicenses:
+                      - type: store
+                        licenses:
+                          - addOnEdition: premium
+      responses:
+        '200':
+          description: Updated license.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/License'
+              examples:
+                updated:
+                  summary: License after the expiry extension (Partner account)
+                  value:
+                    _id: 624cb0356309dc3a543733a4
+                    created: '2022-04-05T21:10:13.226Z'
+                    expires: '2028-04-05T00:00:00.000Z'
+                    opts:
+                      connectorEdition: premium
+                      addonLicenses:
+                        - type: store
+                          licenses:
+                            - addOnEdition: premium
+                    user:
+                      _id: 624774a6a7574d3ed9f9a5cc
+                      email: admin@example.com
+                      name: Account Admin
+                    _integrationId: 5f7e39a76bb8d813180a9549
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      operationId: deleteConnectorLicense
+      tags:
+        - Connectors
+      summary: Delete a license
+      description: |-
+        Deletes a license for a connector.
+
+        **Partner-only endpoint.**
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The connector ID.
+        - name: _licenseId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The license ID.
+      responses:
+        '204':
+          description: License deleted.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/connectors/{_id}/install:
+    post:
+      x-internal: false
+      operationId: installConnector
+      tags:
+        - Connectors
+      summary: Install a connector (Integration App)
+      description: |-
+        Triggers the install flow for a connector (Integration App). The
+        connector must be associated with an integration that has the install
+        function configured. Templates are installed via
+        `POST /v1/integrations/template/{_id}` instead.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The connector ID.
+          schema:
+            type: string
+            format: objectId
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              description: Optional install configuration.
+              additionalProperties: true
+            examples:
+              default_install:
+                summary: Default install — no configuration overrides
+                value: {}
+      responses:
+        '200':
+          description: Connector install initiated.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Install response.
+                additionalProperties: true
+              examples:
+                initiated:
+                  summary: Install initiated — integration created from the connector
+                  value:
+                    _integrationId: 5f7e39a76bb8d813180a9549
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: Connector not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidRef:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Resource not found.
+        '422':
+          description: |-
+            Connector is not associated with an integration that supports
+            the install function.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidIntegrationApp:
+                  value:
+                    errors:
+                      - code: invalid_integration_app
+                        message: Connector is not associated with an integration.
+  /v1/connectors/{_id}/preview:
+    get:
+      x-internal: false
+      operationId: previewConnectorInstall
+      tags:
+        - Connectors
+      summary: Preview a connector install
+      description: |-
+        Returns a preview of what installing this connector would produce.
+        The connector must be associated with an integration that has the
+        install function configured.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The connector ID.
+          schema:
+            type: string
+            format: objectId
+      responses:
+        '200':
+          description: Connector install preview.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Preview envelope with resource docs.
+                additionalProperties: true
+              examples:
+                preview:
+                  summary: Resources the install would create
+                  value:
+                    objects:
+                      - model: Integration
+                        doc:
+                          _id: 6405b9d73496e05ff253d587
+                          name: Shopify - NetSuite
+                      - model: Connection
+                        doc:
+                          _id: 61f92026dd053843b5d72350
+                          type: netsuite
+                          name: NetSuite Connection
+                    stackRequired: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: Connector not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidRef:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Resource not found.
+        '422':
+          description: |-
+            Connector is not associated with an integration that supports
+            the install function.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidIntegrationApp:
+                  value:
+                    errors:
+                      - code: invalid_integration_app
+                        message: Connector is not associated with an integration.
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    EditionResourceList:
+      type: object
+      description: Resource ids bundled into a connector edition.
+      properties:
+        _flowIds:
+          type: array
+          description: Flows included in the edition.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: flows
+            examples:
+              - 5f7e39a76bb8d813180a9549
+        _importIds:
+          type: array
+          description: Imports included in the edition.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: imports
+            examples:
+              - 5f7e3a118f3c4e2b9d1c7a02
+        _exportIds:
+          type: array
+          description: Exports included in the edition.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: exports
+            examples:
+              - 5f7e3a4d2c1b0a9e8d7c6b50
+        _connectionIds:
+          type: array
+          description: Connections included in the edition.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 5d2d7c1f8a3b4e6f9c0a1b2c
+        _asyncHelperIds:
+          type: array
+          description: Async helpers included in the edition.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: asynchelpers
+            examples:
+              - 5e9a1b2c3d4f5a6b7c8d9e0f
+        _fileDefinitionIds:
+          type: array
+          description: File definitions included in the edition.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: filedefinitions
+            examples:
+              - 5f0a1b2c3d4e5f6a7b8c9d0e
+    ConnectorBase:
+      type: object
+      description: Writable connector fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          description: Display name for the connector, shown on its marketplace listing.
+          examples:
+            - Shopify - NetSuite
+        description:
+          type: string
+          description: Summary of what the connector does, shown on its marketplace listing.
+          examples:
+            - Sync orders, customers, fulfillments, and inventory between Shopify and NetSuite.
+        imageURL:
+          type: string
+          description: URL of the connector's logo image displayed in the marketplace.
+          examples:
+            - https://integrator.io/images/connectors/shopify-netsuite.png
+        websiteURL:
+          type: string
+          description: URL of the publisher's product or documentation page for the connector.
+          examples:
+            - https://www.celigo.com/integration-apps/shopify-netsuite/
+        contactEmail:
+          type: string
+          format: email
+          description: Contact email for the connector's publisher.
+          examples:
+            - support@example.com
+        published:
+          type: boolean
+          description: When true, the connector is visible in the Celigo marketplace.
+        managed:
+          type: boolean
+          description: When true, the connector is managed by Celigo.
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          description: Master integration the connector packages and installs.
+          examples:
+            - 6405b9d73496e05ff253d587
+        _stackId:
+          type: string
+          format: objectId
+          x-celigo-refModel: stacks
+          description: Stack that hosts the connector's installer and lifecycle functions.
+          examples:
+            - 61f92026dd053843b5d72350
+        installerFunction:
+          type: string
+          description: Function invoked from the connector's stack when the connector is installed.
+          examples:
+            - installConnector
+        updateFunction:
+          type: string
+          description: Function invoked to apply connector updates to existing installations.
+          examples:
+            - updateConnector
+        preUninstallFunction:
+          type: string
+          description: Function invoked before an installation is uninstalled.
+          examples:
+            - preUninstallConnector
+        uninstallerFunction:
+          type: string
+          description: Function invoked when an installation is uninstalled.
+          examples:
+            - uninstallConnector
+        externalInstallerFunction:
+          type: string
+          description: Function invoked for externally triggered installs (for example, `installConnectorFromExternalApp`).
+          examples:
+            - installConnectorFromExternalApp
+        _sharedImportIds:
+          type: array
+          description: Imports shared with installations of this connector.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: imports
+            examples:
+              - 5f7e39a76bb8d813180a9549
+        _sharedExportIds:
+          type: array
+          description: Exports shared with installations of this connector.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: exports
+            examples:
+              - 5f7e3a118f3c4e2b9d1c7a02
+        _iClientIdMap:
+          type: array
+          description: Maps connection types to the iClient credentials connector installations use.
+          items:
+            type: object
+            properties:
+              _iClientIds:
+                type: array
+                description: iClients available for this map entry.
+                items:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: iclients
+                  examples:
+                    - 5d2d7c1f8a3b4e6f9c0a1b2c
+              connection:
+                type: object
+                description: Connection criteria this entry applies to.
+                properties:
+                  type:
+                    type: string
+                    description: Connection type this entry applies to (e.g. `netsuite`, `http`, `rest`, `salesforce`).
+                    examples:
+                      - netsuite
+                  assistant:
+                    type: string
+                    description: Assistant (application-specific flavor) this entry applies to, used with generic connection types like `http` or `rest` to scope the entry to one application.
+                    examples:
+                      - shopify
+        applications:
+          type: array
+          items:
+            type: string
+            examples:
+              - netsuite
+          description: Application slugs (e.g. `netsuite`, `shopify`).
+        trialEnabled:
+          type: boolean
+          description: |-
+            When true, trial licenses are enabled for this connector. Requires
+            `trialPeriod` and `_trialLicenseId` to be set.
+        trialPeriod:
+          type: integer
+          description: Trial period in days. Required when `trialEnabled` is `true`.
+          examples:
+            - 30
+        _trialLicenseId:
+          type: string
+          format: objectId
+          description: |-
+            License template ID for trials. Required when `trialEnabled`
+            is `true`.
+          examples:
+            - 624cb0356309dc3a543733a4
+        oAuthServerFlow:
+          type: object
+          description: OAuth server-flow configuration used by connector installations.
+          properties:
+            _iClientId:
+              type: string
+              format: objectId
+              x-celigo-refModel: iclients
+              description: iClient used for the OAuth server flow.
+              examples:
+                - 5d2d7c1f8a3b4e6f9c0a1b2c
+        framework:
+          type: string
+          enum:
+            - twoDotZero
+          description: Marks a connector built on the Integration App Framework 2.0. Set to `twoDotZero` for 2.0 connectors and omit for classic connectors; when set, `twoDotZero._integrationId` is required and must match `_integrationId`.
+          x-enumDescriptions:
+            twoDotZero: Connector built on the Integration App Framework 2.0, packaged from a master integration.
+          examples:
+            - twoDotZero
+        twoDotZero:
+          type: object
+          description: Integration App Framework 2.0 configuration. The server initializes this object (typically as `{"editions":[]}`) on classic connectors too, so its presence alone does not imply a 2.0 connector; `_integrationId` is required inside it only when `framework` is `twoDotZero`.
+          properties:
+            _integrationId:
+              type: string
+              format: objectId
+              x-celigo-refModel: integrations
+              description: Master integration this 2.0 connector packages. Must match the connector's top-level `_integrationId`.
+              examples:
+                - 66795a5d0d5b5574e02e5e63
+            editions:
+              type: array
+              description: Editions the connector offers, each bundling the resources an installation receives.
+              items:
+                type: object
+                required:
+                  - displayName
+                properties:
+                  displayName:
+                    type: string
+                    description: Edition name shown when choosing an edition during install.
+                    examples:
+                      - Standard
+                  order:
+                    type: integer
+                    description: Sort position of the edition in the install UI.
+                    examples:
+                      - 1
+                  resources:
+                    $ref: '#/components/schemas/EditionResourceList'
+                  childResources:
+                    $ref: '#/components/schemas/EditionResourceList'
+            changeEdition:
+              type: object
+              description: Hook invoked when an installation switches between editions.
+              properties:
+                function:
+                  type: string
+                  description: Stack function called to migrate an installation between editions.
+                  examples:
+                    - changeEdition
+                _scriptId:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: scripts
+                  description: Script backing the change-edition function.
+                  examples:
+                    - 61f92026dd053843b5d72350
+            isParentChild:
+              type: boolean
+              readOnly: true
+              description: When true, the master integration supports parent-child (multi-store) installs. Computed automatically from the integration; not settable.
+      if:
+        properties:
+          framework:
+            const: twoDotZero
+        required:
+          - framework
+      then:
+        required:
+          - twoDotZero
+        properties:
+          twoDotZero:
+            required:
+              - _integrationId
+    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
+    Connector:
+      type: object
+      description: Connector object as returned by the API. Also used as the request body for create and update; `readOnly` fields are server-managed and ignored on writes.
+      required:
+        - _id
+        - _userId
+        - name
+        - handle
+      allOf:
+        - $ref: '#/components/schemas/ConnectorBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _userId:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              readOnly: true
+              description: User who published the connector.
+              examples:
+                - 54f66374661734964a00011e
+            handle:
+              type: string
+              readOnly: true
+              description: Auto-generated short unique slug for the connector.
+              examples:
+                - sc4n
+            numInstalls:
+              type: integer
+              readOnly: true
+              description: Number of active installations of this connector.
+              examples:
+                - 3672
+    Request:
+      type: object
+      description: Fields that can be sent when creating or updating a connector. Partner accounts only.
+      required:
+        - name
+      allOf:
+        - $ref: '#/components/schemas/ConnectorBase'
+    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
+    License:
+      type: object
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: System-generated unique identifier for the license.
+          examples:
+            - 624cb0356309dc3a543733a4
+        expires:
+          type: string
+          format: date-time
+          description: Date and time at which the license expires.
+          examples:
+            - '2027-04-05T00:00:00.000Z'
+        created:
+          type: string
+          format: date-time
+          description: Timestamp when the license was created.
+          examples:
+            - '2022-04-05T21:10:13.226Z'
+        opts:
+          type: object
+          description: License options — connector edition and any add-on licenses granted.
+          properties:
+            connectorEdition:
+              type: string
+              description: License tier (e.g. `standard`, `premium`, `enterprise`).
+              examples:
+                - premium
+            addonLicenses:
+              type: array
+              description: Add-on licenses granted in addition to the base connector edition, grouped by add-on type.
+              items:
+                type: object
+                properties:
+                  type:
+                    type: string
+                    description: Add-on type this group of license grants applies to (e.g. `store`).
+                    examples:
+                      - store
+                  licenses:
+                    type: array
+                    description: Individual add-on license grants of this type.
+                    items:
+                      type: object
+                      properties:
+                        addOnEdition:
+                          type: string
+                          description: Edition tier of the add-on license grant (e.g. `premium`).
+                          examples:
+                            - premium
+        user:
+          type: object
+          description: Integrator.io user the license is issued to, resolved from the email supplied at creation.
+          properties:
+            email:
+              type: string
+              format: email
+              description: Email address of the licensed user.
+              examples:
+                - admin@example.com
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              description: Unique identifier of the licensed user.
+              examples:
+                - 624774a6a7574d3ed9f9a5cc
+            name:
+              type: string
+              description: Display name of the licensed user.
+              examples:
+                - Account Admin
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          description: Integration instance created for the licensed user's installation of this connector. Each connector license maps one user's installation to its own integration.
+          examples:
+            - 5f7e39a76bb8d813180a9549
+    LicenseCreateRequest:
+      type: object
+      properties:
+        email:
+          type: string
+          format: email
+          description: |-
+            Email address of the integrator.io user to license. The backend
+            resolves this to a user account.
+          examples:
+            - admin@example.com
+        expires:
+          type: string
+          format: date-time
+          description: Date and time at which the license expires.
+          examples:
+            - '2027-04-05T00:00:00.000Z'
+        opts:
+          type: object
+          description: License options — connector edition and any add-on licenses to grant.
+          properties:
+            connectorEdition:
+              type: string
+              description: License tier (e.g. `standard`, `premium`, `enterprise`).
+              examples:
+                - premium
+            addonLicenses:
+              type: array
+              description: Add-on licenses to grant in addition to the base connector edition, grouped by add-on type.
+              items:
+                type: object
+                properties:
+                  type:
+                    type: string
+                    description: Add-on type this group of license grants applies to (e.g. `store`).
+                    examples:
+                      - store
+                  licenses:
+                    type: array
+                    description: Individual add-on license grants of this type.
+                    items:
+                      type: object
+                      properties:
+                        addOnEdition:
+                          type: string
+                          description: Edition tier of the add-on license grant (e.g. `premium`).
+                          examples:
+                            - premium
+  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
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    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.
+    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.
+x-enable-proxy: true
+x-internal: false