# Guth agent feeds

Create one personalized Guth News feed for yourself without an email address or personal information.

## 1. Register
POST https://guth.news/v1/agent-feeds   (optional JSON body: {"label": "short name, no personal data"})
Response (201): feed_id, credential.api_key (shown once), claim.url (separate, single-use, expires in 7 days), endpoints.
Store api_key securely. Send it only as "Authorization: Bearer <api_key>". Never put it in a URL.
Give claim.url to your human. It does not contain or reveal api_key. Do not publish it.

## 2. Subscribe
PUT https://guth.news/v1/agent-feeds/me/subscriptions
{"topics": ["models"|"research"|"agents"|"tools"|"policy"|"infrastructure"|"business"|"robotics"], "companies": ["cloudflare"|"supabase"|"openai"|"apple"|"amazon"|"cursor"|"databricks"|"digitalocean"|"elevenlabs"|"fly-io"|"github"|"gitlab"|"google"|"hugging-face"|"ibm"|"meta"|"microsoft"|"midjourney"|"mistral-ai"|"neon"|"nvidia"|"planetscale"|"replit"|"salesforce"|"sourcegraph"|"together-ai"|"vercel"|"zed"|"arize"|"clickhouse"|"datadog"|"elastic"|"grafana"|"ollama"|"posthog"|"qdrant"|"redis"|"roboflow"|"anthropic"|"cohere"|"perplexity"|"groq"|"cerebras"|"sambanova"|"runway"|"stability-ai"|"replicate"|"pinecone"|"langchain"|"weaviate"], "keywords": ["2-40 chars each"], "rss": ["https://example.com/feed.xml"]}
GET https://guth.news/v1/agent-feeds/catalog lists what is available and its status. Companies (cloudflare, supabase, openai) deliver tracker items and daily notes plus Guth items that name the company. "rss": up to 5 public https feed URLs, checked when added and hourly after; items arrive as type external_link, labeled, never as Guth reporting.

## 3. Read
GET https://guth.news/v1/agent-feeds/me/feed[?cursor=...][&since=ISO-8601][&limit=1-100]
 - Items ascend by change time. Without a cursor you get the latest items. Save next_cursor and send it next time.
 - An item id is stable (guth:<article id>). A changed article returns again with change "updated" and a higher revision.
 - Empty result: 200 with items [] and the same cursor. Use If-None-Match with the ETag to get 304.
GET https://guth.news/v1/agent-feeds/me/whats-new[?cursor=...|since=ISO-8601]
 - Returns a plain-language recap built from the same items, with citations (id, title, canonical url). Default window: last 24 hours.

## Other
 - GET /v1/agent-feeds/me, PUT /v1/agent-feeds/me/preferences {"product_updates": true|false}
 - POST /v1/agent-feeds/me/credential/rotate (invalidates the old key), POST /v1/agent-feeds/me/claim-link (new claim link if unclaimed)
 - Errors: {"error":{"code","message"}}; 401 invalid_credential, 422 validation, 429 rate_limited (Retry-After), 503 source_unavailable.
 - Items are Guth-written and AI-labeled. At most one item every 7 days may be labeled "Guth Labs product update"; opt out with preferences.
 - Public RSS/Atom/JSON/OPML feeds are unchanged: https://guth.news/feeds