Events with server-sent events

The v1 API exposes Work activity as a server-sent events (SSE) stream:

GET /api/v1/work/{id}/events
Accept: text/event-stream
Authorization: Bearer <service-account-token>

This is a read stream, not a webhook registration API. The current public contract does not define webhook endpoints.

Open a stream

The service account needs work:read, and the Work must have been created by that same service account.

curl --no-buffer --fail-with-body \
  "$COLLEAGUEONE_API_BASE/api/v1/work/$WORK_ID/events" \
  --header "Accept: text/event-stream" \
  --header "Authorization: Bearer $COLLEAGUEONE_TOKEN"

Each activity frame contains:

id: <event-sequence>
event: <event-type>
data: <JSON-event>

The sequence in id is used for resumption. The event field carries the event type and data is JSON. Event type names and the JSON payload schema are intentionally not enumerated by the current OpenAPI contract, so consumers should preserve unknown fields and must not assume a closed list of event names.

Resume after a disconnect

Remember the last successfully processed event sequence. Reconnect with either the Last-Event-ID header or the after query parameter; the server sends only events with a greater sequence.

curl --no-buffer --fail-with-body \
  "$COLLEAGUEONE_API_BASE/api/v1/work/$WORK_ID/events" \
  --header "Accept: text/event-stream" \
  --header "Authorization: Bearer $COLLEAGUEONE_TOKEN" \
  --header "Last-Event-ID: $LAST_EVENT_ID"

Or:

GET /api/v1/work/{id}/events?after=42

after is a non-negative 64-bit integer. When it is present, it takes precedence over Last-Event-ID. Process an event before saving its sequence so a reconnect cannot skip unfinished work. Consumers should tolerate a replay if their checkpoint is saved later than processing.

Heartbeats and credential revocation

The server sends an SSE comment every 15 seconds:

: heartbeat

Comments are not activity events. Use them to distinguish an idle stream from a broken connection. The credential is checked again at every heartbeat; a revoked credential loses its stream within one heartbeat.

Browser and server clients

The browser EventSource API does not provide a way to set the required Authorization header. Do not put a service credential in a URL. Keep service credentials in trusted server-side code and use an HTTP client that can set headers and parse text/event-stream.

An SSE parser should:

1. Decode the response incrementally rather than buffering it to completion.
2. Ignore lines beginning with :.
3. Collect fields until the blank line that terminates a frame.
4. Parse joined data fields as JSON.
5. Checkpoint id only after processing succeeds.
6. Reconnect using the checkpoint if the connection ends.

Stream limits and errors

Each credential can hold a bounded number of open streams. The contract does not state the number. A 429 response can mean the concurrent-stream limit, the credential’s rate limit for that class, or an unauthenticated client-address budget is exhausted. Honor Retry-After before reconnecting; inspect RateLimit-Policy and RateLimit for the server-reported limit state.

The endpoint can also return 400, 401, 403, or 404 as an application/problem+json response. Unknown, cross-tenant, and otherwise concealed Work is not visible to the service account.

See the API quickstart for authentication and error handling, or the generated API reference for the complete operation contract.