HTTP endpoints

Sockudo exposes three endpoint groups:

• the main server port, usually 6001, for WebSocket upgrades and the signed app HTTP API
• optional operational endpoints on the main server port
• the metrics server port, usually 9601, for Prometheus scraping

Every route under /apps/{appId} requires Pusher-compatible signed query authentication. Push routes also evaluate the push capability headers described below.

WebSocket

Supported query parameters:

Publish

Useful request controls:

Revocation request body:

{
  "jti": "token-id",
  "client_id": "user-42",
  "expires_at": 1710003600,
  "ttl_seconds": 3600,
  "reason": "session revoked"
}

At least one of jti or client_id is required. ttl_seconds overrides expires_at; otherwise revocations default to 24 hours. Use the token's remaining lifetime for the TTL when it is known.

Channel state

Supported info tokens:

For channels matched by [ai_transport], /channels/{channelName} includes an ai object with active_streams, last_history_serial, and message_count.

Durable history

History query parameters:

Presence history

Presence history uses the same pagination and range controls as durable channel history. The snapshot endpoint is for operational reconstruction and should not be confused with /users, which returns current live members.

Versioned messages

Versioned-message endpoints require versioned_messages.enabled = true and a channel policy that permits mutable messages. They are Sockudo Protocol V2 surfaces. update, delete, and append accept optional op_id for mutation replay dedupe. Mutation responses include channel, message_serial, action, accepted, version_serial, history_serial, delivery_serial, and status.

Annotations

Annotation request fields:

Annotations require versioned messages, global annotations.enabled, and channel-level annotation permission.

When built with ably-compat, the root compatibility router additionally exposes GET and POST /channels/{channelName}/messages/{messageSerial}/annotations. POST accepts an Ably annotation array for create or delete. GET negotiates JSON or MsgPack and returns relative first/next Link relations with an opaque cursor scoped to the app, channel, and message. Compatibility capabilities annotation-publish, annotation-subscribe, annotation-delete-own, and annotation-delete-any remain independent from message mutation capabilities.

Push notifications

Push notifications are a core Sockudo API surface. Push endpoints are available when the binary is built with the push feature. They use signed app authentication plus capability headers.

With ably-compat, the root router also exposes /push/publish, /push/deviceRegistrations, /push/channelSubscriptions, and /push/channels. These are DTO/auth projections over the same durable store, queue, planner, provider, feedback, retry, status, scheduler, and cleanup services listed below. The Ably realtime transport is a real MessageService provider delivery, not a synthetic provider success. Run the native monolith workers in an in-process deployment, or provide the corresponding external workers for the configured queue stages.

Push publish bodies accept notBeforeMs to delay provider dispatch and expiresAtMs to stop late delivery and retry. The public API does not expose POST /push/scheduled; delayed delivery is created through /push/publish, while DELETE /push/scheduled/{jobId} only cancels jobs already persisted by scheduler/store integrations.

Publish responses include renderedPayloads. These previews are rendered from the same effective payload queued for delivery: templates are resolved at admission, request providerOverrides win over template overrides, and retries reuse the accepted rendered payload semantics. Missing templates, missing template variables, malformed overrides, and oversized provider payloads fail before provider dispatch.

Publish status inspection is available through GET /apps/{appId}/push/publish/{publishId}/status. Dead-letter messages are retained in the configured queue backend and are not exposed through a public HTTP listing endpoint yet.

Push headers:

Push list endpoints use cursor pagination with limit and opaque cursor.

Operational endpoints

Ably GET /stats accepts interval IDs or epoch milliseconds for start and end, unit/by values minute, hour, day, or month, forward/backward direction, a bounded limit, and opaque cursors carried in Link headers. Pagination is anchored to interval IDs and a fixed query horizon.

Disable /usage, /operator/stats, and operator aggregation stats in exposed production environments unless they are behind trusted ingress controls.

Metrics endpoint

The metrics server is independent from the main WebSocket/API listener and is enabled by METRICS_ENABLED.

Signed app API parameters

All /apps/* requests use Pusher-style query signing:

Use server SDKs for signing when possible. Custom signers must sign the canonical path exactly as routed, including /apps/{appId}.