Topics
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
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.
Maximum number of topics to return per page. Omit to return all topics.
100Field to sort by. Any other field name is rejected.
lastModifiedPossible values: Opaque cursor for forward pagination. Pass the value from the Link
response header (rel="next") to fetch the next page.
Return only topics whose externalId equals this value. Repeat the parameter to match any of
several values.
erp-orders-createdArray of topics.
No topics match — the account has none, or none carry the requested externalId.
after is not a cursor issued by this endpoint, or sort_by names an unsupported field.
Error code: invalid_query_param.
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[].
limit is not a positive integer. Error code: invalid_query_param.
GET /v1/topics HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"_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"
}
]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.
Writable fields for creating or updating a topic.
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.
orders.createdWhat 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.
One event per order placed. Consumed by the fulfillment and finance flows.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.
604800000Example: 604800000Caller-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.
erp-orders-createdIntegrations 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.
["6ab1f4a138d7733b45998d99"]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.
Topic as returned by the API.
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.
6ab1f44d7c4b4e699fe84b0aAccount owner whose license and topic quota the topic counts against.
624cb0346309dc3a543733a2Display name shown in the UI. Empty when the topic was created without one; not unique, so
use _id to identify a topic.
orders.createdWhat the topic carries and which flows consume it. Absent or null when never set.
One event per order placed. Consumed by the fulfillment and finance flows.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.
604800000Example: 604800000Caller-chosen key set at creation or update. Present only when it was supplied; filter the
list with GET /v1/topics?externalId=….
erp-orders-createdIntegration 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.
6ab1f4a138d7733b45998d99Integration App (connector) that installed the topic. Present only on connector-managed topics, which the connector — not the user — registers and deregisters.
5b3c8f9a2e1d4c0011223344Template the topic was installed from. Present only when it originated from a template.
6a27a36f9cea1a85192e72cdTopic this one was cloned or installed from. Present only on copies.
6aab2870265e1cf39fcbee4dWhen true, the topic was created as a draft by the AI-assisted builder and has not been confirmed yet. Absent on ordinary topics.
trueTimestamp when an unconfirmed draft is deleted automatically. Present only when draft is true.
2026-09-24T03:30:27.432ZTimestamp when the topic was created.
2026-09-16T23:38:24.578ZTimestamp when the topic was last updated by PUT or PATCH.
2026-09-22T02:51:12.733ZTimestamp 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.
2026-09-22T03:29:50.803ZUnauthorized. 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[].
An id in __integrationIds does not belong to an integration in this account. Nothing is created.
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).
POST /v1/topics HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 25
{
"name": "orders.created"
}{
"_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"
}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.
Topic id.
6aab2870265e1cf39fcbee4dTopic object.
Topic as returned by the API.
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.
6ab1f44d7c4b4e699fe84b0aAccount owner whose license and topic quota the topic counts against.
624cb0346309dc3a543733a2Display name shown in the UI. Empty when the topic was created without one; not unique, so
use _id to identify a topic.
orders.createdWhat the topic carries and which flows consume it. Absent or null when never set.
One event per order placed. Consumed by the fulfillment and finance flows.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.
604800000Example: 604800000Caller-chosen key set at creation or update. Present only when it was supplied; filter the
list with GET /v1/topics?externalId=….
erp-orders-createdIntegration 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.
6ab1f4a138d7733b45998d99Integration App (connector) that installed the topic. Present only on connector-managed topics, which the connector — not the user — registers and deregisters.
5b3c8f9a2e1d4c0011223344Template the topic was installed from. Present only when it originated from a template.
6a27a36f9cea1a85192e72cdTopic this one was cloned or installed from. Present only on copies.
6aab2870265e1cf39fcbee4dWhen true, the topic was created as a draft by the AI-assisted builder and has not been confirmed yet. Absent on ordinary topics.
trueTimestamp when an unconfirmed draft is deleted automatically. Present only when draft is true.
2026-09-24T03:30:27.432ZTimestamp when the topic was created.
2026-09-16T23:38:24.578ZTimestamp when the topic was last updated by PUT or PATCH.
2026-09-22T02:51:12.733ZTimestamp 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.
2026-09-22T03:29:50.803Z_id is not a 24-character hexadecimal ObjectId. Error code: invalid_ref.
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[].
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}.
GET /v1/topics/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"_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"
}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.
Topic id.
6aab2870265e1cf39fcbee4dWritable fields for creating or updating a topic.
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.
orders.createdWhat 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.
One event per order placed. Consumed by the fulfillment and finance flows.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.
604800000Example: 604800000Caller-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.
erp-orders-createdIntegrations 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.
["6ab1f4a138d7733b45998d99"]Updated topic.
Topic as returned by the API.
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.
6ab1f44d7c4b4e699fe84b0aAccount owner whose license and topic quota the topic counts against.
624cb0346309dc3a543733a2Display name shown in the UI. Empty when the topic was created without one; not unique, so
use _id to identify a topic.
orders.createdWhat the topic carries and which flows consume it. Absent or null when never set.
One event per order placed. Consumed by the fulfillment and finance flows.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.
604800000Example: 604800000Caller-chosen key set at creation or update. Present only when it was supplied; filter the
list with GET /v1/topics?externalId=….
erp-orders-createdIntegration 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.
6ab1f4a138d7733b45998d99Integration App (connector) that installed the topic. Present only on connector-managed topics, which the connector — not the user — registers and deregisters.
5b3c8f9a2e1d4c0011223344Template the topic was installed from. Present only when it originated from a template.
6a27a36f9cea1a85192e72cdTopic this one was cloned or installed from. Present only on copies.
6aab2870265e1cf39fcbee4dWhen true, the topic was created as a draft by the AI-assisted builder and has not been confirmed yet. Absent on ordinary topics.
trueTimestamp when an unconfirmed draft is deleted automatically. Present only when draft is true.
2026-09-24T03:30:27.432ZTimestamp when the topic was created.
2026-09-16T23:38:24.578ZTimestamp when the topic was last updated by PUT or PATCH.
2026-09-22T02:51:12.733ZTimestamp 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.
2026-09-22T03:29:50.803ZUnauthorized. 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[].
Not found. The requested resource does not exist or is not visible to the caller.
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.
PUT /v1/topics/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 139
{
"name": "orders.created",
"description": "One event per order placed. Consumed by the fulfillment and finance flows.",
"retentionMs": 86400000
}{
"_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"
}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.
Topic id.
6aab2870265e1cf39fcbee4dTopic moved to the recycle bin.
No content
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[].
Not found. The requested resource does not exist or is not visible to the caller.
An export, import, or flow still references the topic. Error code dependencies_not_deleted, one entry per blocking resource.
DELETE /v1/topics/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
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.
Topic id.
6aab2870265e1cf39fcbee4dA JSON Patch document (RFC 6902). Send an array of patch operations on whitelisted fields — all other paths are rejected with 422.
The operation to perform.
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".
The new value to set. Required for replace and add, omit for remove.
Topic patched. No body returned.
No content
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[].
Not found. The requested resource does not exist or is not visible to the caller.
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).
PATCH /v1/topics/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 99
[
{
"op": "replace",
"path": "/name",
"value": "orders.created.v2"
},
{
"op": "remove",
"path": "/description"
}
]No content
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.
Topic id.
6aab2870265e1cf39fcbee4dMaximum number of messages per page.
50Example: 20Continuation cursor from the previous page's nextPageURL; returns messages after that
position. Take it from nextPageURL rather than computing it.
49Only messages published strictly after this time, as Unix epoch milliseconds.
1790047477000Only messages published at or before this time, as Unix epoch milliseconds.
1790047500000One page of messages. messages is empty when nothing is retained in the requested window.
One page of retained messages.
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.
/v1/topics/6ab1f44d7c4b4e699fe84b0a/messages?limit=50&afterOffset=49A 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).
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[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/topics/{_id}/messages HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"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"
}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}.
Topic id.
6aab2870265e1cf39fcbee4dPurge result.
Result of purging a topic's retained messages.
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.
trueUnauthorized. 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[].
Not found. The requested resource does not exist or is not visible to the caller.
DELETE /v1/topics/{_id}/messages HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"deleted": true
}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.
Topic id.
6aab2870265e1cf39fcbee4dMessages to append to the topic.
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.
[{"orderId":"SO-1001","total":42.5},{"orderId":"SO-1002","total":18}]Per-message results in request order. A 200 means the request was accepted, not that every message was published.
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.
messages is missing or not an array. Error code: invalid_messages.
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[].
Not found. The requested resource does not exist or is not visible to the caller.
POST /v1/topics/{_id}/publish HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 82
{
"messages": [
{
"orderId": "SO-1001",
"total": 42.5
},
{
"orderId": "SO-1002",
"total": 18
}
]
}{
"responses": [
{
"statusCode": 200,
"_json": {}
},
{
"statusCode": 200,
"_json": {}
}
]
}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.
Topic id.
6aab2870265e1cf39fcbee4dId of the topic export (adaptorType: TopicExport) whose position to read.
6ab1f5b671fc8127d374d4edRead position of the export on this topic.
Read position of one topic export (listener) on a topic.
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).
A listener whose flow is disabled keeps its position; a listener saved without
type: "stream", or whose flow has not been enabled since the listener was saved, has
never subscribed and reports false.
trueZero-based position of the next message the export will read. -1 when hasCursor is
false. The position counts from the start of the stream, so while no message has expired
the retained message count minus offset is the listener's backlog.
1287Unauthorized. 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[].
The topic or the export does not exist in this account.
GET /v1/topics/{_id}/exports/{_exportId}/offsets HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"hasCursor": true,
"offset": 1287
}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.
Topic id.
6aab2870265e1cf39fcbee4dMaximum number of audit entries to return per page.
1000Example: 100Opaque 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.
W3siJGRhdGUiOiIyMDI2LTA5LTIyVDAzOjIyOjQzLjkyNVoifSwiNmFiMWY0ODM3YzRiNGU2OTlmZTg1NWI2Il0Only return entries at or after this timestamp.
2026-09-01T00:00:00.000ZOnly return entries at or before this timestamp.
2026-09-30T23:59:59.999ZFilter 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.
purgePossible values: Filter by how the change was initiated.
apiPossible values: Filter to changes performed by a single user.
624cb0346309dc3a543733a2Array of audit entries, newest first.
No audit entries exist for this topic.
limit is not a positive integer. Error code: invalid_query_param.
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[].
Not found. The requested resource does not exist or is not visible to the caller.
action or source is outside the audit vocabulary (invalid_audit_field), or from / to
is not an ISO 8601 timestamp (invalid_timestamp_format).
GET /v1/topics/{_id}/audit HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"_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
}
]
}
]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.
Topic id.
6aab2870265e1cf39fcbee4dDependency map. Keys are resource-type strings; values are arrays of dependency entries.
Returns {} when nothing references the topic.
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.
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[].
GET /v1/topics/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"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"
]
}
}
]
}Last updated
Was this helpful?