@celigo/api-specs 0.2.1

package/dist/recyclebin.yml

@@ -0,0 +1,768 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Recycle Bin
+  description: Manage soft-deleted resources held in the recycle bin.
+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: Recycle Bin
+    description: |-
+      The recycle bin holds soft-deleted resources for 30 days before
+      automatic permanent purge. During this window, resources can be
+      inspected, restored individually or with dependents (cascade
+      restore), or permanently deleted ahead of the 30-day deadline.
+
+      ## Recycle bin schema
+
+      {% openapi-schemas spec="recyclebin" schemas="RecycleBin" grouped="true" %}
+paths:
+  /v1/recycleBinTTL:
+    get:
+      x-internal: false
+      operationId: listRecycleBin
+      tags:
+        - Recycle Bin
+      summary: List deleted resources
+      description: |-
+        Returns all resources deleted within the last 30 days, across all
+        resource types. Files and folders deleted from Celigo Storage are
+        included as `StorageItem` entries. Sorted by `lastModified`
+        descending. Not paginated — the full result set is returned in a
+        single response.
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: |-
+            Maximum number of entries to return per resource type. Applied
+            independently to each type, so the total response size is up to
+            `limit` × the number of resource types with deleted items.
+            Does not apply to `StorageItem` entries — every deleted storage
+            item is always included.
+          schema:
+            type: integer
+            minimum: 1
+          example: 10
+      responses:
+        '200':
+          description: Array of deleted resource entries.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/RecycleBin'
+              examples:
+                default:
+                  value:
+                    - model: StorageItem
+                      doc:
+                        _id: 6a55baeec4855ce84f89995d
+                        type: file
+                        name: old-report.pdf
+                        size: 245760
+                        mimeType: application/pdf
+                        status: active
+                        isSystem: false
+                        createdAt: '2026-07-14T04:28:30.456Z'
+                        lastModified: '2026-07-14T04:30:17.254Z'
+                        deletedAt: '2026-07-14T04:30:17.253Z'
+                        deletedBy: 624cb0346309dc3a543733a2
+                    - model: Connection
+                      doc:
+                        _id: 6a074dce9dc296c4ef80c547
+                        name: Shopify Production
+                        type: http
+                        createdAt: '2026-05-15T16:46:06.754Z'
+                        lastModified: '2026-05-15T16:53:12.492Z'
+                    - model: Flow
+                      doc:
+                        _id: 6a0faff9987bc622fa144d8d
+                        name: Sync orders to NetSuite
+                        disabled: true
+                        createdAt: '2026-05-22T01:23:06.000Z'
+                        lastModified: '2026-05-22T01:25:17.971Z'
+                        lastExecutedAt: '2026-05-22T01:24:43.849Z'
+                    - model: LookupCache
+                      doc:
+                        _id: 6a07e31dc6c9a763e00d6f47
+                        name: SKU cross-reference cache
+                        includeDataInTemplatesAndCloning: false
+                        size: 0
+                        sizeInMB: 0 MB
+                        createdAt: '2026-05-16T03:23:09.399Z'
+                        lastModified: '2026-05-16T03:23:11.578Z'
+                        deletedAt: '2026-05-16T03:23:11.522Z'
+        '204':
+          description: Recycle bin is empty (no body returned).
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/recycleBinTTL/{_resourceType}:
+    get:
+      x-internal: false
+      operationId: listRecycleBinByType
+      tags:
+        - Recycle Bin
+      summary: List deleted resources by type
+      description: |-
+        Returns deleted resources of a specific type from the recycle bin
+        (last 30 days). Sort order is not guaranteed. Not paginated — the
+        full result set is returned in a single response.
+
+        `storageitems` behaves differently: the request is proxied to Celigo
+        Storage, which returns an object wrapping an `items` array (not a
+        bare array), sorted by newest deletion first and paginated via the
+        `Link` response header.
+      parameters:
+        - $ref: '#/components/parameters/ResourceType'
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of resources to return.
+          schema:
+            type: integer
+            minimum: 1
+          example: 10
+      responses:
+        '200':
+          description: Array of deleted resource documents.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  required:
+                    - _id
+                    - name
+                    - lastModified
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Unique identifier for the resource.
+                      examples:
+                        - 6a07738df8b91b72d72903c6
+                    name:
+                      type: string
+                      description: Display name for the resource.
+                      examples:
+                        - Transform order payload
+                    createdAt:
+                      type: string
+                      format: date-time
+                      description: Timestamp when the resource was created.
+                      examples:
+                        - '2026-05-15T19:27:09.037Z'
+                    lastModified:
+                      type: string
+                      format: date-time
+                      description: Timestamp when the resource was last modified.
+                      examples:
+                        - '2026-05-15T19:27:10.146Z'
+                    deletedAt:
+                      type: string
+                      format: date-time
+                      description: Timestamp when the resource was deleted.
+                      examples:
+                        - '2026-05-16T01:42:50.767Z'
+                  additionalProperties: true
+              examples:
+                scripts:
+                  summary: Deleted scripts
+                  value:
+                    - _id: 6a07738df8b91b72d72903c6
+                      name: Transform order payload
+                      sandbox: false
+                      postResponseHookToProcessOnChildRecord: false
+                      createdAt: '2026-05-15T19:27:09.037Z'
+                      lastModified: '2026-05-15T19:27:10.146Z'
+                    - _id: 6a0fc53d5f269e647c8c0df2
+                      name: Parse CSV line items
+                      sandbox: false
+                      postResponseHookToProcessOnChildRecord: false
+                      createdAt: '2026-05-22T02:53:49.356Z'
+                      lastModified: '2026-05-22T03:10:28.669Z'
+                lookupcaches:
+                  summary: Deleted lookup caches
+                  value:
+                    - _id: 6a07cb9a2334574c8c54bcb6
+                      name: SKU cross-reference cache
+                      includeDataInTemplatesAndCloning: false
+                      size: 0
+                      sizeInMB: 0 MB
+                      createdAt: '2026-05-16T01:42:50.081Z'
+                      lastModified: '2026-05-16T01:42:50.806Z'
+                      deletedAt: '2026-05-16T01:42:50.767Z'
+        '204':
+          description: No deleted resources of this type (no body returned).
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The resource type is not supported by the recycle bin.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_arguments
+                    message: Recycle Bin operations are not supported for the given model at this time
+  /v1/recycleBinTTL/{_resourceType}/{_id}:
+    get:
+      x-internal: false
+      operationId: getRecycleBinResource
+      tags:
+        - Recycle Bin
+      summary: Get a deleted resource
+      description: |-
+        Returns the full document of a specific deleted resource from
+        the recycle bin. May include fields that the list endpoints omit
+        (e.g. `content` on scripts, `queues` on connections). Not supported
+        for `storageitems` — deleted storage item documents are available
+        only from the list endpoints.
+      parameters:
+        - $ref: '#/components/parameters/ResourceType'
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+          description: Identifies which deleted resource to retrieve.
+          example: 6a024e629a0943889001f33a
+      responses:
+        '200':
+          description: The deleted resource document.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - _id
+                  - name
+                  - lastModified
+                properties:
+                  _id:
+                    type: string
+                    format: objectId
+                    description: Unique identifier for the resource.
+                    example: 6a024e629a0943889001f33a
+                  name:
+                    type: string
+                    description: Display name for the resource.
+                    examples:
+                      - Parse AI agent final_output JSON
+                  createdAt:
+                    type: string
+                    format: date-time
+                    description: Timestamp when the resource was created.
+                    examples:
+                      - '2026-05-11T21:47:14.145Z'
+                  lastModified:
+                    type: string
+                    format: date-time
+                    description: Timestamp when the resource was last modified.
+                    examples:
+                      - '2026-05-11T22:27:53.062Z'
+                  deletedAt:
+                    type: string
+                    format: date-time
+                    description: Timestamp when the resource was deleted.
+                    examples:
+                      - '2026-05-16T01:42:50.767Z'
+                additionalProperties: true
+              examples:
+                script:
+                  summary: Deleted script
+                  value:
+                    _id: 6a024e629a0943889001f33a
+                    name: Transform order payload
+                    sandbox: false
+                    postResponseHookToProcessOnChildRecord: false
+                    content: |-
+                      function preSavePage({ data }) {
+                        return data;
+                      }
+                    createdAt: '2026-05-11T21:47:14.145Z'
+                    lastModified: '2026-05-11T22:27:53.062Z'
+                connection:
+                  summary: Deleted connection
+                  value:
+                    _id: 6a074dce9dc296c4ef80c547
+                    name: Shopify Production
+                    type: http
+                    http:
+                      formType: http
+                      mediaType: json
+                      baseURI: https://httpbin.org
+                      concurrencyLevel: 25
+                    createdAt: '2026-05-15T16:46:06.754Z'
+                    lastModified: '2026-05-15T16:53:12.492Z'
+                lookupcache:
+                  summary: Deleted lookup cache
+                  value:
+                    _id: 6a07cb9a2334574c8c54bcb6
+                    name: SKU cross-reference cache
+                    includeDataInTemplatesAndCloning: false
+                    size: 0
+                    sizeInMB: 0 MB
+                    createdAt: '2026-05-16T01:42:50.081Z'
+                    lastModified: '2026-05-16T01:42:50.806Z'
+                    deletedAt: '2026-05-16T01:42:50.767Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The resource type is not supported by the recycle bin.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_arguments
+                    message: Recycle Bin operations are not supported for the given model at this time
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '501':
+          description: |-
+            Returned when `_resourceType` is `storageitems`, regardless of
+            `_id` — storage items cannot be fetched individually from the
+            recycle bin.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: storage_recyclebin_op_unsupported
+                    message: Recycle-bin operation "getOne" is not supported for storage items.
+    post:
+      x-internal: false
+      operationId: restoreRecycleBinResource
+      tags:
+        - Recycle Bin
+      summary: Restore a deleted resource
+      description: |-
+        Restores a single resource from the recycle bin back to the
+        account's active resources. Any request body is ignored.
+
+        Standalone restore is blocked if a child resource is still in the
+        recycle bin. To restore a resource along with all of its dependents
+        (child flows, exports, imports, etc.), use the cascade-restore
+        endpoint instead.
+      parameters:
+        - $ref: '#/components/parameters/ResourceType'
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+          description: Identifies which deleted resource to restore.
+          example: 6a024e629a0943889001f33a
+      responses:
+        '204':
+          description: Resource restored successfully (no body returned).
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            The resource type is not supported by the recycle bin. Also
+            returned for `storageitems` — storage items cannot be restored
+            through this endpoint.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_arguments
+                    message: Recycle Bin operations are not supported for the given model at this time
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            Resource has dependents still in the recycle bin. Restore the
+            dependents first, or use cascade restore.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: descendants_not_restored
+                    message: flow 60a2c4e6f321d800129a1a3c must be restored before you can restore integration 5f8b3c2e1a2b3c4d5e6f7a8b
+    delete:
+      x-internal: false
+      operationId: deleteRecycleBinResource
+      tags:
+        - Recycle Bin
+      summary: Permanently delete a resource
+      description: |-
+        Permanently purges a resource from the recycle bin. This action
+        cannot be undone — the resource data is irrecoverably removed.
+        Resources are auto-purged after 30 days.
+      parameters:
+        - $ref: '#/components/parameters/ResourceType'
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+          description: Identifies which deleted resource to purge.
+          example: 6a024e629a0943889001f33a
+      responses:
+        '204':
+          description: Resource permanently deleted (no body returned).
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            The resource type is not supported by the recycle bin. Also
+            returned for `storageitems` — storage items cannot be purged
+            through this endpoint.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_arguments
+                    message: Recycle Bin operations are not supported for the given model at this time
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/recycleBinTTL/{resourceType}/{_id}/doCascadeRestore:
+    post:
+      x-internal: false
+      operationId: cascadeRestoreRecycleBinResource
+      tags:
+        - Recycle Bin
+      summary: Cascade-restore a deleted resource
+      description: |-
+        Restores a resource from the recycle bin along with all of its
+        dependent resources (child flows, exports, imports, connections,
+        scripts, etc.). Any request body is ignored. Prefer this over
+        standalone restore when restoring integrations or flows.
+
+        This path uses `resourceType` (no leading underscore), unlike
+        the other recycle bin paths which use `_resourceType`.
+      parameters:
+        - $ref: '#/components/parameters/CascadeResourceType'
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+          description: Identifies which deleted resource to cascade-restore.
+          example: 6a074dce9dc296c4ef80c547
+      responses:
+        '204':
+          description: Resource and all dependents restored successfully (no body returned).
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The resource type does not support cascade restore.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_arguments
+                    message: Recycle Bin cascade restore is not supported for the given model at this time.
+        '404':
+          $ref: '#/components/responses/404-not-found'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    RecycleBin:
+      type: object
+      required:
+        - model
+        - doc
+      properties:
+        model:
+          type: string
+          description: Identifies the resource type of the wrapped document.
+          examples:
+            - Script
+          enum:
+            - Connection
+            - Flow
+            - Export
+            - Import
+            - Script
+            - Integration
+            - Stack
+            - FileDefinition
+            - AsyncHelper
+            - LookupCache
+            - Tool
+            - Api
+            - McpServer
+            - EDIProfile
+            - Agent
+            - StorageItem
+          x-enumDescriptions:
+            Connection: An authenticated link to an external application or service.
+            Flow: A data pipeline that moves records between systems.
+            Export: The source step in a flow that reads data from an external system.
+            Import: The destination step in a flow that writes data to an external system.
+            Script: A custom JavaScript hook that transforms data during flow execution.
+            Integration: A workspace that groups related flows and resources.
+            Stack: An execution environment for custom extension code (hooks, wrappers).
+            FileDefinition: A parsing/generation template for structured file formats (EDI, CSV, fixed-width).
+            AsyncHelper: A configuration for polling long-running asynchronous operations to completion.
+            LookupCache: An in-memory key-value store used for fast lookups during flow execution.
+            Tool: A reusable building block encapsulating lookups, imports, or transforms.
+            Api: A custom HTTP endpoint that lets external systems push or query data through Celigo.
+            McpServer: An MCP server endpoint exposing tools and APIs to external AI agents.
+            EDIProfile: A trading partner profile for EDI document exchange (X12/EDIFACT).
+            Agent: An on-premise agent that proxies API traffic to systems behind a firewall.
+            StorageItem: A file or folder stored in Celigo Storage.
+        doc:
+          type: object
+          required:
+            - _id
+            - name
+            - lastModified
+          description: |-
+            The resource document as it existed at deletion time.
+            Fields vary by resource type; common fields are listed below.
+          properties:
+            _id:
+              type: string
+              format: objectId
+              description: Unique identifier for the resource.
+              examples:
+                - 6a07738df8b91b72d72903c6
+            name:
+              type: string
+              description: Display name for the resource.
+              examples:
+                - Transform order payload
+            createdAt:
+              type: string
+              format: date-time
+              description: Timestamp when the resource was created.
+              examples:
+                - '2026-05-15T19:27:09.037Z'
+            lastModified:
+              type: string
+              format: date-time
+              description: Timestamp when the resource was last modified.
+              examples:
+                - '2026-05-15T19:27:10.146Z'
+            deletedAt:
+              type: string
+              format: date-time
+              description: Timestamp when the resource was deleted.
+              examples:
+                - '2026-05-16T01:42:50.767Z'
+          additionalProperties: true
+    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
+  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
+    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.
+  parameters:
+    ResourceType:
+      name: _resourceType
+      in: path
+      required: true
+      description: Resource type to operate on.
+      schema:
+        type: string
+        enum:
+          - connections
+          - flows
+          - exports
+          - imports
+          - scripts
+          - integrations
+          - stacks
+          - filedefinitions
+          - asynchelpers
+          - lookupcaches
+          - tools
+          - apis
+          - mcpservers
+          - ediprofiles
+          - agents
+          - storageitems
+        x-enumDescriptions:
+          connections: Authenticated links to external applications.
+          flows: Data pipelines that move records between systems.
+          exports: Source steps that read data from external systems.
+          imports: Destination steps that write data to external systems.
+          scripts: Custom JavaScript hooks for data transformation.
+          integrations: Workspaces grouping related flows and resources.
+          stacks: Execution environments for custom extension code.
+          filedefinitions: Parsing/generation templates for structured files.
+          asynchelpers: Configurations for polling long-running async operations.
+          lookupcaches: In-memory key-value stores for flow lookups.
+          tools: Reusable building blocks for lookups, imports, or transforms.
+          apis: Custom HTTP endpoints for external data push/query.
+          mcpservers: MCP server endpoints for external AI agents.
+          ediprofiles: Trading partner profiles for EDI document exchange.
+          agents: On-premise agents proxying traffic behind firewalls.
+          storageitems: Files and folders deleted from Celigo Storage (list-only).
+    CascadeResourceType:
+      name: resourceType
+      in: path
+      required: true
+      description: Resource type to cascade-restore. Uses `resourceType` (no leading underscore), unlike the other recycle bin paths.
+      schema:
+        type: string
+        enum:
+          - connections
+          - flows
+          - exports
+          - imports
+          - scripts
+          - integrations
+          - stacks
+          - filedefinitions
+          - asynchelpers
+          - lookupcaches
+          - tools
+          - apis
+          - mcpservers
+          - ediprofiles
+          - agents
+        x-enumDescriptions:
+          connections: Connection and its dependents.
+          flows: Flow, its exports, imports, scripts, and connections.
+          exports: Export and its dependents.
+          imports: Import and its dependents.
+          scripts: Script and its dependents.
+          integrations: Integration workspace and all child resources.
+          stacks: Stack and its dependents.
+          filedefinitions: File definition and its dependents.
+          asynchelpers: Async helper and its dependents.
+          lookupcaches: Lookup cache and its dependents.
+          tools: Tool and its dependents.
+          apis: Custom API endpoint and its dependents.
+          mcpservers: MCP server and its dependents.
+          ediprofiles: EDI profile and its dependents.
+          agents: On-premise agent and its dependents.
+x-enable-proxy: true
+x-internal: false