Better RSS API

Base URL

https://www.better-rss.com/api/v1

Authentication

Every request sends a bearer token in the Authorization header:

Authorization: Bearer brss_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate tokens from Settings → API. Each token has read and/or write scopes and an optional expiry (30d, 90d, 1y, or never). The raw token is shown once on creation — save it immediately. Revoke any time from the same page.

Tokens belong to you. Don't share them. If one leaks, revoke it. Short-lived tokens are safer for scripts and one-off integrations.

How It Works

1. Upgrade the account to Pro or Ultra.
2. Open Settings → API and create a token.
3. Pick read for list/sync clients, or add write for clients that mark items read, star items, subscribe, or unsubscribe.
4. Store the token in your app or script environment as a secret.
5. Call /api/v1/* with the bearer header shown above.

The API checks the token, token expiry, token scope, resource ownership, current Pro/Ultra status, and daily API cap on every request. If the account leaves Pro or Ultra, existing tokens stop working with 402 pro_required until API access is active again.

Quick Check

Use /me as a simple integration health check.

curl https://www.better-rss.com/api/v1/me \
  -H "Authorization: Bearer $BRSS_TOKEN"

{
  "email": "<account-email>",
  "tier": "pro",
  "scopes": ["read", "write"]
}

CORS

All /api/v1/* endpoints send Access-Control-Allow-Origin: *, so browser apps can call them directly with fetch(). The API uses bearer-token auth — no cookies are ever read — which is why permissive CORS is safe.

Errors

JSON errors on non-2xx responses:

{
  "error": {
    "code": "invalid_token",
    "message": "Token is invalid or revoked."
  }
}

• 400 — malformed request
• 401 — missing or bad token
• 402 — Pro or Ultra tier required
• 403 — token lacks the required scope
• 404 — resource not found or not yours
• 429 — rate limited
• 500 — something broke on our side

Endpoints

GET /me

Who am I? Useful for client health checks.

curl https://www.better-rss.com/api/v1/me \
  -H "Authorization: Bearer $BRSS_TOKEN"

GET /stats

Reading statistics for the authenticated Pro or Ultra account.

curl https://www.better-rss.com/api/v1/stats \
  -H "Authorization: Bearer $BRSS_TOKEN"

GET /items

List items from your subscribed feeds. Newest first.

Query params:

• feed_id — restrict to one feed
• unread=true — only unread items
• starred=true — only starred items
• since — ISO 8601 date; items published after this
• limit — 1-100, default 50
• offset — pagination

curl "https://www.better-rss.com/api/v1/items?unread=true&limit=25" \
  -H "Authorization: Bearer $BRSS_TOKEN"

POST /items/:id/read

Mark an item read or unread. Scope: write.

curl -X POST "https://www.better-rss.com/api/v1/items/$ID/read" \
  -H "Authorization: Bearer $BRSS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read": true}'

POST /items/:id/star

Star or unstar an item. Scope: write.

curl -X POST "https://www.better-rss.com/api/v1/items/$ID/star" \
  -H "Authorization: Bearer $BRSS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"starred": true}'

GET /feeds

List your subscriptions.

curl https://www.better-rss.com/api/v1/feeds \
  -H "Authorization: Bearer $BRSS_TOKEN"

POST /feeds/subscribe

Subscribe to a new feed. Returns the existing subscription if you're already subscribed. Scope: write.

curl -X POST https://www.better-rss.com/api/v1/feeds/subscribe \
  -H "Authorization: Bearer $BRSS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/feed.xml", "tag": "tech"}'

DELETE /feeds/:id

Unsubscribe. Scope: write.

curl -X DELETE "https://www.better-rss.com/api/v1/feeds/$FEED_ID" \
  -H "Authorization: Bearer $BRSS_TOKEN"

GET /briefs

List your AI-generated briefs. Newest first.

curl "https://www.better-rss.com/api/v1/briefs?limit=10" \
  -H "Authorization: Bearer $BRSS_TOKEN"

GET /briefs/:id

Full brief, including the markdown body.

curl "https://www.better-rss.com/api/v1/briefs/$BRIEF_ID" \
  -H "Authorization: Bearer $BRSS_TOKEN"

Stability

This is v1. If a field changes shape or a resource moves, we'll do it under /api/v2. v1 stays as-is.