{"name":"Newsletter Agent API","description":"An agent-first newsletter API. Subscribe with an email to get a Bearer token, then read newsletter issues. Upgrade to paid ($5/mo) via x402 (USDC on Base) or Stripe to unlock premium content.","contact":{"twitter":"@StarvnChartist","email":"jonos@starvingchartist.ai"},"protocol":{"acp_version":"2026-01-30","x402":true,"openapi":"http://localhost:8000/docs"},"quickstart":[{"step":1,"action":"Subscribe to get a Bearer token","method":"POST","path":"/subscribe","body":{"email":"you@example.com"},"note":"Safe to call for any email — new or existing. If the email already exists in Beehiiv, the subscription is imported. Token is returned once — save it immediately."},{"step":2,"action":"Read newsletter issues (free tier)","method":"GET","path":"/newsletter/issues","headers":{"Authorization":"Bearer <token>"},"params":{"limit":10},"note":"Free subscribers see free-audience issues only."},{"step":3,"action":"Upgrade to paid for full content","method":"POST","path":"/checkout_sessions","headers":{"Authorization":"Bearer <token>"},"body":{"line_items":[{"id":"newsletter_paid","quantity":1}],"currency":"usd","capabilities":{"payment":{"handlers":[{"id":"handler_x402"}]}}},"note":"Creates an ACP checkout session. Then POST /checkout_sessions/{cs_id}/complete with credential.type='x402' to trigger HTTP 402. Pay USDC on Base (mainnet), retry with X-PAYMENT header. Or use header x-payment-method: stripe for Beehiiv-hosted Stripe checkout."},{"step":4,"action":"Read full paid issues","method":"GET","path":"/newsletter/issues","headers":{"Authorization":"Bearer <token>"},"note":"Paid subscribers see all issues with full paid content."}],"authentication":{"type":"Bearer token","header":"Authorization: Bearer <token>","obtain":"POST /subscribe with your email — token returned once","rotate":"POST /token/rotate (max 3/day) if token is lost","tiers":{"free":"Access to free-audience issues only","paid":"Access to all issues including premium content. Valid 30 days per payment."}},"endpoints":{"subscribe":{"method":"POST","path":"/subscribe","auth":false},"unsubscribe":{"method":"POST","path":"/unsubscribe","auth":true},"issues_list":{"method":"GET","path":"/newsletter/issues","auth":true,"params":["latest=true","since=ISO8601","limit=N"]},"issue_single":{"method":"GET","path":"/newsletter/issues/{post_id}","auth":true},"checkout_create":{"method":"POST","path":"/checkout_sessions","auth":true},"checkout_get":{"method":"GET","path":"/checkout_sessions/{cs_id}","auth":true},"checkout_complete":{"method":"POST","path":"/checkout_sessions/{cs_id}/complete","auth":true,"note":"Triggers x402 HTTP 402 payment flow"},"checkout_cancel":{"method":"POST","path":"/checkout_sessions/{cs_id}/cancel","auth":true},"me":{"method":"GET","path":"/me","auth":true,"note":"Auto-reconciles paid tier from Beehiiv"},"token_rotate":{"method":"POST","path":"/token/rotate","auth":true,"rate_limit":"3/day"}},"products":[{"id":"newsletter_free","name":"Newsletter Free","amount":0,"currency":"usd","content":"Free-audience issues only"},{"id":"newsletter_paid","name":"Newsletter Paid","amount":500,"currency":"usd","billing":"30 days per payment","content":"All issues including premium content","checkout_url":"/checkout_sessions"}],"payment_methods":[{"id":"x402/evm","description":"USDC on Base (mainnet)","how":"POST /checkout_sessions/{cs_id}/complete → receive HTTP 402 → pay on-chain → retry with X-PAYMENT header"},{"id":"x402/svm","description":"USDC on Solana (mainnet)","how":"POST /checkout_sessions/{cs_id}/complete → receive HTTP 402 → pay on-chain → retry with X-PAYMENT header"},{"id":"stripe/beehiiv","description":"Fiat via Beehiiv-hosted Stripe checkout","how":"Add header x-payment-method: stripe, then follow continue_url in response. Poll GET /me until tier == paid."}]}