@celigo/api-specs 0.2.38 → 0.2.40

package/dist/stack.yml

@@ -21,11 +21,11 @@ security:
 tags:
   - name: Stacks
     description: |-
-      Stacks are execution environments that run custom extension code for integrations. Two types are supported: **server** (self-hosted) and **lambda** (AWS Lambda).
+      Stacks are execution environments that run custom extension code for integrations. Two types are supported: **server** (self-hosted) and **lambda** (AWS Lambda). A stack can be shared with other integrator.io users; the `/v1/sshares` operations manage the shares you own, while the Account API lists the stacks shared with you.
 
-      ## Stack schema
+      ## Stack and stack share schemas
 
-      {% openapi-schemas spec="stack" schemas="Stack" grouped="true" %}
+      {% openapi-schemas spec="stack" schemas="Stack,StackShare" grouped="true" %}
 paths:
   /v1/stacks:
     get:
@@ -576,10 +576,12 @@ paths:
                         - api
                         - ui
                         - system
+                        - cli
                       x-enumDescriptions:
                         api: Change made via the REST API.
                         ui: Change made through the Celigo UI.
                         system: Change made by an automated platform process.
+                        cli: Change made via the Celigo CLI.
                     time:
                       type: string
                       format: date-time
@@ -625,11 +627,14 @@ paths:
                             description: New value (absent on delete).
                     deletedInfo:
                       type: object
-                      description: Metadata about the deleted resource. Present on `delete` events.
+                      description: |-
+                        Name snapshot of a deleted stack. Once the stack is in the recycle
+                        bin, every entry in its history carries it — not only the `delete`
+                        event — so the name can still be shown after the record is gone.
                       properties:
                         name:
                           type: string
-                          description: Name of the resource at the time of deletion.
+                          description: Name of the stack at the time of deletion.
                           examples:
                             - Order Processing Lambda
               examples:
@@ -712,6 +717,460 @@ paths:
                   value: {}
         '401':
           $ref: '#/components/responses/401-unauthorized'
+  /v1/stacks/{_id}/invite:
+    post:
+      x-internal: false
+      summary: Share a stack with a user
+      operationId: inviteUserToStack
+      tags:
+        - Stacks
+      description: |-
+        Invites another integrator.io user to use this stack and emails them the
+        invitation. Creates a pending share record — the stack becomes usable by
+        the recipient only after they accept it (`PUT /v1/sshares/{_id}/accept`).
+        The recipient is looked up by email before the stack is checked, so an
+        unknown address fails even for a stack id that does not exist. Stacks that
+        back an Integration App cannot be shared.
+      x-celigo-ai-guidance:
+        - The response `_id` is the share record — use it with `/v1/sshares/{_id}`, not `/v1/stacks/{_id}`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Stack ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: stacks
+            examples:
+              - 685a05192a483c98dc907762
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StackInviteRequest'
+            examples:
+              default:
+                value:
+                  email: partner@example.com
+      responses:
+        '201':
+          description: Pending share created and the invitation emailed. The `Location` header points at the new share record.
+          headers:
+            Location:
+              description: Relative path of the created share record, `/sshares/{_id}`.
+              schema:
+                type: string
+                examples:
+                  - /sshares/69f538ddb600a20919f8bd94
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StackShare'
+              examples:
+                pending:
+                  value:
+                    _id: 69f538ddb600a20919f8bd94
+                    _stackId: 685a05192a483c98dc907762
+                    sharedWithUser:
+                      _id: 68c821306f5d848c881da205
+                      email: partner@example.com
+        '400':
+          description: The user already holds a share on this stack.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                alreadyShared:
+                  value:
+                    errors:
+                      - code: invalid_invite
+                        message: The user already has access to the account. Please use the edit permissions option to update the permissions for the user.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: No integrator.io user has this email address.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unknownUser:
+                  value:
+                    errors:
+                      - code: invalid_user
+                        message: We were not able to find any user with the provided email address.
+  /v1/sshares:
+    get:
+      x-internal: false
+      summary: List stack shares you own
+      operationId: listStackShares
+      tags:
+        - Stacks
+      description: |-
+        Returns every share record for stacks you own — who each stack is shared
+        with and whether they have accepted. Sorted by `_stackId` ascending. For the
+        stacks other users have shared with *you*, use `GET /v1/shared/sshares`.
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of share records to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - $ref: '#/components/parameters/After'
+        - name: sort_by
+          in: query
+          required: false
+          description: Field to sort by. Values outside the enum are rejected with 400 `invalid_query_param`.
+          schema:
+            type: string
+            enum:
+              - _stackId
+            default: _stackId
+            x-enumDescriptions:
+              _stackId: Group the records by stack
+      responses:
+        '200':
+          description: Array of stack share records.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination link. Includes `<...>; rel="next"` with an
+                `after` cursor when more records exist; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/StackShare'
+              examples:
+                default:
+                  value:
+                    - _id: 69f538ddb600a20919f8bd94
+                      _stackId: 685a05192a483c98dc907762
+                      accepted: true
+                      sharedWithUser:
+                        _id: 68c821306f5d848c881da205
+                        name: Partner User
+                        email: partner@example.com
+                        authTypeSSO: null
+                        lastSignIn: '2026-05-01T23:40:36.839Z'
+                        allowedToResetMFA: false
+                    - _id: 6ab1f8c04db5688fd8cb2a11
+                      _stackId: 685a05192a483c98dc907762
+                      sharedWithUser:
+                        _id: 6a6f0d2c9b1e4f3a8c7d5e21
+                        email: contractor@example.com
+                        authTypeSSO: null
+                        allowedToResetMFA: false
+        '204':
+          description: You have not shared any stacks.
+        '400':
+          description: Invalid pagination or sort parameter.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                badSort:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: The query parameter "sort_by" has invalid value.
+                badCursor:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: Please provide a valid cursor(i.e after or before query param) to encode or decode.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/sshares/{_id}:
+    get:
+      x-internal: false
+      summary: Get a stack share
+      operationId: getStackShareById
+      tags:
+        - Stacks
+      description: |-
+        Returns a single share record for a stack you own. Identifies the recipient
+        by `_sharedWithUserId` only — for their name and email, read the record from
+        `GET /v1/sshares`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Share record ID (not the stack ID).
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: sshares
+            examples:
+              - 69f538ddb600a20919f8bd94
+      responses:
+        '200':
+          description: Stack share record.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StackShare'
+              examples:
+                accepted:
+                  value:
+                    _id: 69f538ddb600a20919f8bd94
+                    _stackId: 685a05192a483c98dc907762
+                    _sharedWithUserId: 68c821306f5d848c881da205
+                    accepted: true
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: No share with this id exists on a stack you own.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: SShare not found.
+    put:
+      x-internal: false
+      summary: Update a stack share
+      operationId: updateStackShare
+      tags:
+        - Stacks
+      description: |-
+        Replaces a share record you own. Resend `_stackId` and `_sharedWithUserId`
+        unchanged — they identify the share and cannot be modified — and set
+        `disabled` to suspend or restore the recipient's use of the stack. The
+        recipient's acceptance is preserved. Toggling `disabled`, or reopening a
+        dismissed invitation with `dismissed: false`, notifies the recipient by email.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Share record ID (not the stack ID).
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: sshares
+            examples:
+              - 69f538ddb600a20919f8bd94
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StackShareRequest'
+            examples:
+              suspend:
+                summary: Suspend the recipient's use of the stack
+                value:
+                  _stackId: 685a05192a483c98dc907762
+                  _sharedWithUserId: 68c821306f5d848c881da205
+                  disabled: true
+      responses:
+        '200':
+          description: Updated share record.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StackShare'
+              examples:
+                updated:
+                  value:
+                    _id: 69f538ddb600a20919f8bd94
+                    _stackId: 685a05192a483c98dc907762
+                    _sharedWithUserId: 68c821306f5d848c881da205
+                    accepted: true
+                    disabled: true
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: No share with this id exists on a stack you own.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: SShare not found.
+        '422':
+          description: An identity field is missing, or `_stackId` does not match the stored share.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missingRecipient:
+                  summary: _sharedWithUserId omitted
+                  value:
+                    errors:
+                      - field: _sharedWithUserId
+                        code: missing_required_field
+                        message: Path `_sharedWithUserId` is required.
+                stackChanged:
+                  summary: _stackId differs from the stored share
+                  value:
+                    errors:
+                      - code: update_not_allowed
+                        message: The value provided for the field _stackId in the update request for SShare doesn't match with the existing record.
+    delete:
+      x-internal: false
+      summary: Revoke a stack share
+      operationId: deleteStackShare
+      tags:
+        - Stacks
+      description: |-
+        Permanently removes the share so the recipient can no longer use the
+        stack. Blocked while any of the recipient's connections, exports, or
+        imports still reference the stack — they must repoint or delete those
+        first. To suspend access without removing the share, use
+        `PUT /v1/sshares/{_id}/disable`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Share record ID (not the stack ID).
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: sshares
+            examples:
+              - 69f538ddb600a20919f8bd94
+      responses:
+        '204':
+          description: Share revoked.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: No share with this id exists on a stack you own.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: SShare not found.
+  /v1/sshares/{_id}/disable:
+    put:
+      x-internal: false
+      summary: Toggle a stack share (disable or re-enable)
+      operationId: toggleStackShareDisabled
+      tags:
+        - Stacks
+      description: |-
+        Flips the `disabled` flag on a share you own — call again to re-enable;
+        there is no separate `/enable` path. The recipient is notified by email each
+        time. Only an accepted or dismissed share can be toggled: a still-pending
+        invitation is rejected, and a dismissed one is left unchanged. Equivalent to
+        updating `disabled` through `PUT /v1/sshares/{_id}` without resending the body.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Share record ID (not the stack ID).
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: sshares
+            examples:
+              - 69f538ddb600a20919f8bd94
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              description: Empty body — the target is identified by the path parameter alone.
+            examples:
+              default:
+                summary: Empty body
+                value: {}
+      responses:
+        '204':
+          description: Share toggled.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: No share with this id exists on a stack you own.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: SShare not found.
+  /v1/sshares/{_id}/reinvite:
+    put:
+      x-internal: false
+      summary: Reinvite a user who dismissed a stack share
+      operationId: reinviteStackShare
+      tags:
+        - Stacks
+      description: |-
+        Re-sends a stack share invitation the recipient dismissed and returns the
+        share to the pending state. Only a dismissed, unaccepted share can be
+        reinvited. To share a stack for the first time, use `POST /v1/stacks/{_id}/invite`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Share record ID (not the stack ID).
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: sshares
+            examples:
+              - 69f538ddb600a20919f8bd94
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              description: Empty body — the target is identified by the path parameter alone.
+            examples:
+              default:
+                summary: Empty body
+                value: {}
+      responses:
+        '204':
+          description: Invitation re-sent.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: No share with this id exists on a stack you own.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: SShare not found.
 components:
   securitySchemes:
     bearerAuth:
@@ -743,6 +1202,15 @@ components:
       schema:
         type: string
       example: createdAt,lastModified
+    After:
+      name: after
+      in: query
+      required: false
+      description: |-
+        Opaque cursor for forward pagination. Pass the value from the `Link`
+        response header (`rel="next"`) to fetch the next page.
+      schema:
+        type: string
   schemas:
     Stack:
       type: object
@@ -1137,6 +1605,13 @@ components:
           description: Display name of the dependent resource.
           examples:
             - Import Orders to NetSuite
+        type:
+          type: string
+          description: |-
+            Sub-type of the dependent resource when its collection distinguishes one, such as
+            `stream` for a listener export. Only present for resource types that carry a `type`.
+          examples:
+            - stream
         paths:
           type: array
           description: |-
@@ -1199,6 +1674,168 @@ components:
             dependencyIds:
               export:
                 - 64ff4b21612a134bd2f45534
+    StackInviteRequest:
+      type: object
+      description: Request body for `POST /v1/stacks/{_id}/invite`.
+      required:
+        - email
+      properties:
+        email:
+          type: string
+          format: email
+          description: |-
+            Email address of the integrator.io user to share the stack with, matched
+            case-insensitively. The address must already belong to an integrator.io
+            account — a stack cannot be shared with someone who has not signed up.
+          examples:
+            - partner@example.com
+      x-celigo-ai-guidance:
+        - An address with no integrator.io account fails with 404 `invalid_user`; the recipient must sign up first, then the invite can be sent.
+        - Sharing with a user who already holds a share on this stack fails with 400 `invalid_invite` — edit or re-enable the existing share instead.
+    StackShare:
+      type: object
+      description: |-
+        A share record granting another user access to one of your stacks — the
+        owner's view of a stack share. The `_id` is the share record, not the stack;
+        the recipient sees the same share through `GET /v1/shared/sshares`.
+      x-celigo-ai-guidance:
+        - Booleans are present only when true — a share with no `accepted`, `dismissed`, or `disabled` key is a pending invitation.
+      required:
+        - _id
+        - _stackId
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: sshares
+          description: Identifier of the share record. Use it with the `/v1/sshares/{_id}` operations, not the stack id.
+          examples:
+            - 69f538ddb600a20919f8bd94
+        _stackId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: stacks
+          description: Stack that is shared. Fetch its configuration with `GET /v1/stacks/{_id}`.
+          examples:
+            - 685a05192a483c98dc907762
+        _sharedWithUserId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: users
+          description: |-
+            Identity of the user the stack is shared with. Present on
+            `GET /v1/sshares/{_id}` and the update response; the list and the
+            invite response expand it into `sharedWithUser` instead.
+          examples:
+            - 68c821306f5d848c881da205
+        accepted:
+          type: boolean
+          readOnly: true
+          description: When true, the recipient accepted the invitation and can use the stack. Present only when true.
+          examples:
+            - true
+        dismissed:
+          type: boolean
+          readOnly: true
+          description: When true, the recipient declined the invitation; send it again with `PUT /v1/sshares/{_id}/reinvite`. Present only when true.
+        disabled:
+          type: boolean
+          readOnly: true
+          description: When true, you suspended the recipient's use of the stack via `PUT /v1/sshares/{_id}/disable`. Present only when true.
+        sharedWithUser:
+          type: object
+          readOnly: true
+          description: |-
+            Identity details of the recipient. Present on `GET /v1/sshares` and on the
+            invite response; the single-record operations return `_sharedWithUserId`
+            instead. `name` is included only once the invitation is accepted.
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              description: The recipient's own user id.
+              examples:
+                - 68c821306f5d848c881da205
+            email:
+              type: string
+              format: email
+              description: Email address the invitation was sent to.
+              examples:
+                - partner@example.com
+            name:
+              type: string
+              description: Display name of the recipient. Present only once the invitation is accepted.
+              examples:
+                - Partner User
+            authTypeSSO:
+              type:
+                - object
+                - 'null'
+              description: SSO linkage of the recipient's own sign-in. `null` when the recipient signs in with a password.
+              additionalProperties: true
+            lastSignIn:
+              type: string
+              format: date-time
+              description: Timestamp when the recipient last signed in to integrator.io (any account).
+              examples:
+                - '2026-05-01T23:40:36.839Z'
+            allowedToResetMFA:
+              type: boolean
+              description: When true, the caller may reset the recipient's MFA.
+              examples:
+                - false
+    StackShareRequest:
+      type: object
+      description: |-
+        Request body for `PUT /v1/sshares/{_id}`. The share's identity fields must be
+        resent unchanged; the only state the owner can change here is `disabled` (and
+        `dismissed`, to reopen a declined invitation). Acceptance belongs to the
+        recipient and is preserved.
+      required:
+        - _stackId
+        - _sharedWithUserId
+      properties:
+        _stackId:
+          type: string
+          format: objectId
+          x-celigo-refModel: stacks
+          description: |-
+            Stack the share belongs to. Must match the stored value — a share cannot
+            be moved to another stack.
+          examples:
+            - 685a05192a483c98dc907762
+        _sharedWithUserId:
+          type: string
+          format: objectId
+          x-celigo-refModel: users
+          description: |-
+            User the stack is shared with. Must match the stored value — to share the
+            stack with someone else, send a new invitation with `POST /v1/stacks/{_id}/invite`.
+          examples:
+            - 68c821306f5d848c881da205
+        disabled:
+          type: boolean
+          description: |-
+            When true, suspends the recipient's use of the stack without deleting the
+            share; send false to re-enable. Accepted only once the recipient has
+            accepted or dismissed the invitation. `PUT /v1/sshares/{_id}/disable` toggles
+            the same flag without resending the body.
+          examples:
+            - true
+        dismissed:
+          type: boolean
+          description: |-
+            Send false on a dismissed share to reopen the invitation; the owner cannot
+            set it to true. `PUT /v1/sshares/{_id}/reinvite` does the same and notifies
+            the recipient.
+          examples:
+            - false
+      x-celigo-ai-guidance:
+        - GET the share first and resend `_stackId` and `_sharedWithUserId` unchanged — omitting `_sharedWithUserId` fails with 422 `missing_required_field`, and a different `_stackId` fails with 422 `update_not_allowed`.
   responses:
     401-unauthorized:
       description: |-