@celigo/api-specs 0.2.38 → 0.2.40

package/dist/integration.yml

@@ -1595,6 +1595,126 @@ paths:
           $ref: '#/components/responses/401-unauthorized'
         '404':
           $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/lookupcaches:
+    get:
+      x-internal: false
+      operationId: listIntegrationLookupCaches
+      tags:
+        - Integrations
+      summary: List lookup caches registered to an integration
+      description: |-
+        Returns a bare array of full lookup cache objects for every cache in the integration's
+        `_registeredLookupCacheIds`, sorted by `name`. Each element is the same shape as
+        `GET /v1/lookupcaches/{_id}`. Rejects unknown integration ids with a 404.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of lookup caches to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+        - $ref: '#/components/parameters/After'
+      responses:
+        '200':
+          description: Array of lookup cache objects.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination link. Includes `<...>; rel="next"` with an `after` cursor when more
+                caches remain; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/LookupCache'
+              examples:
+                one_cache:
+                  summary: Integration with one registered cache
+                  value:
+                    - _id: 68680d7111d1437fbcbce534
+                      _userId: 624cb0346309dc3a543733a2
+                      name: US State Name to State Code
+                      includeDataInTemplatesAndCloning: false
+                      size: 1887
+                      sizeInMB: <5 MB
+                      createdAt: '2026-03-24T19:51:01.266Z'
+                      lastModified: '2026-04-18T05:40:33.812Z'
+        '204':
+          description: No lookup caches are registered to the integration.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    post:
+      x-internal: false
+      operationId: createLookupCacheOnIntegration
+      tags:
+        - Integrations
+      summary: Create a lookup cache and register it
+      description: |-
+        Creates a lookup cache exactly as `POST /v1/lookupcaches` does and, in the same call, adds it to
+        the integration's `_registeredLookupCacheIds` and an `aliases[]` entry whose `alias` is a slug of
+        the cache name — the same side effect as the `register` operations. Populate the cache afterwards
+        with `POST /v1/lookupcaches/{_id}/data`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request-2'
+            examples:
+              default:
+                value:
+                  name: Customer ID Cache
+      responses:
+        '201':
+          description: Created lookup cache, already registered to the integration.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LookupCache'
+              examples:
+                created:
+                  value:
+                    _id: 6ab1f6f37c4b4e699fe8c72c
+                    _userId: 624cb0346309dc3a543733a2
+                    name: Customer ID Cache
+                    includeDataInTemplatesAndCloning: false
+                    size: 0
+                    sizeInMB: 0 MB
+                    createdAt: '2026-09-22T03:33:07.337Z'
+                    lastModified: '2026-09-22T03:33:07.367Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
   /v1/integrations/{_id}/lookupcaches/{_lookupCacheId}/register:
     put:
       x-internal: false
@@ -1771,6 +1891,329 @@ paths:
           $ref: '#/components/responses/401-unauthorized'
         '404':
           $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/topics:
+    get:
+      x-internal: false
+      operationId: listIntegrationTopics
+      tags:
+        - Integrations
+      summary: List topics registered to an integration
+      description: |-
+        Returns a bare array of full topic objects for every topic in the integration's
+        `_registeredTopicIds`, sorted by `name`. Each element is the same shape as
+        `GET /v1/topics/{_id}`. Rejects unknown integration ids with a 404. The `externalId` filter of
+        `GET /v1/topics` is not applied here.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of topics to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+        - $ref: '#/components/parameters/After'
+      responses:
+        '200':
+          description: Array of topic objects.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination link. Includes `<...>; rel="next"` with an `after` cursor when more
+                topics remain; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Topic'
+              examples:
+                one_topic:
+                  summary: Integration with one registered topic
+                  value:
+                    - _id: 6aab2870265e1cf39fcbee4d
+                      _userId: 624cb0346309dc3a543733a2
+                      name: orders.created
+                      description: One event per order placed. Consumed by the fulfillment and finance flows.
+                      retentionMs: 604800000
+                      createdAt: '2026-09-16T23:38:24.578Z'
+                      lastModified: '2026-09-16T23:38:24.578Z'
+        '204':
+          description: No topics are registered to the integration.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    post:
+      x-internal: false
+      operationId: createTopicOnIntegration
+      tags:
+        - Integrations
+      summary: Create a topic and register it
+      description: |-
+        Creates a topic exactly as `POST /v1/topics` does and, in the same call, adds it to the
+        integration's `_registeredTopicIds`. Use this when the topic is being built for one integration's
+        flows; to share a topic across several integrations, create it with `POST /v1/topics` and
+        register it on each with the `register` operations.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request-3'
+            examples:
+              default:
+                value:
+                  name: orders.created
+                  description: One event per order placed. Consumed by the fulfillment and finance flows.
+                  retentionMs: 604800000
+      responses:
+        '201':
+          description: Created topic, already registered to the integration.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Topic'
+              examples:
+                created:
+                  value:
+                    _id: 6aab2870265e1cf39fcbee4d
+                    _userId: 624cb0346309dc3a543733a2
+                    name: orders.created
+                    description: One event per order placed. Consumed by the fulfillment and finance flows.
+                    retentionMs: 604800000
+                    createdAt: '2026-09-16T23:38:24.578Z'
+                    lastModified: '2026-09-16T23:38:24.578Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: The topic body failed validation — the same codes as `POST /v1/topics`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                retention_too_short:
+                  value:
+                    errors:
+                      - field: retentionMs
+                        code: min
+                        message: Path `retentionMs` (3599999) is less than minimum allowed value (3600000).
+  /v1/integrations/{_id}/topics/{_topicId}/register:
+    put:
+      x-internal: false
+      operationId: registerTopicToIntegration
+      tags:
+        - Integrations
+      summary: Register a topic to an integration (by path)
+      description: |-
+        Adds a single topic to the integration's `_registeredTopicIds` so flows in the integration can
+        subscribe to or publish on it. No request body is needed; registering an already-registered topic
+        succeeds without duplicating it. To unregister, use `DELETE` on the same path; to register several
+        topics at once, use `PUT /v1/integrations/{_id}/topics/register`.
+
+        Registration also happens automatically when a flow in the integration is saved with a step
+        bound to the topic. Unlike lookup caches, registering a topic adds no `aliases[]` entry.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: _topicId
+          in: path
+          required: true
+          description: Topic id to register.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+      responses:
+        '204':
+          description: Topic registered successfully. No body returned.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: The integration does not exist, or the topic does not exist in this account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                topic_not_found:
+                  value:
+                    errors:
+                      - code: not_found
+                        message: 'The topics with following _id''s: 6aab2870265e1cf39fcbee4d don''t exist.'
+    delete:
+      x-internal: false
+      operationId: unregisterTopicFromIntegration
+      tags:
+        - Integrations
+      summary: Unregister a topic from an integration
+      description: |-
+        Removes a topic's registration from the integration. This does not delete the topic — it only
+        removes it from the integration's `_registeredTopicIds`. Fails when the topic is not registered
+        on the integration, or while any flow step in the integration (an export or import with
+        `topic._topicId` set) still uses it. Repoint or delete those steps first, then retry.
+      x-celigo-ai-guidance:
+        - |-
+          Before calling, check `GET /v1/topics/{_topicId}/dependencies` for `flows` in this integration
+          — while any exist the platform returns 400 `not_allowed` "The topic is being actively used by a
+          step in this integration…".
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: _topicId
+          in: path
+          required: true
+          description: Topic id to unregister.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+      responses:
+        '204':
+          description: Topic unregistered successfully. No body returned.
+        '400':
+          description: |-
+            The topic is not registered on this integration ("The topic which you are trying to
+            deregister is not registered on the integration."), or a flow step in the integration still
+            uses it ("The topic is being actively used by a step in this integration…"). Error code:
+            `not_allowed` for both.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                in_use:
+                  value:
+                    errors:
+                      - code: not_allowed
+                        message: The topic is being actively used by a step in this integration. Please remove the topic reference from all steps before deregistering.
+                not_registered:
+                  value:
+                    errors:
+                      - code: not_allowed
+                        message: The topic which you are trying to deregister is not registered on the integration.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/topics/register:
+    put:
+      x-internal: false
+      operationId: registerTopicsToIntegration
+      tags:
+        - Integrations
+      summary: Register topics to an integration (by body)
+      description: |-
+        Adds one or more topics to the integration's `_registeredTopicIds`. The request body is a bare
+        JSON array of topic ids; duplicates and already-registered ids are collapsed, and an empty array
+        is accepted as a no-op. Every id must name a topic in this account or nothing is registered.
+        Alternatively, use `PUT /v1/integrations/{_id}/topics/{_topicId}/register` to register a single
+        topic by path parameter.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              description: Topic ids to register.
+              items:
+                type: string
+                format: objectId
+                x-celigo-refModel: topics
+            examples:
+              default:
+                value:
+                  - 6aab2870265e1cf39fcbee4d
+                  - 6aab2870bb44c84f7b77e9f7
+      responses:
+        '204':
+          description: Topics registered successfully. No body returned.
+        '400':
+          description: |-
+            The body is not a JSON array ("Maximum batch size is …", code `batch_size_exceeded`), or an
+            entry is not a valid ObjectId ("Please provide a valid _topicId.", code `invalid_ref`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                bad_id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _topicId.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: The integration does not exist, or one of the topics does not exist in this account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                topic_not_found:
+                  value:
+                    errors:
+                      - code: not_found
+                        message: 'The topics with following _id''s: 6aab2870bb44c84f7b77e9f7 don''t exist.'
   /v1/integrations/{_id}/tree/metadata:
     get:
       x-internal: false
@@ -2205,6 +2648,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:
     Settings:
       type: object
@@ -3795,6 +4247,22 @@ components:
                 type: string
                 format: objectId
                 x-celigo-refModel: lookupcaches
+            _registeredTopicIds:
+              type: array
+              readOnly: true
+              description: |-
+                Topics registered to this integration, so its flows can subscribe to or publish on them.
+                Maintained by the platform: added through the integration's topic `register` operations,
+                `POST /v1/topics` with `__integrationIds`, or automatically when a flow in the integration
+                is saved with a step bound to a topic; removed by the `DELETE …/register` operation or when
+                the topic is deleted. Client-sent values are ignored (PUT-verified). Absent on integrations
+                that have never had a topic registered.
+              items:
+                type: string
+                format: objectId
+                x-celigo-refModel: topics
+              examples:
+                - - 6aab2870265e1cf39fcbee4d
     Request:
       type: object
       description: Fields that can be sent when creating or updating an integration.
@@ -4254,6 +4722,345 @@ components:
               - 67b123456789abcdef012345
             description: Environment id the integration belongs to.
         additionalProperties: true
+    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
+    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-2:
+      type: object
+      description: Writable fields for creating or updating a lookup cache.
+      allOf:
+        - $ref: '#/components/schemas/LookupCacheBase'
+    Topic:
+      type: object
+      description: Topic as returned by the API.
+      required:
+        - _id
+        - _userId
+        - name
+        - retentionMs
+        - createdAt
+        - lastModified
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: topics
+          description: |-
+            Unique identifier for the topic. Topic exports and imports bind to it through
+            `topic._topicId`, and it is the `_topicId` used by every `/v1/topics/{_id}/…` endpoint.
+          examples:
+            - 6ab1f44d7c4b4e699fe84b0a
+        _userId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: users
+          description: Account owner whose license and topic quota the topic counts against.
+          examples:
+            - 624cb0346309dc3a543733a2
+        name:
+          type: string
+          maxLength: 200
+          description: |-
+            Display name shown in the UI. Empty when the topic was created without one; not unique, so
+            use `_id` to identify a topic.
+          examples:
+            - orders.created
+        description:
+          type:
+            - string
+            - 'null'
+          maxLength: 5120
+          description: What the topic carries and which flows consume it. Absent or null when never set.
+          examples:
+            - One event per order placed. Consumed by the fulfillment and finance flows.
+        retentionMs:
+          type: integer
+          minimum: 3600000
+          maximum: 7776000000
+          default: 604800000
+          description: |-
+            How long a published message stays readable, in milliseconds, before it is dropped from the
+            stream whether or not a listener consumed it. The week-long default applies when the topic was
+            created without one.
+          examples:
+            - 604800000
+            - 3600000
+        externalId:
+          type: string
+          maxLength: 1024
+          description: |-
+            Caller-chosen key set at creation or update. Present only when it was supplied; filter the
+            list with `GET /v1/topics?externalId=…`.
+          examples:
+            - erp-orders-created
+        _integrationId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: integrations
+          description: |-
+            Integration App installation that owns the topic. Present only on topics created by an
+            Integration App; absent on topics you create directly, which are shared across integrations
+            through `_registeredTopicIds` instead.
+          examples:
+            - 6ab1f4a138d7733b45998d99
+        _connectorId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: connectors
+          description: |-
+            Integration App (connector) that installed the topic. Present only on connector-managed
+            topics, which the connector — not the user — registers and deregisters.
+          examples:
+            - 5b3c8f9a2e1d4c0011223344
+        _templateId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: templates
+          description: Template the topic was installed from. Present only when it originated from a template.
+          examples:
+            - 6a27a36f9cea1a85192e72cd
+        _sourceId:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Topic this one was cloned or installed from. Present only on copies.
+          examples:
+            - 6aab2870265e1cf39fcbee4d
+        draft:
+          type: boolean
+          readOnly: true
+          description: |-
+            When true, the topic was created as a draft by the AI-assisted builder and has not been
+            confirmed yet. Absent on ordinary topics.
+          examples:
+            - true
+        draftExpiresAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when an unconfirmed draft is deleted automatically. Present only when `draft` is true.
+          examples:
+            - '2026-09-24T03:30:27.432Z'
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the topic was created.
+          examples:
+            - '2026-09-16T23:38:24.578Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the topic was last updated by PUT or PATCH.
+          examples:
+            - '2026-09-22T02:51:12.733Z'
+        deletedAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: |-
+            Timestamp when the topic was moved to the recycle bin. Present only on the copy returned by
+            `GET /v1/recycleBinTTL/topics/{_id}`; deleted topics are hidden from every other endpoint.
+          examples:
+            - '2026-09-22T03:29:50.803Z'
+    Request-3:
+      type: object
+      description: Writable fields for creating or updating a topic.
+      required:
+        - name
+      x-celigo-ai-guidance:
+        - |-
+          Always send name — the server does not enforce it and creates a topic with an empty name
+          that cannot be told apart in lists. On PUT send the whole document: omitted fields are
+          cleared (description, externalId) and retentionMs falls back to seven days.
+        - |-
+          Unknown top-level fields are dropped silently, so a misspelled field does not fail the
+          request — read the response body back to confirm what was stored.
+      properties:
+        name:
+          type: string
+          maxLength: 200
+          description: |-
+            Display name shown in the UI and recorded as `deletedInfo.name` on audit entries. Names need
+            not be unique — exports and imports bind to the topic id, so renaming never breaks a
+            subscription. Script tags and other unsafe HTML are stripped on save.
+          examples:
+            - orders.created
+        description:
+          type:
+            - string
+            - 'null'
+          maxLength: 5120
+          description: |-
+            What the topic carries and which flows consume it. Shown in the UI only; it plays no part in
+            routing. Send null to clear a previous value.
+          examples:
+            - One event per order placed. Consumed by the fulfillment and finance flows.
+        retentionMs:
+          type: integer
+          minimum: 3600000
+          maximum: 7776000000
+          default: 604800000
+          description: |-
+            How long a published message stays readable, in milliseconds, before it is dropped from the
+            stream whether or not a listener consumed it. The default keeps a week of messages, enough for
+            a listener that is paused over a weekend to catch up; the ceiling is further capped by the
+            account license's `topics.retentionCeilingDays`. Changing it on an existing topic
+            re-configures the stream, so messages older than the new window are no longer retained.
+          examples:
+            - 604800000
+            - 3600000
+          x-celigo-ai-guidance:
+            - |-
+              A value above the account's ceiling fails with 422 `topics_retention_exceeds_entitlement`;
+              read the ceiling from `GET /v1/licenses` (`topics.retentionCeilingDays`) before asking for
+              long retention. Below one hour fails with 422 `min`.
+        externalId:
+          type: string
+          maxLength: 1024
+          description: |-
+            Caller-chosen key for finding the topic again without storing its id — filter the list with
+            `GET /v1/topics?externalId=…`. Integration Apps use it to locate a topic across installs.
+          examples:
+            - erp-orders-created
+        __integrationIds:
+          type: array
+          maxItems: 100
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+          description: |-
+            Integrations to register the new topic on immediately after creation, so flows in those
+            integrations can subscribe to it. Honored only on `POST /v1/topics` (ignored on PUT), never
+            persisted, and not echoed back. Ids are validated before the topic is saved; registration
+            runs after the save, and per-integration failures are reported in
+            `__failedIntegrationRegistrations` on the 201 response without rolling back the new topic.
+          x-celigo-ai-guidance:
+            - |-
+              Invalid input rejects the whole request without creating the topic: a non-array value or
+              duplicate ids fail with 422 `invalid_request`, an element that is not a valid ObjectId fails
+              with 422 `invalid_ref` naming `__integrationIds[i]`, and an integration that does not exist
+              in the account fails with 404.
+            - To register an existing topic instead, use `PUT /v1/integrations/{_id}/topics/{_topicId}/register`.
+          examples:
+            - - 6ab1f4a138d7733b45998d99
     ILMIgnoreResponse:
       type: object
       description: |-
@@ -4300,6 +5107,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: |-