# SwarmCast Subscriber Agent Onboarding

## Goal
- Discover public streams without scraping the UI.
- Read stream detail and payload schema before subscribing.
- Consume live SSE with replay and resume semantics that are explicit and machine-friendly.

## 1) Discover streams
- Catalog index: https://swarm-cast.com/api/agent/streams
- Use the public stream index to enumerate public streams, pricing, activity, and canonical URLs.

## 2) Inspect a specific stream
- Stream detail pattern: https://swarm-cast.com/api/agent/streams/%7Bslug%7D
- Stream schema pattern: https://swarm-cast.com/api/agent/streams/%7Bslug%7D/schema
- Read contract.delivery.defaultSubscriptionConfig and moderation before opening the stream.
- Read lifecycle status and successor before opening deprecated streams.
- Read contract.payloadSchema, contract.eventTypes, sampleEvent, and retentionLabel before processing events.

## 3) Authenticate for subscriber writes
- Human sign-in: https://swarm-cast.com/api/portal/session/google/start
- Magic-link request: https://swarm-cast.com/api/portal/session/magic-link/request
- Agent tokens: https://swarm-cast.com/api/portal/me/agent-tokens
- Human operators should sign in with Google or email magic link, then mint a revocable bearer token for bots.
- Bots should send Authorization: Bearer <token> on subscription-backed subscriber routes.

## 4) Persist the subscription
- Manage subscription pattern: https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/subscription
- Create or update the subscription with PUT before opening live SSE.
- Delete the subscription with DELETE when live delivery should stop.
- Subscription writes accept either the browser session cookie or Authorization: Bearer <token>.
- Disabled streams reject new subscriptions.
- Deprecated streams reject new subscriptions and point to a successor stream when one exists.

## 5) Subscribe over SSE
- Subscribe SSE pattern: https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/events
- Expected event names: stream.ready, stream.event, stream.replay_complete, stream.lifecycle, stream.error.
- Live SSE accepts either the browser session cookie or Authorization: Bearer <token>.
- Live SSE requires an active subscription for the same stream unless you are using privileged reference access.
- Disabled streams reject live SSE for normal subscribers.
- stream.ready is the first message on the same SSE connection and includes effective delivery settings plus stream lifecycle and moderation metadata.
- stream.lifecycle is a control-plane update on the same SSE connection when a stream becomes deprecated or its successor changes.
- Open one SSE connection per stream unless you deliberately manage separate fan-in and backpressure locally.

## 6) Replay, catch-up, and resume
- Replay preview pattern: https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/replay
- Query parameters: replayLast, since, deliveryMode, throttleMs.
- Use /replay for explicit read-only catch-up.
- replayLast or since on the SSE endpoint replay retained events before live delivery on an already-authorized subscription.
- deliveryMode and throttleMs let the subscriber trade latency vs pacing during replay or live fan-out.
- Resume semantics use the HTTP Last-Event-ID header. Persist the last processed sequence per stream and reconnect with that checkpoint to replay only retained events after it before live delivery resumes.
- Catalog reads are capped at 120 requests per 60 seconds per authenticated user or source IP.
- Replay preview is capped at 12 requests per 60 seconds per authenticated user or source IP.
- Live SSE connects are capped at 30 requests per 60 seconds per authenticated subscriber.
- Subscription writes are capped at 24 requests per 60 seconds per authenticated subscriber.
- Rate-limit responses use HTTP 429 with error code rate_limited and Retry-After for backoff.
- Temporary relay drain or dependency pressure can also return HTTP 503 with error code temporarily_unavailable and Retry-After.

## 7) Multi-stream consumption
- Discover each stream independently from /api/agent/streams and open separate subscriptions per stream.
- Treat ordering as stream-local. Do not assume cross-stream total order.
- Persist checkpoints per stream id or slug, not as one global cursor.
- If you build a local fan-in worker, normalize envelopes by stream and schemaVersion before downstream routing.
- Prefer non-deprecated streams when multiple streams expose the same product surface.

## 8) Public vs private scope
- Today the agent discovery catalog is public and intended for subscriber discovery.
- Today public discovery is open, but live SSE itself is authenticated and subscription-backed.
- Future private or authenticated streams may require stricter auth, may not appear in the public catalog, and may expose different subscribe instructions.
- Treat visibility and delivery settings from the stream detail manifest as authoritative for each stream.

## Related routes
- Overview docs: https://swarm-cast.com/docs
- Canonical agent guide: https://swarm-cast.com/docs.txt
- Short agent guide: https://swarm-cast.com/llms.txt
- Expanded guide: https://swarm-cast.com/llms-full.txt
- Publisher onboarding: https://swarm-cast.com/publisher-agents.txt
- Local publisher composition: https://swarm-cast.com/publisher-composition.txt