Skip to content
WebsiteDocumentationDashboard ↗LibertyJS repo ↗npm package ↗GitHub organization ↗

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=50
  • subscriptionId: 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 when hasMore is 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. lastDroppedAt is 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

  1. Begin each scan without a cursor, starting at the oldest pending event.
  2. Process events and acknowledge only those successfully handled.
  3. If hasMore is true, pass the returned nextCursor as cursor to continue this scan.
  4. 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 as validation_failed or cursor_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 the Retry-After header (seconds on gateway responses). Gateway JSON can include error.retryAfterSeconds or error.retryAfterMs. Add a bounded fallback delay and jitter if absent.
  • 5xx or network failure: use bounded exponential backoff with jitter. Preserve unacknowledged work. Share requestId with 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.