@celigo/api-specs 0.2.38 → 0.2.40

package/dist/topic.yml

@@ -0,0 +1,1783 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Topics
+  description: Manage Event Streams topics — durable event streams that buffer published messages for topic exports.
+  x-celigo-ai-guidance:
+    - |-
+      API for managing Event Streams topics: account-level, durable message channels. A topic import
+      step (or POST /v1/topics/{_id}/publish) appends messages; each subscribed topic export step reads
+      them independently; messages expire after retentionMs. Topics are registered on integrations like
+      lookup caches (Integration._registeredTopicIds) through the /v1/integrations/{_id}/topics routes.
+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: Topics
+    description: |-
+      Topics are durable event streams that decouple the flows that publish messages from the flows
+      that consume them: a topic import step (or `POST /v1/topics/{_id}/publish`) appends messages, each
+      subscribed topic export step reads them at its own pace, and messages expire after the topic's
+      `retentionMs`. Event Streams is a licensed feature: listing topics works on every account, but
+      creating or updating a topic and every message operation require the `topics` entitlement —
+      without it they fail with `topics_subscription_required` (a 422 validation error on topic writes,
+      403 on the message endpoints) — and the license also caps how many topics the account may hold
+      (`topicsAllowed`) and the longest retention allowed (`retentionCeilingDays`).
+
+      ## Topic schema
+
+      {% openapi-schemas spec="topic" schemas="Topic" grouped="true" %}
+paths:
+  /v1/topics:
+    get:
+      x-internal: false
+      summary: List topics
+      description: |-
+        Returns the account's topics sorted by `name` ascending (ties by most recently modified first).
+        Topics in the recycle bin are not included. `include` and `exclude` projections are not
+        supported on this resource.
+      operationId: listTopics
+      tags:
+        - Topics
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of topics to return per page. Omit to return all topics.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+        - name: sort_by
+          in: query
+          required: false
+          description: Field to sort by. Any other field name is rejected.
+          schema:
+            type: string
+            enum:
+              - name
+              - lastModified
+            x-enumDescriptions:
+              name: Alphabetical by display name (the default)
+              lastModified: Most recently modified first
+            examples:
+              - lastModified
+        - $ref: '#/components/parameters/After'
+        - name: externalId
+          in: query
+          required: false
+          description: |-
+            Return only topics whose `externalId` equals this value. Repeat the parameter to match any of
+            several values.
+          schema:
+            type: string
+            examples:
+              - erp-orders-created
+      responses:
+        '200':
+          description: Array of topics.
+          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:
+                default:
+                  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'
+                    - _id: 6aab2870bb44c84f7b77e9f7
+                      _userId: 624cb0346309dc3a543733a2
+                      name: orders.fulfillment
+                      description: Pick, pack and ship instructions emitted by the fulfillment flow, one per order.
+                      retentionMs: 3600000
+                      externalId: wms-fulfillment
+                      createdAt: '2026-09-16T23:38:24.885Z'
+                      lastModified: '2026-09-16T23:38:24.885Z'
+        '204':
+          description: No topics match — the account has none, or none carry the requested `externalId`.
+        '400':
+          description: |-
+            `after` is not a cursor issued by this endpoint, or `sort_by` names an unsupported field.
+            Error code: `invalid_query_param`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                bad_sort:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: The query parameter "sort_by" has invalid value.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: '`limit` is not a positive integer. Error code: `invalid_query_param`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                bad_limit:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: Invalid limit sent in request.
+    post:
+      x-internal: false
+      summary: Create a topic
+      description: |-
+        Creates a topic and counts it against the license's `topics.topicsAllowed` quota. The stream
+        itself is provisioned lazily on the first publish, so a new topic reports no messages until
+        something is published to it. Pass `__integrationIds` to register the topic on integrations in the
+        same call; otherwise register it later with the `/v1/integrations/{_id}/topics/…/register`
+        operations so flows in those integrations can bind to it.
+      operationId: createTopic
+      tags:
+        - Topics
+      x-celigo-ai-guidance:
+        - |-
+          The account quota is enforced only on create and on restore from the recycle bin: when the
+          account already holds `topics.topicsAllowed` active topics the call fails with 422
+          `topics_limit_exceeded`. Topics sitting in the recycle bin do not count — delete or purge an
+          unused topic first.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              minimal:
+                summary: Name only — seven-day retention
+                value:
+                  name: orders.created
+              full:
+                summary: Custom retention, external key, registered on one integration
+                value:
+                  name: orders.fulfillment
+                  description: Pick, pack and ship instructions emitted by the fulfillment flow, one per order.
+                  retentionMs: 3600000
+                  externalId: wms-fulfillment
+                  __integrationIds:
+                    - 6ab1f4a138d7733b45998d99
+      responses:
+        '201':
+          description: |-
+            Created topic. When `__integrationIds` was sent and some registrations failed, the body also
+            carries `__failedIntegrationRegistrations`, an array of `{_integrationId, error}` entries — the
+            topic itself was still created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Topic'
+              examples:
+                created:
+                  value:
+                    _id: 6aab2870bb44c84f7b77e9f7
+                    _userId: 624cb0346309dc3a543733a2
+                    name: orders.fulfillment
+                    description: Pick, pack and ship instructions emitted by the fulfillment flow, one per order.
+                    retentionMs: 3600000
+                    externalId: wms-fulfillment
+                    createdAt: '2026-09-16T23:38:24.885Z'
+                    lastModified: '2026-09-16T23:38:24.885Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: An id in `__integrationIds` does not belong to an integration in this account. Nothing is created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unknown_integration:
+                  value:
+                    errors:
+                      - field: _id
+                        code: invalid_ref
+                        message: unable to find integration for the given id.
+        '422':
+          description: |-
+            Validation failed. `retentionMs` outside its bounds (`min`, `max`), above the license ceiling
+            (`topics_retention_exceeds_entitlement`), or not numeric (`invalid_field`); `name` longer than
+            200 characters (`maxlength`); `description` or `externalId` over their size limits
+            (`size_limit_exceeded`); the account at its topic quota (`topics_limit_exceeded`); or a
+            malformed `__integrationIds` (`invalid_request`, `invalid_ref`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                retention_above_ceiling:
+                  value:
+                    errors:
+                      - field: _id
+                        code: topics_retention_exceeds_entitlement
+                        message: The requested retention exceeds your account's topic retention ceiling of 90 days. Contact your account manager to raise it.
+                      - field: retentionMs
+                        code: max
+                        message: Path `retentionMs` (7776000001) is more than maximum allowed value (7776000000).
+                quota_reached:
+                  value:
+                    errors:
+                      - field: _id
+                        code: topics_limit_exceeded
+                        message: You have reached your topic limit of 20. Delete an unused topic or contact your account manager to raise the limit.
+                duplicate_integration_ids:
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: __integrationIds must not contain duplicate integration IDs.
+  /v1/topics/{_id}:
+    get:
+      x-internal: false
+      summary: Get a topic
+      description: |-
+        Returns a topic's configuration. Read its messages with `GET /v1/topics/{_id}/messages`. A topic
+        in the recycle bin is reported as not found; restore it first.
+      operationId: getTopicById
+      tags:
+        - Topics
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Topic id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+      responses:
+        '200':
+          description: Topic object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Topic'
+              examples:
+                default:
+                  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'
+        '400':
+          description: '`_id` is not a 24-character hexadecimal ObjectId. Error code: `invalid_ref`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                malformed_id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            No active topic has this id. A topic in the recycle bin answers with the message "You are
+            trying to access a Topic that is already in the Recycle Bin…"; restore it with
+            `POST /v1/recycleBinTTL/topics/{_id}`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Topic not found.
+                in_recycle_bin:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: You are trying to access a Topic that is already in the Recycle Bin. Please restore it from the Recycle Bin and try your request again.
+    put:
+      x-internal: false
+      summary: Update a topic
+      description: |-
+        Replaces the topic's writable fields with the request body. Fields left out are cleared, not
+        kept: `description` and `externalId` are removed and `retentionMs` reverts to seven days — send
+        the full document, or use PATCH to change `name` or `description` alone. Read-only fields in the
+        body are ignored. Changing `retentionMs` re-configures the stream's retention window;
+        the topic id and its subscriptions are unaffected.
+      operationId: updateTopic
+      tags:
+        - Topics
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Topic id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              shorten_retention:
+                summary: Shorten retention to one day
+                value:
+                  name: orders.created
+                  description: One event per order placed. Consumed by the fulfillment and finance flows.
+                  retentionMs: 86400000
+      responses:
+        '200':
+          description: Updated topic.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Topic'
+              examples:
+                updated:
+                  value:
+                    _id: 6aab2870265e1cf39fcbee4d
+                    _userId: 624cb0346309dc3a543733a2
+                    name: orders.created
+                    description: One event per order placed. Consumed by the fulfillment and finance flows.
+                    retentionMs: 86400000
+                    createdAt: '2026-09-16T23:38:24.578Z'
+                    lastModified: '2026-09-22T02:51:12.733Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            Validation failed — the same codes as on create: `min`, `max`,
+            `topics_retention_exceeds_entitlement`, `invalid_field` for `retentionMs`; `maxlength` for
+            `name`; `size_limit_exceeded` for `description` or `externalId`.
+          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).
+    patch:
+      x-internal: false
+      summary: Patch a topic
+      description: |-
+        Applies a JSON Patch document (RFC 6902) to the topic. Only `/name` and `/description` are
+        patchable; every other path — including `/retentionMs` and `/externalId` — is rejected, so use
+        PUT to change those. Unlike PUT, fields not named in the patch are left untouched.
+      operationId: patchTopic
+      tags:
+        - Topics
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Topic id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JsonPatchRequest'
+            examples:
+              rename:
+                summary: Rename and clear the description
+                value:
+                  - op: replace
+                    path: /name
+                    value: orders.created.v2
+                  - op: remove
+                    path: /description
+      responses:
+        '204':
+          description: Topic patched. No body returned.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            A path other than `/name` or `/description` was patched ("… is not a whitelisted property"),
+            or the new value failed validation (for example `maxlength` on `/name`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_whitelisted:
+                  value:
+                    errors:
+                      - message: /retentionMs is not a whitelisted property
+    delete:
+      x-internal: false
+      summary: Delete a topic
+      description: |-
+        Moves the topic to the recycle bin, where it is kept for 30 days before being purged, and removes
+        it from `_registeredTopicIds` on every integration that had it registered; restoring it does not
+        re-register it. Its retained messages are kept and become readable again if the topic is
+        restored, and are gone for good once the topic is purged. Deletion is refused while any export or
+        import still binds to the topic through `topic._topicId`, or a flow still contains such a step —
+        delete or repoint those first, and purge them from the recycle bin before purging the topic.
+      operationId: deleteTopic
+      tags:
+        - Topics
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Topic id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+      responses:
+        '204':
+          description: Topic moved to the recycle bin.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: An export, import, or flow still references the topic. Error code `dependencies_not_deleted`, one entry per blocking resource.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                listener_still_bound:
+                  value:
+                    errors:
+                      - code: dependencies_not_deleted
+                        message: export 6ab1f5b671fc8127d374d4ed must be deleted before you can delete topic 6aab2870265e1cf39fcbee4d
+  /v1/topics/{_id}/messages:
+    get:
+      x-internal: false
+      summary: List retained messages
+      description: |-
+        Reads the messages currently retained on a topic, oldest first, without affecting any
+        listener's read position — use it to inspect what producers are publishing or to confirm a
+        purge. Pages are cursor-based: follow `nextPageURL` until it is absent. Query parameters other
+        than the four below are ignored.
+      operationId: listTopicMessages
+      tags:
+        - Topics
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Topic id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of messages per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 50
+            examples:
+              - 20
+        - name: afterOffset
+          in: query
+          required: false
+          description: |-
+            Continuation cursor from the previous page's `nextPageURL`; returns messages after that
+            position. Take it from `nextPageURL` rather than computing it.
+          schema:
+            type: string
+            examples:
+              - '49'
+        - name: time_gt
+          in: query
+          required: false
+          description: Only messages published strictly after this time, as Unix epoch milliseconds.
+          schema:
+            type: integer
+            format: int64
+            examples:
+              - 1790047477000
+        - name: time_lte
+          in: query
+          required: false
+          description: Only messages published at or before this time, as Unix epoch milliseconds.
+          schema:
+            type: integer
+            format: int64
+            examples:
+              - 1790047500000
+      responses:
+        '200':
+          description: One page of messages. `messages` is empty when nothing is retained in the requested window.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TopicMessagesResponse'
+              examples:
+                page:
+                  summary: First of several pages
+                  value:
+                    messages:
+                      - timestamp: '2026-09-22T03:24:35.992Z'
+                        payload:
+                          orderId: SO-1001
+                          total: 42.5
+                      - timestamp: '2026-09-22T03:24:35.992Z'
+                        payload:
+                          orderId: SO-1002
+                          total: 18
+                    nextPageURL: /v1/topics/6aab2870265e1cf39fcbee4d/messages?limit=2&afterOffset=1
+                empty:
+                  summary: Nothing retained
+                  value:
+                    messages: []
+        '400':
+          description: |-
+            A query parameter is malformed: `limit` outside 1–100 (`invalid_limit`), `time_gt` or
+            `time_lte` not epoch milliseconds (`invalid_time_gt`, `invalid_time_lte`), or `afterOffset`
+            not a cursor issued by this endpoint (`invalid_after_offset`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                bad_limit:
+                  value:
+                    errors:
+                      - code: invalid_limit
+                        message: limit must be an integer between 1 and 100
+                        source: internal
+                bad_time:
+                  value:
+                    errors:
+                      - code: invalid_time_gt
+                        message: time_gt must be a Unix timestamp in milliseconds
+                        source: internal
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    delete:
+      x-internal: false
+      summary: Purge retained messages
+      description: |-
+        Removes every retained message from the topic while keeping the topic, its retention setting,
+        and its subscriptions; the purge cannot be undone. Records an audit entry with `event: purge`
+        and `fieldChanges[0].fieldPath: messages`. To remove the topic itself, use
+        `DELETE /v1/topics/{_id}`.
+      operationId: purgeTopicMessages
+      tags:
+        - Topics
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Topic id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+      responses:
+        '200':
+          description: Purge result.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PurgeMessagesResponse'
+              examples:
+                purged:
+                  value:
+                    deleted: true
+                nothing_to_purge:
+                  value:
+                    deleted: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/topics/{_id}/publish:
+    post:
+      x-internal: false
+      summary: Publish messages to a topic
+      description: |-
+        Appends messages to the topic in the order given, so every subscribed topic export receives them
+        on its next read. The first publish to a new topic provisions its stream, which can take a few
+        seconds longer than later calls. Oversized messages are rejected individually while the rest of
+        the batch is still published — always check `responses[].statusCode`.
+      operationId: publishTopicMessages
+      tags:
+        - Topics
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Topic id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PublishRequest'
+            examples:
+              two_orders:
+                value:
+                  messages:
+                    - orderId: SO-1001
+                      total: 42.5
+                    - orderId: SO-1002
+                      total: 18
+      responses:
+        '200':
+          description: |-
+            Per-message results in request order. A 200 means the request was accepted, not that every
+            message was published.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PublishResponse'
+              examples:
+                all_published:
+                  value:
+                    responses:
+                      - statusCode: 200
+                        _json: {}
+                      - statusCode: 200
+                        _json: {}
+                one_too_large:
+                  summary: Second message rejected for size, first one published
+                  value:
+                    responses:
+                      - statusCode: 200
+                        _json: {}
+                      - statusCode: 422
+                        errors:
+                          - code: topic_publish_event_too_large
+                            message: Message at index 1 exceeds the maximum allowed size of 1048576 bytes.
+                            source: resource
+                            resolved: false
+                            occurredAt: 1790047646930
+        '400':
+          description: '`messages` is missing or not an array. Error code: `invalid_messages`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_an_array:
+                  value:
+                    errors:
+                      - code: invalid_messages
+                        message: The "messages" field is required and must be a JSON array of objects to publish.
+                        source: internal
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/topics/{_id}/exports/{_exportId}/offsets:
+    get:
+      x-internal: false
+      summary: Get a listener's read position
+      description: |-
+        Reports how far a topic export (listener) has read on this topic — where its next run resumes.
+        Use it to check whether a listener is keeping up or has never run. The export must belong to the
+        account but need not subscribe to this topic; an export that does not simply has no cursor.
+      operationId: getTopicExportOffsets
+      tags:
+        - Topics
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Topic id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+        - name: _exportId
+          in: path
+          required: true
+          description: 'Id of the topic export (`adaptorType: TopicExport`) whose position to read.'
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: exports
+            examples:
+              - 6ab1f5b671fc8127d374d4ed
+      responses:
+        '200':
+          description: Read position of the export on this topic.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TopicExportOffsets'
+              examples:
+                consuming:
+                  summary: Listener that has committed a position
+                  value:
+                    hasCursor: true
+                    offset: 1287
+                never_consumed:
+                  summary: Listener that has not read this topic yet
+                  value:
+                    hasCursor: false
+                    offset: -1
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: The topic or the export does not exist in this account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                export_not_found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Export not found.
+  /v1/topics/{_id}/audit:
+    get:
+      x-internal: false
+      summary: Get audit log for a topic
+      description: |-
+        Returns the change history for a topic, newest first: who changed what and when, including
+        message purges, recycle-bin deletes and restores. Works for a topic in the recycle bin; once the
+        topic is purged, query `GET /v1/audit?resourceType=topic&_resourceId={_id}` instead.
+      operationId: getTopicAudit
+      tags:
+        - Topics
+      parameters:
+        - name: _id
+          in: path
+          description: Topic id.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+        - name: limit
+          in: query
+          description: Maximum number of audit entries to return per page.
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor for the next page. Take it from the `after` value in the `Link`
+            response header's `rel="next"` URL rather than constructing it.
+          schema:
+            type: string
+            examples:
+              - W3siJGRhdGUiOiIyMDI2LTA5LTIyVDAzOjIyOjQzLjkyNVoifSwiNmFiMWY0ODM3YzRiNGU2OTlmZTg1NWI2Il0
+        - name: from
+          in: query
+          required: false
+          description: Only return entries at or after this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-09-01T00:00:00.000Z'
+        - name: to
+          in: query
+          required: false
+          description: Only return entries at or before this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-09-30T23:59:59.999Z'
+        - name: action
+          in: query
+          required: false
+          description: |-
+            Filter by the change type. Maps to the `event` field on each entry; a value outside the
+            platform's audit vocabulary is rejected with 422 `invalid_audit_field`.
+          schema:
+            type: string
+            enum:
+              - create
+              - update
+              - delete
+              - view
+              - restore
+              - purge
+              - signin
+              - signout
+              - purgelogs
+            examples:
+              - purge
+            x-enumDescriptions:
+              create: A resource was created.
+              update: A resource was modified.
+              delete: A resource was deleted (moved to recycle bin).
+              view: A resource was viewed or accessed.
+              restore: A resource was restored from the recycle bin.
+              purge: Retained messages were purged, or the resource was permanently removed from the recycle bin.
+              signin: A user signed in to the account.
+              signout: A user signed out of the account.
+              purgelogs: Execution logs were purged for a resource.
+        - name: source
+          in: query
+          required: false
+          description: Filter by how the change was initiated.
+          schema:
+            type: string
+            enum:
+              - ui
+              - api
+              - system
+              - connector
+              - script
+              - sso
+            examples:
+              - api
+            x-enumDescriptions:
+              ui: Change made through the Celigo web UI.
+              api: Change made via the REST API.
+              system: Change made automatically by the platform.
+              connector: Change made by an Integration App (connector) process.
+              script: Change made by a custom script execution.
+              sso: Change triggered by an SSO authentication event.
+        - name: _byUserId
+          in: query
+          required: false
+          description: Filter to changes performed by a single user.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: users
+            examples:
+              - 624cb0346309dc3a543733a2
+      responses:
+        '200':
+          description: Array of audit entries, newest first.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination link. Includes `<...>; rel="next"` with an `after` cursor when more
+                entries exist; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Unique identifier for this audit entry.
+                      examples:
+                        - 6ab1f5ab8dc372a2b50ae31a
+                    resourceType:
+                      type: string
+                      description: Always `topic` for this endpoint.
+                      examples:
+                        - topic
+                    _resourceId:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: topics
+                      description: Id of the topic this entry belongs to.
+                      examples:
+                        - 6aab2870265e1cf39fcbee4d
+                    event:
+                      type: string
+                      description: |-
+                        Type of change. A topic's history runs create → update… → delete → restore or
+                        purge; `purge` also records each `DELETE /v1/topics/{_id}/messages`, which is
+                        told apart by `fieldChanges[0].fieldPath` being `messages`.
+                      enum:
+                        - create
+                        - update
+                        - delete
+                        - restore
+                        - purge
+                      x-enumDescriptions:
+                        create: Topic was created.
+                        update: Topic was modified by PUT or PATCH.
+                        delete: Topic was moved to the recycle bin.
+                        restore: Topic was restored from the recycle bin.
+                        purge: Retained messages were purged, or the topic was permanently removed from the recycle bin.
+                    source:
+                      type: string
+                      description: How the change was initiated. Restores from the recycle bin are recorded as `system`.
+                      enum:
+                        - api
+                        - ui
+                        - system
+                      x-enumDescriptions:
+                        api: Change made via the REST API.
+                        ui: Change made through the Celigo UI.
+                        system: Change made by an automated platform process.
+                    time:
+                      type: string
+                      format: date-time
+                      description: Timestamp when the change occurred.
+                      examples:
+                        - '2026-09-22T03:27:39.894Z'
+                    byUser:
+                      type: object
+                      description: User who made the change.
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: users
+                          description: User id.
+                          examples:
+                            - 624cb0346309dc3a543733a2
+                        email:
+                          type: string
+                          format: email
+                          description: User email address.
+                          examples:
+                            - user@example.com
+                        name:
+                          type: string
+                          description: User display name.
+                          examples:
+                            - Jane Doe
+                    fieldChanges:
+                      type: array
+                      description: |-
+                        Fields that were modified. Empty on `create`, `delete`, and `restore`; a single
+                        `messages` entry without values on a message purge.
+                      items:
+                        type: object
+                        properties:
+                          fieldPath:
+                            type: string
+                            description: Dot-notation path of the changed field, or `messages` for a message purge.
+                            examples:
+                              - retentionMs
+                          oldValue:
+                            description: Previous value (absent when the field was unset).
+                          newValue:
+                            description: New value (absent when the field was cleared).
+                    deletedInfo:
+                      type: object
+                      description: |-
+                        Present on every entry once the topic has been deleted; carries the topic's name at
+                        the time it was deleted so purged topics stay identifiable.
+                      properties:
+                        name:
+                          type: string
+                          description: Name of the topic when it was deleted.
+                          examples:
+                            - orders.created
+              examples:
+                default:
+                  value:
+                    - _id: 6ab1f5ab8dc372a2b50ae31a
+                      resourceType: topic
+                      _resourceId: 6aab2870265e1cf39fcbee4d
+                      source: api
+                      event: purge
+                      time: '2026-09-22T03:27:39.894Z'
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        email: user@example.com
+                        name: Jane Doe
+                      fieldChanges:
+                        - fieldPath: messages
+                    - _id: 6ab1f4837c4b4e699fe855b6
+                      resourceType: topic
+                      _resourceId: 6aab2870265e1cf39fcbee4d
+                      source: api
+                      event: update
+                      time: '2026-09-22T03:22:43.925Z'
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        email: user@example.com
+                        name: Jane Doe
+                      fieldChanges:
+                        - fieldPath: retentionMs
+                          oldValue: 604800000
+                          newValue: 3600000
+        '204':
+          description: No audit entries exist for this topic.
+        '400':
+          description: '`limit` is not a positive integer. Error code: `invalid_query_param`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                bad_limit:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: Invalid limit sent in request.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            `action` or `source` is outside the audit vocabulary (`invalid_audit_field`), or `from` / `to`
+            is not an ISO 8601 timestamp (`invalid_timestamp_format`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                bad_action:
+                  value:
+                    errors:
+                      - code: invalid_audit_field
+                        message: bogus is not a valid audit action.
+                bad_timestamp:
+                  value:
+                    errors:
+                      - code: invalid_timestamp_format
+                        message: 'Please make sure that the time provided for field: "from" is in ISO8601 time format.'
+  /v1/topics/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listTopicDependencies
+      tags:
+        - Topics
+      summary: List dependencies of a topic
+      description: |-
+        Returns the resources that reference the topic: `exports` and `imports` bound to it through
+        `topic._topicId`, `flows` that contain those steps, and `integrations` that list it in
+        `_registeredTopicIds`. Exports and imports listed here block `DELETE /v1/topics/{_id}` until they
+        are removed or repointed. An unknown topic id returns an empty map rather than 404.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Topic id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: topics
+            examples:
+              - 6aab2870265e1cf39fcbee4d
+      responses:
+        '200':
+          description: |-
+            Dependency map. Keys are resource-type strings; values are arrays of dependency entries.
+            Returns `{}` when nothing references the topic.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DependencyResponse'
+              examples:
+                listener_and_integration:
+                  summary: Topic with a listener export and one registration
+                  value:
+                    exports:
+                      - id: 6ab1f5b671fc8127d374d4ed
+                        name: Orders created listener
+                        paths:
+                          - topic._topicId
+                        accessLevel: manage
+                        dependencyIds:
+                          topic:
+                            - 6aab2870265e1cf39fcbee4d
+                    integrations:
+                      - id: 6ab1f4a138d7733b45998d99
+                        name: Order fulfillment
+                        paths:
+                          - _registeredTopicIds[*]
+                        accessLevel: manage
+                        dependencyIds:
+                          topic:
+                            - 6aab2870265e1cf39fcbee4d
+                empty:
+                  summary: Nothing references the topic
+                  value: {}
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    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:
+    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'
+    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
+    Request:
+      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
+    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'
+    TopicMessage:
+      type: object
+      description: One retained message, in publish order.
+      required:
+        - timestamp
+        - payload
+      properties:
+        timestamp:
+          type: string
+          format: date-time
+          description: Timestamp when the message was appended to the stream; the value `time_gt` and `time_lte` filter on.
+          examples:
+            - '2026-09-22T03:24:35.992Z'
+        payload:
+          description: |-
+            The message exactly as it was published — normally the JSON object sent in `messages[]`.
+            A value that was not valid JSON is returned verbatim as a string.
+          examples:
+            - orderId: SO-1001
+              total: 42.5
+    TopicMessagesResponse:
+      type: object
+      description: One page of retained messages.
+      required:
+        - messages
+      properties:
+        messages:
+          type: array
+          description: |-
+            Messages in the requested window, oldest first. Empty when the topic has never received a
+            message, when everything has aged out of `retentionMs`, or when the continuation cursor is
+            already at the end of the stream.
+          items:
+            $ref: '#/components/schemas/TopicMessage'
+        nextPageURL:
+          type: string
+          description: |-
+            Relative URL of the next page, carrying the same filters plus an `afterOffset` cursor.
+            Follow it as-is rather than building the cursor yourself. Absent on the last page.
+          examples:
+            - /v1/topics/6ab1f44d7c4b4e699fe84b0a/messages?limit=50&afterOffset=49
+    PurgeMessagesResponse:
+      type: object
+      description: Result of purging a topic's retained messages.
+      required:
+        - deleted
+      properties:
+        deleted:
+          type: boolean
+          description: |-
+            When true, the topic's stream was cleared — also reported when it held no messages at the time.
+            False only for a topic that has never received a message, so there was no stream to clear.
+          examples:
+            - true
+    PublishRequest:
+      type: object
+      description: Messages to append to the topic.
+      required:
+        - messages
+      x-celigo-ai-guidance:
+        - |-
+          The body must be an object with a messages array — a bare array or a missing/non-array
+          messages field fails with 400 `invalid_messages`. Other top-level keys are ignored.
+      properties:
+        messages:
+          type: array
+          description: |-
+            Messages to append, in order; each becomes one record that listeners receive. An empty array
+            is accepted and publishes nothing. Every message is serialized as JSON and may be at most
+            1 MiB; oversized messages are reported per entry in the response and the rest are still
+            published.
+          items:
+            type: object
+            description: One message. Any JSON object; the platform stores it as-is and returns it as `payload` when read back.
+          examples:
+            - - orderId: SO-1001
+                total: 42.5
+              - orderId: SO-1002
+                total: 18
+    PublishResponse:
+      type: object
+      description: |-
+        Per-message outcome of a publish call. The HTTP status is 200 whenever the request body was
+        valid; inspect each entry's `statusCode` to see which messages were appended.
+      required:
+        - responses
+      properties:
+        responses:
+          type: array
+          description: One entry per element of `messages`, in the same order. Empty when `messages` was empty.
+          items:
+            type: object
+            required:
+              - statusCode
+            properties:
+              statusCode:
+                type: integer
+                description: |-
+                  Outcome for this message: 200 when it was appended, 422 when it was rejected before
+                  publishing (for example because it exceeds the size limit), 500 when the stream
+                  refused the batch it belonged to.
+                examples:
+                  - 200
+                  - 422
+              _json:
+                type: object
+                description: Present when `statusCode` is 200. Currently always an empty object.
+                examples:
+                  - {}
+              errors:
+                type: array
+                description: Present when `statusCode` is not 200. Why this message was not published.
+                items:
+                  type: object
+                  required:
+                    - code
+                    - message
+                  properties:
+                    code:
+                      type: string
+                      description: |-
+                        Machine-readable reason. `topic_publish_event_too_large` when the serialized
+                        message exceeds 1 MiB; `topic_publish_failed` when the stream rejected the batch.
+                      examples:
+                        - topic_publish_event_too_large
+                    message:
+                      type: string
+                      description: Human-readable explanation, naming the message index.
+                      examples:
+                        - Message at index 0 exceeds the maximum allowed size of 1048576 bytes.
+                    source:
+                      type: string
+                      description: Layer that produced the error — `resource` for size rejections, `internal` for stream failures.
+                      examples:
+                        - resource
+                    resolved:
+                      type: boolean
+                      description: Always false here; publish errors are not retried by the platform.
+                      examples:
+                        - false
+                    occurredAt:
+                      type: integer
+                      description: Unix epoch milliseconds when the error was raised.
+                      examples:
+                        - 1790047646930
+    TopicExportOffsets:
+      type: object
+      description: Read position of one topic export (listener) on a topic.
+      required:
+        - hasCursor
+        - offset
+      properties:
+        hasCursor:
+          type: boolean
+          description: |-
+            When true, the export has committed a read position on this topic and its next run resumes
+            from `offset`. False when the export has never consumed the topic, when its last committed
+            position has expired from the stream, or when it does not listen to this topic at all — a
+            listener without a cursor starts from its own `topic.startPosition` (`latest` or `earliest`).
+          examples:
+            - true
+            - false
+        offset:
+          type: integer
+          minimum: -1
+          description: |-
+            Zero-based position of the next message the export will read. `-1` when `hasCursor` is
+            false.
+          examples:
+            - 1287
+            - -1
+    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
+        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: |-
+            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
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+x-internal: false
+x-enable-proxy: true