API Reference

First step of Google sign-in: submits the single-use reCAPTCHA token in the request body (never in a URL) and returns a short-lived signed `start` ticket. Returns 403 if reCAPTCHA verification fails — retry with a fresh token.

Start Google sign-in with the ticket from POST /auth/oauth/google/prepare. Redirects the browser to Google consent, then to {FRONTEND_URL}/auth/oauth/callback?code=... with a short-lived single-use authorization code. Accounts with TOTP enabled redirect to /auth/2fa instead. A missing/expired ticket redirects back to the login page with an error instead of returning an error page.

OAuth callback (internal) — exchanges the Google authorization code for a profile, then redirects the browser to the frontend with a single-use code ({FRONTEND_URL}/auth/oauth/callback?code=... or /auth/2fa?code=... for 2FA accounts).

Exchange the single-use authorization code from the OAuth callback redirect for a session JWT. For accounts with TOTP enabled, returns requires_2fa and a pending_token instead — complete login via POST /auth/2fa/login.

Legacy email/password login. Passwords were removed — this endpoint returns 404. Sign in via Google OAuth instead.

Exchange an expiring JWT for a fresh token and the refreshed user object.

Public reCAPTCHA v2 site key, used to protect anonymous endpoints (contact, feedback, signup).

Returns the current authenticated user, plan, email verification state, and subscription status.

Update profile fields: language, name, or avatar URL.

Referral status — shows referral code, total referrals, and free Pro months earned.

List all active sessions (devices/browsers) for the account.

Revoke a single session by ID.

Revoke all sessions except the current one.

Log out — invalidates the current session server-side.

Verify an email address with the token from the verification email.

Resend the email verification link to the given address.

Request an email address change. A confirmation link is sent to your current email.

Complete the email change using the token from the confirmation email.

Legacy password change. Passwords were removed — this endpoint returns 404. Sign in via Google OAuth.

Upload a profile avatar (multipart/form-data file). Returns the new avatar URL.

Request account deletion. A confirmation link is sent to your account email.

Permanently delete the account using the token from the confirmation email.

Unsubscribe from all digest/alert emails.

Get current notification preferences (digest frequency, alert breaks, categories).

Update notification preferences.

Get the synced theme preference (light, dark, or system).

Sync the theme preference to the account.

Recent search queries for the user (deduplicated).

Clear the user's search history.

Start TOTP (authenticator app) setup. Returns a secret, QR code URL, and otpauth URI to register.

Confirm a setup code to enable TOTP 2FA on the account.

Disable TOTP 2FA, verifying with a current code.

Complete sign-in for accounts with TOTP enabled. Exchange the pending token from POST /auth/oauth/exchange + 2FA code for a session JWT.

Send a support message. Requires a valid reCAPTCHA token. No authentication required.

Generate a new API key. Requires a Pro Developer (or higher) subscription. The raw key is shown once — store it immediately.

Revoke an API key immediately. Any requests using this key will return 401.

Create a scoped API key restricted to a specific set of endpoints. Requires a Pro Developer (or higher) subscription.

Compute the reading bias profile for the authenticated user from their reading history.

Bias detection across recent articles with per-article confidence scores.

Detect coverage blind spots — topics and sources the user has under-read relative to the news landscape.

Personal reading analytics — volume, categories, sources, and bias trend over time.

Get the personalized feed preferences for the account. Reader Power Tools module feature.

Update personalized feed preferences. Only provided fields are updated. Reader Power Tools module feature.

Get the personalized article feed ranked for the user. Reader Power Tools module feature.

List and search articles. Free for all users — auth is optional but lets you exceed the 30-day lookback window. Free users are limited to a 30-day lookback; Pro users can query further back. Export is Pro-only.

Generate a signed Custom RSS feed URL. Reader Power Tools module feature — the response includes a URL with a 30-day HMAC signature and expiry. Subscribe that URL in any RSS reader.

Custom RSS 2.0 feed for any keyword, source, or category. Reader Power Tools module feature — requires a valid exp + sig (HMAC) from /api/articles/rss/sign. Returns 403 feed_token_required if missing, invalid, or expired. Feeds honour the Pro 90-day lookback window.

Retrieve a single article by its ID. Requires a Pro Developer API key.

Mark an article as read for the authenticated user. Auth is optional — unauthenticated requests are silently ignored.

Return the authenticated user's read history as full article objects, newest read first.

List the authenticated user's saved articles, newest saved first.

Save an article to the user's saved list.

Remove an article from the user's saved list.

Download up to 50,000 matching articles as a CSV file. Requires a Pro Developer API key.

Download up to 50,000 matching articles as a JSON file. Requires a Pro Developer API key.

List all active sources with article counts and last scraped timestamps.

Aggregate source metadata — total counts by category, active totals.

Total number of tracked sources.

Metadata for a single source by name.

Returns up to 500 spider run records — status, articles added, and errors.

List the latest story clusters. Free users are limited to 50 stories.

Get a single story cluster by ID, including headline and summary.

List the articles that make up a story cluster.

Coverage analysis for a story — how each source covered the event.

Side-by-side comparison of how outlets framed a story.

Register a keyword alert. An email is sent when matching articles are scraped. Supports translation to a target language.

List all active alerts, optionally filtered by email.

Get the total count of alerts for a given email.

Remove a keyword alert by its ID.

Pause or resume a keyword alert. Set paused_until to a future timestamp to snooze (or now for immediate pause); null resumes.

Generate an on-demand digest without sending an email. Defaults to last 30 days.

Generate an on-demand digest with articles translated to a target language. Translation is unlimited and open to everyone; no auth required.

List saved rules with new-match counts ("N new" since you last applied each rule).

Create a saved rule. The new-match baseline starts at creation time.

Update a saved rule — rename, tweak filters, or toggle digest_enabled. Only provided fields are updated.

Delete a saved rule.

Duplicate a saved rule as "<name> (copy)" at the end of the list.

Per-rule counts of articles that arrived since each rule was last viewed.

Persist a new ordering (0-based) for the user's saved rules.

Run a saved rule now — current matching articles, newest first. Does not reset the new-match baseline.

Reset a rule's new-match baseline to now (clear its badge).

Share a saved rule with a team.

List smart alert rules (Team subscription required).

Create a smart alert rule with AND/OR/NOT logic, sensitivity, and optional sentiment/anomaly triggers (Team subscription required).

Update a smart alert rule. Only provided fields are updated.

Delete a smart alert rule.

Share an alert rule with a team.

Rule performance metrics — matches, alerts fired, precision.

Test whether a piece of text matches a rule.

Historical baseline for volume and velocity anomaly gates.

List configured anomaly alerts.

Create an anomaly alert on a metric with a threshold.

Update an anomaly alert.

Delete an anomaly alert.

Log of detected anomalies.

List saved and alert rules shared into teams the user belongs to, with team and sharer info.

Get articles tagged with a semantic signal (e.g. market-mover, urgency, controversy, sentiment-shift).

Enhanced signal view with per-article reasoning and score breakdowns.

Cross-signal correlations — how signals co-occur across articles.

Manually tag an article with a signal and score.

Signal trends over time — score evolution per signal.

Run automatic signal detection on a single article.

Run automatic signal detection across recent articles.

List ML signal patterns — keyword sets plus centroid embeddings used for semantic auto-tagging, with similarity thresholds and active flags.

Tune a signal pattern: similarity threshold (lower fires more often), decay hours, or enable/disable it. Disabled patterns are excluded from auto-tagging.

Latest forecast per metric (article_volume_24h, source_activity_{source}, manipulation/propaganda/spin indices) with confidence and validity windows.

List webhook configs. Requires a Pro Developer subscription.

Create a webhook. URL must be HTTPS and resolve to a public IP.

Update a webhook config — name, URL, events, headers, or pause/resume deliveries via active.

Delete a webhook config.

Send a test delivery to verify the endpoint.

Delivery history — status codes, retries, and payloads.

Retry a failed delivery.

List teams the user owns or belongs to.

Create a new team.

Update team name or seat count.

Delete a team.

List team members and their roles.

Add a member directly to the team.

Change a member's role.

Remove a member from the team.

Invite a user to the team by email.

Invite multiple users by email in one call.

List pending invitations for a team.

Revoke a pending invitation.

Recent team activity — rule changes, member changes.

Leave a team.

Transfer team ownership to another member.

List invitations sent to the current user.

Accept a team invitation.

Decline a team invitation.

Look up a user by email to add to a team.

Aggregate bias, source, and signal trends across all team members.

Get the team digest configuration.

Create the team digest configuration (upserts if one already exists).

Update the team digest configuration. Only provided fields are updated.

List the team's shared collections with story counts.

Create a shared collection for the team.

Delete a shared collection.

Add a story to a shared collection.

Remove a story from a shared collection.

List the team's story assignments with story and assignee details.

Assign a story to a team member.

Update an assignment's status, assignee, or notes.

Personal reading analytics — articles read, categories, sources, bias trend.

Export articles in a chosen format with a time range (1-2160 hours, 90 days). Requires a Pro Developer subscription.

List scheduled exports.

Create a scheduled export (e.g. daily/weekly).

Update a scheduled export. Only provided fields are updated.

Delete a scheduled export.

Post a comment on an article or a story.

List comments for an article or story.

Edit your own comment.

Delete your own comment.

Get the active payment processor and whether it is configured. mode is "test" or "live".

Return available Pro plan tiers and pricing.

Create a Lemon Squeezy hosted checkout for the chosen plan and return a redirect URL. The provider handles card, PayPal, Apple Pay, Google Pay and more; a webhook fulfils the subscription.

Create a Lemon Squeezy checkout for the in-app card form. Returns checkout_id (used by lemon.js to tokenize the card) and checkout_url (opened in the overlay, completed with the token). No billing address, cardholder name, or tax ID is collected — the email is taken from the authenticated user. Falls back to the hosted overlay for providers that require a billing address (e.g. when store tax is enabled).

Check whether the user can still start a free trial for the given plan (once per plan family, max 3 total).

Cancel an active Pro subscription or trial at the provider. Access continues until the end of the current billing period (period-end cancel). If the provider cancel fails, the request returns an error and local state is left unchanged.

Get the current subscription status, plan, and trial/billing dates.

Return all payment records for the authenticated user.

Lemon Squeezy webhook handler for subscription/order events (subscription_created, subscription_updated, subscription_cancelled, subscription_payment_success, order_refunded, etc.). Signed with the X-Signature HMAC-SHA256 header — do not call manually.

Trending search terms for the home page.

Public plan pricing list used by the pricing page.

Submit anonymous product feedback. Authenticated users skip reCAPTCHA.

Readiness probe — checks the DB connection pool and reports per-component status. Returns 200 when ready, 503 when the pool is unavailable.