@celigo/api-specs 0.2.1

package/dist/lookupcache.yml

@@ -0,0 +1,1325 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Lookup Caches
+  description: API for managing Celigo lookup caches — in-memory key-value stores used during flow execution for fast lookups and deduplication.
+  x-celigo-ai-guidance:
+    - |-
+      API for managing lookup caches in Celigo. Lookup caches are in-memory key-value
+      stores used during integration processing for fast data lookups, deduplication,
+      and cross-reference resolution.
+
+      Each lookup cache:
+      - Belongs to a specific integration
+      - Has a maximum size of 50 MB per cache
+      - Is subject to a per-environment aggregate limit of 1 GB
+      - Can optionally include its data when used in templates and cloning
+
+      Lookup cache data is managed through separate data endpoints (getData, upsert, delete, purge)
+      that proxy to the dedicated Lookup Cache service.
+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: Lookup Caches
+    description: |-
+      Lookup caches are in-memory key-value stores used during flow
+      execution for fast lookups, deduplication, and cross-reference
+      resolution.
+
+      Lookup caches are account-level resources — they are not scoped to
+      a specific integration.
+
+      - Maximum size: 50 MB per cache
+      - Aggregate limit: 1 GB per environment
+      - Data is managed through separate endpoints (`getData`, `upsert`,
+        `delete`, `purge`) that proxy to the Lookup Cache service
+
+      ## Lookup cache schema
+
+      {% openapi-schemas spec="lookupcache" schemas="LookupCache" grouped="true" %}
+paths:
+  /v1/lookupcaches:
+    get:
+      x-internal: false
+      summary: List lookup caches
+      description: Returns lookup caches in the account.
+      operationId: listLookupCaches
+      tags:
+        - Lookup Caches
+      parameters:
+        - name: limit
+          in: query
+          description: Maximum number of caches to return per page. Omit to return all caches.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+        - name: externalId
+          in: query
+          description: Filter to caches matching this exact external identifier.
+          schema:
+            type: string
+            examples:
+              - ext-cache-12345
+      responses:
+        '200':
+          description: One or more lookup caches found.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. Contains a `rel="next"` entry when
+                more pages remain; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/LookupCache'
+              examples:
+                default:
+                  value:
+                    - _id: 69c2eb25365fb658aa39c642
+                      _userId: 624cb0346309dc3a543733a2
+                      name: US State Name to State Code
+                      description: Maps full state names, abbreviations, and common variations to 2-letter state codes
+                      includeDataInTemplatesAndCloning: false
+                      size: 1887
+                      sizeInMB: <5 MB
+                      createdAt: '2026-03-24T19:51:01.266Z'
+                      lastModified: '2026-04-18T05:40:33.812Z'
+                    - _id: 69f4b2d97009ea11ab730306
+                      _userId: 624cb0346309dc3a543733a2
+                      name: ''
+                      includeDataInTemplatesAndCloning: false
+                      size: 0
+                      sizeInMB: 0 MB
+                      createdAt: '2026-05-01T14:04:09.321Z'
+                      lastModified: '2026-05-01T14:04:09.339Z'
+        '204':
+          description: No lookup caches exist in the account.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+      x-celigo-ai-guidance:
+        - |-
+          Returns a list of all lookup caches configured in the account.
+          If no lookup caches exist, a 204 response with no body will be returned.
+    post:
+      x-internal: false
+      summary: Create a lookup cache
+      description: |-
+        Creates a new empty lookup cache. Only `name` is required. Populate
+        it afterwards via `POST /v1/lookupcaches/{_id}/data`.
+      operationId: createLookupCache
+      tags:
+        - Lookup Caches
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              minimal:
+                summary: Minimal — name only
+                value:
+                  name: Customer ID Cache
+              with_options:
+                summary: With description and template inclusion
+                value:
+                  name: Product SKU Lookup
+                  description: Maps external vendor SKUs to internal product IDs
+                  includeDataInTemplatesAndCloning: true
+      responses:
+        '201':
+          description: Lookup cache created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LookupCache'
+              examples:
+                default:
+                  value:
+                    _id: 6a07cb9a2334574c8c54bcb6
+                    _userId: 624cb0346309dc3a543733a2
+                    name: Customer ID Cache
+                    includeDataInTemplatesAndCloning: false
+                    size: 0
+                    sizeInMB: 0 MB
+                    createdAt: '2026-05-15T21:42:35.701Z'
+                    lastModified: '2026-05-15T21:42:35.701Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+      x-celigo-ai-guidance:
+        - |-
+          The cache is created with size 0 and can be populated through
+          the data management endpoints. The per-environment aggregate size
+          limit is validated on creation (1 GB for new caches).
+  /v1/lookupcaches/{_id}:
+    get:
+      x-internal: false
+      summary: Get a lookup cache
+      description: |-
+        Returns configuration, metadata, and current size of a lookup cache.
+        This returns metadata only — to read the cached key-value data,
+        use `POST /v1/lookupcaches/{_id}/getData`.
+      operationId: getLookupCacheById
+      tags:
+        - Lookup Caches
+      parameters:
+        - name: _id
+          in: path
+          description: Lookup cache ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 69c2eb25365fb658aa39c642
+      responses:
+        '200':
+          description: Lookup cache found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LookupCache'
+              examples:
+                default:
+                  value:
+                    _id: 69c2eb25365fb658aa39c642
+                    _userId: 624cb0346309dc3a543733a2
+                    name: US State Name to State Code
+                    description: Maps full state names, abbreviations, and common variations to 2-letter state codes
+                    includeDataInTemplatesAndCloning: false
+                    size: 1887
+                    sizeInMB: <5 MB
+                    createdAt: '2026-03-24T19:51:01.266Z'
+                    lastModified: '2026-04-18T05:40:33.812Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update a lookup cache
+      description: |-
+        Replaces the cache's writable fields. Read-only fields (`_id`,
+        `_userId`, `size`, `sizeInMB`, timestamps) are silently ignored.
+        To write cached data, use `POST /v1/lookupcaches/{_id}/data`.
+      operationId: updateLookupCache
+      tags:
+        - Lookup Caches
+      parameters:
+        - name: _id
+          in: path
+          description: Lookup cache ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 69c2eb25365fb658aa39c642
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              default:
+                summary: Update name and description
+                value:
+                  name: US State Code Lookup (v2)
+                  description: Updated mapping table — now includes territories
+                  includeDataInTemplatesAndCloning: true
+      responses:
+        '200':
+          description: Lookup cache updated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LookupCache'
+              examples:
+                updated:
+                  summary: Cache with updated name and description (read-only fields preserved)
+                  value:
+                    _id: 69c2eb25365fb658aa39c642
+                    _userId: 624cb0346309dc3a543733a2
+                    name: US State Code Lookup (v2)
+                    description: Updated mapping table — now includes territories
+                    includeDataInTemplatesAndCloning: true
+                    size: 1887
+                    sizeInMB: <5 MB
+                    createdAt: '2026-03-24T19:51:01.266Z'
+                    lastModified: '2026-04-21T09:30:12.405Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+      x-celigo-ai-guidance:
+        - |-
+          This updates metadata such as name, description, and template settings.
+          To manage the actual cached data, use the data management endpoints.
+    patch:
+      x-internal: false
+      summary: Patch a lookup cache
+      description: |-
+        Partially updates a lookup cache using a JSON Patch document (RFC 6902).
+        Only `replace` is supported, on these paths:
+
+        | Path | Description |
+        |------|-------------|
+        | `/name` | Cache display name |
+        | `/description` | Cache description |
+
+        All other paths or operations are rejected.
+      operationId: patchLookupCache
+      tags:
+        - Lookup Caches
+      parameters:
+        - name: _id
+          in: path
+          description: Lookup cache ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 69c2eb25365fb658aa39c642
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JsonPatchRequest'
+            examples:
+              rename:
+                summary: Rename a lookup cache
+                value:
+                  - op: replace
+                    path: /name
+                    value: Customer ID Cache (v2)
+      responses:
+        '204':
+          description: Lookup cache patched successfully
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      summary: Delete a lookup cache
+      description: |-
+        Soft-deletes a lookup cache and all its data. Retained for 30 days
+        before permanent removal. To clear data without deleting the cache
+        itself, use `DELETE /v1/lookupcaches/{_id}/data/purge` instead.
+      operationId: deleteLookupCache
+      tags:
+        - Lookup Caches
+      parameters:
+        - name: _id
+          in: path
+          description: Lookup cache ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 69c2eb25365fb658aa39c642
+      responses:
+        '204':
+          description: Lookup cache deleted.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/lookupcaches/{_id}/clone/preview:
+    get:
+      x-internal: false
+      summary: Preview cloning a lookup cache
+      description: |-
+        Returns resources that would be created by cloning this cache.
+        Lookup caches have no transitive dependencies, so the response
+        contains only the cache itself. No resources are created. Whether
+        the clone includes cached data depends on the source cache's
+        `includeDataInTemplatesAndCloning` setting.
+      operationId: previewCloneLookupCache
+      tags:
+        - Lookup Caches
+      parameters:
+        - name: _id
+          in: path
+          description: Lookup cache ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 69c2eb25365fb658aa39c642
+      responses:
+        '200':
+          description: Clone preview retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ClonePreviewResponse'
+              examples:
+                default:
+                  summary: Preview contains only the cache itself (no transitive dependencies)
+                  value:
+                    objects:
+                      - model: LookupCache
+                        doc:
+                          name: US State Name to State Code
+                          description: Maps full state names, abbreviations, and common variations to 2-letter state codes
+                          includeDataInTemplatesAndCloning: false
+                    stackRequired: false
+                    _stackId: null
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/lookupcaches/{_id}/data:
+    post:
+      x-internal: false
+      operationId: upsertLookupCacheData
+      tags:
+        - Lookup Caches
+      summary: Upsert entries into a lookup cache
+      description: |-
+        Writes key-value entries to a lookup cache. Keys that already exist are
+        overwritten; new keys are created. Keys are strings; values may be strings or
+        objects — arrays at the top level are rejected (wrap them in an object). One
+        invalid value fails the entire batch with `400 invalid_value`.
+
+        The service rejects batches larger than ~1000 entries or ~5 MB of JSON.
+        Callers uploading more than that should split their payload; the Celigo CLI
+        auto-batches at 1000 entries / 5 MB and concatenates the per-key results.
+        Each cache is capped at 50 MB and the per-environment aggregate is 1 GB.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Lookup cache id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 69c2eb25365fb658aa39c642
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/LookupCacheDataUpsertRequest'
+            examples:
+              default:
+                summary: Upsert a handful of state-code entries
+                value:
+                  data:
+                    - key: CA
+                      value: California
+                    - key: NY
+                      value: New York
+                    - key: TX
+                      value: Texas
+      responses:
+        '200':
+          description: Entries upserted. Per-key success flags in response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LookupCacheDataUpsertResponse'
+              examples:
+                default:
+                  value:
+                    success: true
+                    data:
+                      - key: CA
+                        success: true
+                      - key: NY
+                        success: true
+                      - key: TX
+                        success: true
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    delete:
+      x-internal: false
+      operationId: deleteLookupCacheDataKeys
+      tags:
+        - Lookup Caches
+      summary: Delete specific keys from a lookup cache
+      description: |-
+        Removes named keys from a lookup cache. Send the keys to delete in the request
+        body. To wipe every entry instead, call `DELETE /v1/lookupcaches/{_id}/data/purge`.
+
+        Send the request with `Content-Type: application/json`. The body must be a
+        JSON object with a `keys` property; a request with no body is rejected as
+        `missing_parameter`. The response reports `success: true` for every
+        submitted key, including keys that did not exist in the cache.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Lookup cache id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 69c2eb25365fb658aa39c642
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/LookupCacheDataDeleteRequest'
+            examples:
+              default:
+                summary: Delete two keys
+                value:
+                  keys:
+                    - CA
+                    - NY
+      responses:
+        '200':
+          description: Delete accepted. Per-key results in response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LookupCacheDataDeleteResponse'
+              examples:
+                default:
+                  value:
+                    success: true
+                    data:
+                      - key: CA
+                        success: true
+                      - key: NY
+                        success: true
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/lookupcaches/{_id}/getData:
+    post:
+      x-internal: false
+      operationId: getLookupCacheData
+      tags:
+        - Lookup Caches
+      summary: Read entries from a lookup cache
+      description: |-
+        Returns entries stored in a lookup cache. Called as `POST` (not `GET`) so the
+        query — explicit keys or a prefix — can travel in the request body.
+
+        Body variants:
+          - omitted or `{}` → first page of all entries (up to ~1000, unordered).
+          - `{keys: [...]}` → one entry per requested key. Hits carry `value`; misses
+            carry `error: {message}` — missing keys are **reported**, not silently
+            omitted. Branch on `error` vs `value` when consuming the response.
+          - `{startsWith: "prefix"}` → every entry whose key begins with `prefix`
+            (case-sensitive).
+
+        `keys` and `startsWith` are treated as mutually exclusive client-side; if both
+        are supplied the server honors `keys` and ignores `startsWith`. Keys are
+        case-sensitive. There is no pagination cursor for unfiltered reads; for
+        caches larger than ~1000 entries, use a prefix scheme with `startsWith`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Lookup cache id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 69c2eb25365fb658aa39c642
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/LookupCacheDataReadRequest'
+            examples:
+              all:
+                summary: First page of every entry (no filter)
+                value: {}
+              by_keys:
+                summary: Fetch specific keys
+                value:
+                  keys:
+                    - CA
+                    - NY
+              by_prefix:
+                summary: Fetch every entry whose key starts with a prefix
+                value:
+                  startsWith: tenant-42/
+      responses:
+        '200':
+          description: Matched entries.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LookupCacheDataReadResponse'
+              examples:
+                hits_and_misses:
+                  summary: Mix of found and missing keys
+                  value:
+                    success: true
+                    data:
+                      - key: CA
+                        value: California
+                      - key: NY
+                        value: New York
+                      - key: ZZ
+                        error:
+                          message: Key not found
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/lookupcaches/{_id}/data/purge:
+    delete:
+      x-internal: false
+      operationId: purgeLookupCacheData
+      tags:
+        - Lookup Caches
+      summary: Purge all data from a lookup cache
+      description: |-
+        Removes every entry from a lookup cache. The cache itself is preserved — only
+        its contents are cleared. Use this instead of deleting-and-recreating when you
+        want to keep the cache's `_id`, name, and any references from flows intact.
+        This operation is irreversible. To delete a subset of keys, use
+        `DELETE /v1/lookupcaches/{_id}/data` with a `keys` body.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Lookup cache id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 69c2eb25365fb658aa39c642
+      responses:
+        '204':
+          description: Cache data was purged. No response body.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/lookupcaches/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listLookupCacheDependencies
+      tags:
+        - Lookup Caches
+      summary: List dependencies of a lookup cache
+      description: |-
+        Returns the set of resources that depend on the specified resource.
+        The response is an object whose keys are dependent-resource types
+        (e.g. `flows`, `imports`) and whose values are arrays of dependency
+        entries. An empty object `{}` means no dependents exist (also
+        returned for a well-formatted but nonexistent id).
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 69c2eb25365fb658aa39c642
+      responses:
+        '200':
+          description: |
+            Dependency map. Keys are resource-type strings; values are arrays
+            of dependency entries. Returns `{}` when no dependents exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DependencyResponse'
+              examples:
+                none:
+                  summary: No dependents (also returned for a nonexistent ID)
+                  value: {}
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    LookupCacheBase:
+      type: object
+      description: Writable fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          maxLength: 200
+          description: Display name.
+          examples:
+            - Customer ID Cache
+            - Product SKU Lookup
+        description:
+          type: string
+          maxLength: 5120
+          description: Purpose or contents of the cache.
+          examples:
+            - Maps external customer IDs to internal Salesforce IDs for deduplication
+        includeDataInTemplatesAndCloning:
+          type: boolean
+          default: false
+          description: |-
+            Whether to include the cached key-value data when this cache is
+            used in templates or cloned. When `false` (default), only
+            metadata transfers. Set to `true` for static reference tables.
+          examples:
+            - false
+            - true
+          x-celigo-ai-guidance:
+            - |-
+              When false (default), only the cache metadata is included — the actual
+              key-value data is not transferred. Set to true if the cached data is
+              part of the integration's configuration (e.g., static reference tables).
+        externalId:
+          type: string
+          description: Caller-supplied identifier for cross-system correlation.
+          examples:
+            - ext-cache-12345
+    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
+    LookupCache:
+      type: object
+      required:
+        - _id
+        - _userId
+        - createdAt
+        - lastModified
+      description: Lookup cache object as returned by the API.
+      allOf:
+        - $ref: '#/components/schemas/LookupCacheBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _userId:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: users
+              description: User who owns this lookup cache.
+              examples:
+                - 624cb0346309dc3a543733a2
+            _templateId:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: templates
+              description: Template this lookup cache was installed from, when it originated from a template.
+              examples:
+                - 6a27a36f9cea1a85192e72cd
+            _sourceId:
+              type: string
+              format: objectId
+              readOnly: true
+              description: Origin resource ID when this cache was created by cloning or installing a template.
+              examples:
+                - 5f8d43a1b9e5a80011a35f2c
+            size:
+              type: integer
+              minimum: 0
+              readOnly: true
+              description: Current size of the cached data in bytes. Maximum 50 MB per cache; 1 GB aggregate per environment.
+              examples:
+                - 0
+                - 1887
+                - 5242880
+            sizeInMB:
+              type: string
+              readOnly: true
+              description: |-
+                Human-readable size rounded up to the nearest 5 MB increment.
+                `"0 MB"` for empty caches, `"<5 MB"` through `"<50 MB"` for
+                non-empty caches, `"50 MB"` at the per-cache cap.
+              examples:
+                - 0 MB
+                - <5 MB
+                - <25 MB
+                - 50 MB
+              x-celigo-ai-guidance:
+                - |-
+                  Human-readable representation of the cache size, rounded up to
+                  the nearest 5 MB increment. Returns "0 MB" for empty caches,
+                  "<N MB" for caches under 50 MB, and "50 MB" for caches at or
+                  over the limit.
+            draft:
+              type: boolean
+              readOnly: true
+              description: When true, this cache was created as a draft by the AI-assisted builder and has not yet been confirmed.
+              examples:
+                - true
+            draftExpiresAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: When the draft cache expires and will be automatically deleted. Only present when `draft` is `true`.
+              examples:
+                - '2026-05-08T17:29:30.726Z'
+    Request:
+      type: object
+      description: Writable fields for creating or updating a lookup cache.
+      allOf:
+        - $ref: '#/components/schemas/LookupCacheBase'
+    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
+    JsonPatchOperation:
+      type: object
+      description: A single JSON Patch operation (RFC 6902).
+      required:
+        - op
+        - path
+      properties:
+        op:
+          type: string
+          enum:
+            - replace
+            - add
+            - remove
+          x-enumDescriptions:
+            replace: Replaces the value at the specified path.
+            add: Sets the value at the specified path.
+            remove: Removes the value at the specified path.
+          description: The operation to perform.
+        path:
+          type: string
+          description: |-
+            JSON Pointer (RFC 6901) to the field to patch. Only
+            whitelisted paths are accepted — unlisted paths return
+            `422` with `"<path> is not a whitelisted property"`.
+        value:
+          description: The new value to set. Required for `replace` and `add`, omit for `remove`.
+    JsonPatchRequest:
+      type: array
+      description: |-
+        A JSON Patch document (RFC 6902). Send an array of patch
+        operations on whitelisted fields — all other paths are rejected
+        with 422.
+      minItems: 1
+      items:
+        $ref: '#/components/schemas/JsonPatchOperation'
+    ClonePreviewResponse:
+      type: object
+      description: |
+        Preview of the resources that would be created by a clone operation.
+        Each object in the `objects` array represents a resource that will be
+        cloned, including the target resource and all transitive dependencies
+        (connections, scripts, exports, imports, etc.).
+      properties:
+        objects:
+          type: array
+          description: |
+            List of resources that would be created by the clone. Always includes
+            the target resource and may include transitive dependencies such as
+            connections, scripts, exports, imports, async helpers, and lookup caches.
+          items:
+            type: object
+            properties:
+              model:
+                type: string
+                description: |
+                  The model type of the resource. Observed values include
+                  AsyncHelper, Connection, Export, Flow, Import, Integration,
+                  LookupCache, Script, and Tool.
+                examples:
+                  - Flow
+              doc:
+                type: object
+                description: The full resource document that would be created by the clone.
+                additionalProperties: true
+        stackRequired:
+          type: boolean
+          description: Whether the clone requires a stack (connector-level) environment to proceed.
+        _stackId:
+          type:
+            - string
+            - 'null'
+          description: The stack id associated with the resource, or null if no stack is involved.
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+    LookupCacheDataEntry:
+      type: object
+      description: |-
+        A single key-value pair stored in a lookup cache. Keys are strings; values are
+        either strings or objects — the cache preserves whichever JSON shape was
+        upserted. Top-level arrays are **rejected** at upsert with
+        `400 invalid_value "The value provided corresponding to the key: <k> is invalid"`;
+        callers that need to store an array should wrap it in an object
+        (e.g. `{ "items": [...] }`).
+      properties:
+        key:
+          type: string
+          description: |-
+            Lookup key. Treated as an opaque string by the cache — case-sensitive, no
+            normalization. The same cache can hold multiple entries that differ only in
+            case (e.g. `CA` and `ca`).
+          examples:
+            - CA
+            - ext-customer-12345
+        value:
+          description: |-
+            Value associated with the key. May be a string or an object; nested arrays
+            inside an object are fine. Top-level arrays are rejected — wrap them.
+            Consumers should check the runtime type before use.
+          oneOf:
+            - title: String value
+              type: string
+            - title: Object value
+              type: object
+              additionalProperties: true
+          examples:
+            - California
+            - customerId: 0015g00000abc
+            - ts: '2026-04-22T00:00:00Z'
+    LookupCacheDataUpsertRequest:
+      type: object
+      description: |-
+        Request body for upserting key-value entries into a lookup cache. `data` must be
+        a non-empty array. Keys already present are overwritten; new keys are created.
+
+        The service rejects batches larger than ~1000 entries or ~5 MB — callers inserting
+        more than that should split into multiple requests (the Celigo CLI auto-batches
+        at 1000 entries / 5 MB).
+      properties:
+        data:
+          type: array
+          minItems: 1
+          description: Entries to upsert. Must contain at least one item.
+          items:
+            $ref: '#/components/schemas/LookupCacheDataEntry'
+      required:
+        - data
+    LookupCacheKeyResult:
+      type: object
+      description: |-
+        Per-key result returned by the upsert and delete-keys endpoints. The `success`
+        flag reflects whether the individual key operation succeeded; the wrapping
+        response's `success` flag reflects whether the request as a whole was accepted.
+
+        For deletes, `success: true` is returned even for keys that did not exist in the
+        cache — the API does not distinguish between "deleted" and "absent."
+      properties:
+        key:
+          type: string
+          description: The key this result applies to.
+          examples:
+            - CA
+        success:
+          type: boolean
+          description: When true, the operation on this key completed successfully.
+    LookupCacheDataUpsertResponse:
+      type: object
+      description: |-
+        Response from a successful lookup-cache upsert. Contains a per-key success flag
+        for every entry in the request — in the same order as submitted.
+      properties:
+        success:
+          type: boolean
+          description: When true, the server accepted the upsert request. Individual key results are in `data`.
+        data:
+          type: array
+          description: Per-key results, one entry per submitted key.
+          items:
+            $ref: '#/components/schemas/LookupCacheKeyResult'
+    LookupCacheDataDeleteRequest:
+      type: object
+      description: |-
+        Request body for deleting specific keys from a lookup cache. The `keys` array
+        may be empty (the endpoint returns `{success: true, data: []}`), but the field
+        itself must be present — a request body missing `keys` is rejected with
+        `missing_parameter`.
+
+        To remove every entry from a cache instead, call
+        `DELETE /v1/lookupcaches/{_id}/data/purge`.
+      properties:
+        keys:
+          type: array
+          description: Keys to remove from the cache.
+          items:
+            type: string
+          examples:
+            - - CA
+              - NY
+      required:
+        - keys
+    LookupCacheDataDeleteResponse:
+      type: object
+      description: |-
+        Response from a successful delete-keys call. Mirrors the upsert response shape:
+        one per-key result entry per submitted key, in submission order.
+
+        Note: `success: true` is returned for every submitted key regardless of whether
+        it actually existed in the cache — the endpoint does not distinguish between
+        "deleted" and "absent." Callers that need that distinction should read the
+        cache first.
+      properties:
+        success:
+          type: boolean
+          description: When true, the server accepted the delete request. Individual key results are in `data`.
+        data:
+          type: array
+          description: Per-key results, one entry per submitted key.
+          items:
+            $ref: '#/components/schemas/LookupCacheKeyResult'
+    LookupCacheDataReadRequest:
+      type: object
+      description: |-
+        Request body for reading entries from a lookup cache.
+
+        All fields are optional. If omitted, the endpoint returns the first page of the
+        cache (up to ~1000 entries, unordered). `keys` and `startsWith` should be
+        treated as mutually exclusive — if both are supplied the server honors `keys`
+        and ignores `startsWith`. An empty JSON body (`{}`) is equivalent to calling
+        the endpoint with no body.
+      properties:
+        keys:
+          type: array
+          description: |-
+            Explicit keys to fetch. The response returns one `data[]` entry per
+            requested key: hits carry `value`, misses carry `error: {message}` — both
+            surface in the same array. Branch on the presence of `error` vs `value`
+            when consuming the response.
+          items:
+            type: string
+          examples:
+            - - CA
+              - NY
+              - TX
+        startsWith:
+          type: string
+          description: |-
+            Key prefix filter. Returns every entry whose key begins with the supplied
+            string (case-sensitive). Useful for namespaced keys like
+            `tenant-42/customer-…`.
+          examples:
+            - tenant-42/
+    LookupCacheDataMissingEntry:
+      type: object
+      description: |-
+        Per-key read result returned when a requested `keys[]` entry was not present in
+        the cache. Surfaces in `data[]` alongside successful `LookupCacheDataEntry`
+        items — callers should check for an `error` sub-object to distinguish hits from
+        misses.
+      properties:
+        key:
+          type: string
+          description: The key that was not found.
+          examples:
+            - ZZ
+        error:
+          type: object
+          description: Miss diagnostic.
+          properties:
+            message:
+              type: string
+              description: Human-readable explanation of the miss.
+              examples:
+                - Key not found
+    LookupCacheDataReadResponse:
+      type: object
+      description: |-
+        Response from a successful lookup-cache read. Contains the matching entries.
+
+        When no filter is supplied, the response contains the first page of the cache
+        (up to ~1000 entries). The API does not currently expose a pagination cursor for
+        large caches — callers that need to iterate a cache larger than the page limit
+        should use `startsWith` to narrow the result set, or key their data with a known
+        prefix scheme.
+      properties:
+        success:
+          type: boolean
+          description: When true, the read request completed successfully.
+        data:
+          type: array
+          description: |-
+            Per-key results, one entry per key returned by the read. Hits carry `key` + `value`
+            (`LookupCacheDataEntry`); misses on `keys[]`-filtered reads carry `key` + `error`
+            (`LookupCacheDataMissingEntry`). Callers should switch on the presence of `error`
+            vs `value` to distinguish. Order is not guaranteed.
+          items:
+            oneOf:
+              - $ref: '#/components/schemas/LookupCacheDataEntry'
+              - $ref: '#/components/schemas/LookupCacheDataMissingEntry'
+    DependencyEntry:
+      type: object
+      description: A single resource that depends on the queried resource.
+      properties:
+        id:
+          type: string
+          description: Unique identifier of the dependent resource.
+          examples:
+            - 61f92026dd053843b5d72350
+        name:
+          type: string
+          description: Display name of the dependent resource.
+          examples:
+            - Import Orders to NetSuite
+        paths:
+          type: array
+          description: |-
+            Dot-notation paths within the dependent resource that reference
+            the target resource. `[*]` denotes array elements.
+          items:
+            type: string
+          examples:
+            - - hooks.preSavePage._scriptId
+        accessLevel:
+          type: string
+          description: The caller's access level on the dependent resource.
+          examples:
+            - manage
+        dependencyIds:
+          type: object
+          description: |-
+            Map of resource types to arrays of IDs that this dependent
+            resource references on the target. Keys are singular or plural
+            resource type strings; values are arrays of ID strings.
+          additionalProperties:
+            type: array
+            items:
+              type: string
+          example:
+            script:
+              - 64ff4b21612a134bd2f45531
+      required:
+        - id
+        - name
+        - paths
+        - accessLevel
+        - dependencyIds
+    DependencyResponse:
+      type: object
+      description: |
+        Map of dependent-resource types to arrays of dependency entries.
+        Keys are plural resource type strings (e.g. `flows`, `imports`,
+        `connections`). An empty object `{}` means no dependents.
+      additionalProperties:
+        type: array
+        items:
+          $ref: '#/components/schemas/DependencyEntry'
+      example:
+        exports:
+          - id: 64ff4b21612a134bd2f45534
+            name: Bank FTP Export
+            paths:
+              - hooks.preSavePage._scriptId
+            accessLevel: manage
+            dependencyIds:
+              script:
+                - 64ff4b21612a134bd2f45531
+        flows:
+          - id: 64ff4b22612a134bd2f45538
+            name: CAMT-053 to Celigo CAM Format
+            paths:
+              - pageGenerators[*]._exportId
+            accessLevel: manage
+            dependencyIds:
+              export:
+                - 64ff4b21612a134bd2f45534
+  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.
+    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.
+x-enable-proxy: true
+x-internal: false