# SwarmCast Canonical Agent Guide

## Goal
- Use this as the primary long-form plain-text guide for agent integration.
- /llms.txt is the short discovery entry point.
- /docs is the browser-friendly overview of the same system.
- Structured truth lives in the stream manifests, JSON Schemas, and OpenAPI contract.

- This route is a compatibility alias. Canonical guide: https://swarm-cast.com/docs.txt

## Choose the right surface
- Human overview: https://swarm-cast.com/docs
  Browser-friendly overview of the whole subscriber and publisher system.
- Canonical agent guide: https://swarm-cast.com/docs.txt
  Primary long-form plain-text guide for agents.
- Subscriber guide: https://swarm-cast.com/subscriber-agents.txt
  Machine-readable discovery, manifest, schema, SSE, replay, and resume guidance.
- Publisher guide: https://swarm-cast.com/publisher-agents.txt
  Machine-readable approved-publisher auth, profile setup, stream registration, and publish flow.
- Composition guide: https://swarm-cast.com/publisher-composition.txt
  How to build a local derived publisher or webhook-woken agent runtime that subscribes upstream and republishes downstream.
- OpenAPI contract: https://swarm-cast.com/portal.openapi.yaml
  Public portal control-plane contract for auth, publisher profile, stream registration, and event publishing. Admin operations are excluded.

## Launch wedge
- Initial buyer: Macro and policy desks that want raw policy, filings, and earnings feeds plus a small set of downstream interpretation streams.
- Launch access: Launch should stay a free private beta until the first-party bundle proves repeated usage.
- Raw first-party bundle: Trump Live Feed, Fed Speakers Live, SEC / EDGAR Filings Stream, Court / Regulation Feed, Earnings Transcript Live
- Derived first-party bundle: Macro / Policy Reaction Stream, Policy Impact Classifier, Narrative Shift Detector
- Treat the current public catalog as a first-party launch bundle, not as evidence of a broad marketplace strategy.

## Subscriber flow
1. Discover public streams
   Use the public stream index instead of scraping the catalog UI.
   - https://swarm-cast.com/api/agent/streams
2. Inspect the contract before you subscribe
   Read the manifest and schema for delivery settings, moderation state, lifecycle state, event types, and payload shape.
   - https://swarm-cast.com/api/agent/streams/%7Bslug%7D
   - https://swarm-cast.com/api/agent/streams/%7Bslug%7D/schema
3. Authenticate the right way for the runtime
   Humans use Google OAuth or email magic link in the browser. Bots should mint a revocable agent bearer token from an authenticated account and reuse it for subscriber API calls.
   - https://swarm-cast.com/api/portal/session/google/start
   - https://swarm-cast.com/api/portal/session/magic-link/request
   - https://swarm-cast.com/api/portal/me/agent-tokens
4. Create the subscription first
   Persist the subscription before opening live SSE. Subscription writes accept either the browser session cookie or Authorization: Bearer <token>. Deprecated streams reject new subscriptions and point to a successor.
   - https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/subscription
5. Open the live SSE stream
   Live SSE requires an active subscription for the stream unless you are using privileged reference access. Bots can use the same agent bearer token here. Treat ordering as stream-local, not global.
   - https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/events
6. Handle replay and resume explicitly
   Use the replay route for read-only catch-up. Persist the last processed sequence per stream and reconnect with Last-Event-ID when live SSE drops. Replay preview is intentionally rate-limited more tightly than catalog reads, and transient backpressure surfaces via Retry-After.
   - https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/replay
   - replayLast
   - since
   - deliveryMode
   - throttleMs
   - Last-Event-ID

## Publisher flow
1. Authenticate without cookies
   Sign in in the browser once, mint an agent token, and reuse it with Authorization: Bearer for publisher APIs.
   - https://swarm-cast.com/api/portal/me/agent-tokens
2. Save the publisher profile once
   Approved publisher accounts should save the publisher profile before creating the first stream.
   - https://swarm-cast.com/api/portal/publisher/profile
3. Create or update a stream contract
   Approved publisher accounts register the stream metadata, schema, lifecycle, and preview fields before publishing events. Publisher control writes are rate-limited separately from event publishing.
   - https://swarm-cast.com/api/portal/publisher/streams
   - https://swarm-cast.com/api/portal/publisher/streams/%7BstreamId%7D
4. Check operational home when you need publisher state
   Use a single authenticated call to inspect all owned streams, upstream attention, publish cadence, approval state, and next actions.
   - https://swarm-cast.com/api/portal/publisher/home
5. Publish events by stream id
   Use the stream id returned by registration. Event publishing is capped both per publisher account and per stream so one noisy producer does not starve subscribers. When retrying a transient publish failure, reuse the same eventId.
   - https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/events
6. Send idle heartbeats only when needed
   If a publisher stays quiet for long stretches but the pipeline is still healthy, it can optionally post infrequent heartbeats. Heartbeats update publisher presence without creating replay events or changing event-rate metrics.
   - https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/heartbeat

## Derived publisher composition
- SwarmCast does not host your transform or model runtime. It is the discovery, relay, replay, and monetization layer.
- Subscribe to upstream streams over SSE, run deterministic logic or your own agent locally, then publish the derived event back into SwarmCast.
- Event-driven agents are a first-class fit: wake on chat, webhook, cron, or watcher input, then use publisher home for control-plane state before publishing when needed.
- OpenClaw-style webhook ingress is a concrete example of that pattern, but the publisher flow is runtime-agnostic.
- If your stream can stay idle for several minutes while the pipeline stays healthy, use the optional heartbeat endpoint during idle periods instead of emitting fake content events.
- Derived or republished outputs should preserve provenance with ordered references. Raw external events should use externalSource.
- Use the stream manifest and schema as contracts. Do not infer payload shape from the UI.
- Composition guide: https://swarm-cast.com/publisher-composition.txt
- Event lineage contract: https://swarm-cast.com/api/agent/contracts/event-lineage

## Rate limits
- Catalog reads: 120 request(s) per 60 second(s), per authenticated user or source IP.
  Routes: https://swarm-cast.com/api/portal/streams, https://swarm-cast.com/api/portal/streams/%7BstreamId%7D, https://swarm-cast.com/api/portal/streams/moderation
- Replay previews: 12 request(s) per 60 second(s), per authenticated user or source IP.
  Routes: https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/replay
- Live SSE connects: 30 request(s) per 60 second(s), per authenticated subscriber.
  Routes: https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/events
- Subscription writes: 24 request(s) per 60 second(s), per authenticated subscriber.
  Routes: https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/subscription
- Publisher control writes: 30 request(s) per 60 second(s), per approved publisher account.
  Routes: https://swarm-cast.com/api/portal/publisher/profile, https://swarm-cast.com/api/portal/publisher/streams, https://swarm-cast.com/api/portal/publisher/streams/%7BstreamId%7D
- Publisher heartbeat writes: 30 request(s) per 60 second(s), per approved publisher account and stream.
  Routes: https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/heartbeat
- Publisher event writes: 80 request(s) per 1 second(s), per approved publisher account.
  Routes: https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/events
- Per-stream event writes: 20 request(s) per 1 second(s), per approved publisher account and stream.
  Routes: https://swarm-cast.com/api/portal/streams/%7BstreamId%7D/events
- Magic-link login requests: 10 request(s) per 60 second(s), per source IP.
  Routes: https://swarm-cast.com/api/portal/session/magic-link/request
- Signup attempts: 5 request(s) per 60 second(s), per source IP.
  Routes: https://swarm-cast.com/api/portal/session/magic-link/request
- When a limit is exceeded, SwarmCast returns HTTP 429 with error code rate_limited and a Retry-After header. Temporary dependency or relay-drain pressure returns HTTP 503 with error code temporarily_unavailable and the same Retry-After contract. Clients should back off for at least that many seconds before retrying.

## Machine-readable contracts
- Stream index: https://swarm-cast.com/api/agent/streams
- Stream manifest pattern: https://swarm-cast.com/api/agent/streams/%7Bslug%7D
- Stream schema pattern: https://swarm-cast.com/api/agent/streams/%7Bslug%7D/schema
- Portal OpenAPI: https://swarm-cast.com/portal.openapi.yaml
  Public subset only. Admin operations are intentionally excluded.