LibertyTools / Docs
Poll API reference
Use these endpoints from any server-side HTTP client. LibertyJS handles reads and acknowledgements for its command handlers; this reference is for integrations that manage delivery themselves.
Authentication
Get a subscription ID and one-time Poll token from Dashboard → Outputs → Poll clients. Send the token as a Bearer credential on every read and acknowledgement:
Authorization: Bearer <poll-token>Reading events with this HTTP API does not require an ER:LC server key. The public ingest URL cannot read events. Keep the Poll token out of query strings, browser applications, logs, and repositories.
Read pending events
GET https://api.libertytools.dev/v1/poll/subscriptions/:subscriptionId/events?limit=50subscriptionId: required path value from Outputs.limit: optional positive integer; defaults to 50. Values above 100 are capped at 100; invalid or nonpositive values return 400.cursor: optional opaque value from a previous response; URL-encode it when building a query string. Do not construct or decode cursors yourself.
Events are returned oldest first by receipt time, with event ID as a tie-breaker. Reading does not acknowledge them. A successful response is HTTP 200:
{
"events": [
{
"id": "evt_example",
"connectionId": "con_example",
"type": "CustomCommand",
"occurredAt": "2026-10-16T14:21:47.000Z",
"receivedAt": "2026-10-16T14:21:47.783Z",
"data": {
"userId": "98765",
"command": "help",
"argument": ""
},
"synthetic": false
}
],
"nextCursor": "opaque-cursor-from-server",
"hasMore": false,
"pendingCount": 1,
"oldestPendingAt": "2026-10-16T14:21:47.783Z",
"droppedCount": 0
}events: normalized events matching this subscription. See required and optional event fields.nextCursor: position after the last returned event, or null for an empty page. It can be non-null even whenhasMoreis false.hasMore: whether more events were available after this page at read time.pendingCount: pending backlog count; acknowledgement changes it.oldestPendingAt: oldest pending receipt time; omitted when none remain.droppedCount: cumulative drop count for this subscription.lastDroppedAtis included when a drop has been recorded. Neither field restores missing events.
Example with curl
These are shell examples for macOS/Linux, not PowerShell. Set the environment variables privately before running. Replace the example event ID in the acknowledgement with an ID you actually handled.
curl --silent --show-error --include \
--header "Authorization: Bearer $POLL_TOKEN" \
"https://api.libertytools.dev/v1/poll/subscriptions/$POLL_SUBSCRIPTION_ID/events?limit=50"Pagination and retry loop
- Begin each scan without a cursor, starting at the oldest pending event.
- Process events and acknowledge only those successfully handled.
- If
hasMoreis true, pass the returnednextCursorascursorto continue this scan. - At the end of the scan, wait before starting again without a cursor. Restart without a cursor after a process restart too.
A cursor is a page position, not an acknowledgement or a durable checkpoint. Keeping it forever can skip earlier events whose handlers failed. If a handler fails, leave that event unacknowledged and retry it in a later scan with a bounded delay. Deduplicate side effects using the event ID, including across process restarts.
Acknowledge processed events
POST https://api.libertytools.dev/v1/poll/subscriptions/:subscriptionId/events/acknowledge
Authorization: Bearer <poll-token>
Content-Type: application/json
{ "eventIds": ["evt_example"] }Send at most 100 string IDs per request. Duplicate IDs are collapsed. Acknowledgement applies only to this subscription; it does not remove another client's backlog. HTTP 200 returns:
{
"acknowledged": [
"evt_example"
],
"alreadyAcknowledged": [],
"unknown": []
}acknowledged contains newly acknowledged IDs; alreadyAcknowledged contains repeat acknowledgements. unknown contains IDs outside the subscription or no longer available, including deleted events. Inspect all three arrays instead of assuming HTTP 200 means every ID was found.
curl --silent --show-error --include \
--request POST \
--header "Authorization: Bearer $POLL_TOKEN" \
--header "Content-Type: application/json" \
--data '{"eventIds":["evt_example"]}' \
"https://api.libertytools.dev/v1/poll/subscriptions/$POLL_SUBSCRIPTION_ID/events/acknowledge"Errors and limits
Gateway errors use this envelope. Values below are illustrative; retry delays vary:
{
"error": {
"code": "rate_limited",
"message": "Poll read limit reached.",
"requestId": "req_example",
"retryAfterSeconds": 30
}
}400: invalid input such asvalidation_failedorcursor_invalid. Correct the input; discard an invalid cursor and start a fresh scan.401 credential_invalid: missing, incorrect, or revoked Poll credentials. Confirm the ID/token pair; rotate an exposed or lost token.404 connection_not_found: the connection is missing, paused, or restricted. Check its dashboard status.429: rate limited. Honor theRetry-Afterheader (seconds on gateway responses). Gateway JSON can includeerror.retryAfterSecondsorerror.retryAfterMs. Add a bounded fallback delay and jitter if absent.5xxor network failure: use bounded exponential backoff with jitter. Preserve unacknowledged work. SharerequestIdwith support when available.
A proxy or edge service can return a different body, so inspect HTTP status and headers before assuming JSON. Poll reads are limited to 120 per minute per subscription; other request protections also apply. Pending events expire after 14 days and are capped at 5,000 per subscription, oldest first. Connection storage eviction can remove them sooner. Check the retention limits and dropped counts when reconnecting.