Complete reference for the PulseAggregator API. Most data and account endpoints require authentication via Authorization: Bearer (JWT from Google OAuth) or an X-API-Key header. A few endpoints are free or public. Tier badges (PRO, PRO DEV, TEAM) show the minimum subscription required. See pricing →
Base URLhttps://api.pulseaggregator.com
Authentication methods
JWT Bearer
Authorization: Bearer eyJ...
From Google OAuth sign-in — valid 7 days. Used for account and tier-gated endpoints.
X-API-Key
X-API-Key: pa_xxxxxxxxxxxx
Used for data endpoints. Key creation requires a Pro Developer+ subscription.
Key / JWT
Either header
Endpoints marked "Key / JWT" accept either header. Some also work without auth.
Tier-gated endpoints require a verified subscription. The PRO badge means Pro Reader (or higher), PRO DEV means Pro Developer, and TEAM means Team. See pricing →
Rate limits are per-IP with brute-force protection and escalating lockout. Notable defaults: articles 120/min, article list & sources 60/min, digests/alerts 5 per 5 min, digests/preview 30/min, payments 20/min, contact 5 per 5 min. Request body size limit is 64KB.
Authentication
Google OAuth sign-in, JWT refresh, account profile, sessions, 2FA, email changes, notifications, and support contact. Account endpoints use the JWT from OAuth sign-in (Authorization: Bearer).
GET/auth/oauth/google
▼
Start Google sign-in. 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.
GET/auth/oauth/google/callback
▼
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).
POST/auth/oauth/exchange
▼
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.
POST/auth/login
▼
Legacy email/password login. Passwords were removed — this endpoint returns 404. Sign in via Google OAuth instead.
POST/auth/refresh
JWT
▼
Exchange an expiring JWT for a fresh token and the refreshed user object.
GET/auth/recaptcha-sitekey
▼
Public reCAPTCHA v2 site key, used to protect anonymous endpoints (contact, feedback, signup).
GET/auth/me
JWT
▼
Returns the current authenticated user, plan, email verification state, and subscription status.
PATCH/auth/me
JWT
▼
Update profile fields: language, name, or avatar URL.
GET/auth/referral/status
JWT
▼
Referral status — shows referral code, total referrals, and free Pro months earned.
GET/auth/sessions
JWT
▼
List all active sessions (devices/browsers) for the account.
DELETE/auth/sessions/{session_id}
JWT
▼
Revoke a single session by ID.
DELETE/auth/sessions
JWT
▼
Revoke all sessions except the current one.
POST/auth/logout
JWT
▼
Log out — invalidates the current session server-side.
POST/auth/verify-email
▼
Verify an email address with the token from the verification email.
POST/auth/resend-verification
▼
Resend the email verification link to the given address.
POST/auth/me/email/request
JWT
▼
Request an email address change. A confirmation link is sent to your current email.
POST/auth/me/email/confirm
▼
Complete the email change using the token from the confirmation email.
POST/auth/me/password
JWT
▼
Legacy password change. Passwords were removed — this endpoint returns 404. Sign in via Google OAuth.
POST/auth/me/avatar
JWT
▼
Upload a profile avatar (multipart/form-data file). Returns the new avatar URL.
POST/auth/me/delete/request
JWT
▼
Request account deletion. A confirmation link is sent to your account email.
POST/auth/me/delete/confirm
▼
Permanently delete the account using the token from the confirmation email.
POST/auth/unsubscribe
JWT
▼
Unsubscribe from all digest/alert emails.
GET/auth/me/notifications
JWT
▼
Get current notification preferences (digest frequency, alert breaks, categories).
PATCH/auth/me/notifications
JWT
▼
Update notification preferences.
GET/auth/me/theme
JWT
▼
Get the synced theme preference (light, dark, or system).
PUT/auth/me/theme
JWT
▼
Sync the theme preference to the account.
GET/auth/me/searches
JWT
▼
Recent search queries for the user (deduplicated).
DELETE/auth/me/searches
JWT
▼
Clear the user's search history.
POST/auth/2fa/setup
JWT
▼
Start TOTP (authenticator app) setup. Returns a secret, QR code URL, and otpauth URI to register.
POST/auth/2fa/verify
JWT
▼
Confirm a setup code to enable TOTP 2FA on the account.
POST/auth/2fa/disable
JWT
▼
Disable TOTP 2FA, verifying with a current code.
POST/auth/2fa/login
▼
Complete sign-in for accounts with TOTP enabled. Exchange the pending token from POST /auth/oauth/exchange + 2FA code for a session JWT.
POST/auth/contact
▼
Send a support message. Requires a valid reCAPTCHA token. No authentication required.
GET/auth/paypal-sdk-proxy
▼
Proxy the PayPal JS SDK to bypass ad-blockers. Adds the CORS header for the frontend origin.
API Keys
Create and manage API keys for server-to-server access. Creating keys requires a Pro Developer (or Team) subscription. Data endpoints are called with the X-API-Key header.
POST/auth/api-keys
JWTPRO DEV
▼
Generate a new API key. Requires a Pro Developer (or higher) subscription. The raw key is shown once — store it immediately.
DELETE/auth/api-keys/{key_id}
JWT
▼
Revoke an API key immediately. Any requests using this key will return 401.
POST/auth/api-keys/limited
JWTPRO DEV
▼
Create a scoped API key restricted to a specific set of endpoints. Requires a Pro Developer (or higher) subscription.
Personalization
Bias analysis, blind spots, preferences, and the personalized feed. Bias/analytics endpoints require Pro (Reader) — the personalized feed requires Pro Reader.
GET/auth/me/news-bias
JWTPRO
▼
Compute the reading bias profile for the authenticated user from their reading history.
GET/auth/me/bias-detection
JWTPRO
▼
Bias detection across recent articles with per-article confidence scores.
GET/auth/me/blindspots
JWTPRO
▼
Detect coverage blind spots — topics and sources the user has under-read relative to the news landscape.
GET/auth/me/analytics
JWTPRO
▼
Personal reading analytics — volume, categories, sources, and bias trend over time.
GET/auth/me/preferences
JWTPRO
▼
Get the personalized feed preferences for the account.
PUT/auth/me/preferences
JWTPRO
▼
Update personalized feed preferences. Only provided fields are updated.
GET/auth/me/feed
JWTPRO
▼
Get the personalized article feed ranked for the user.
Articles
Search, filter, and retrieve articles from 10000+ sources. Listing is free for everyone (free/unauthenticated requests default to a 7-day lookback window). Exports and single-article lookup require a Pro Developer API key.
GET/api/articles/
API Key
▼
List and search articles. Free for all users — auth is optional but lets you exceed the 7-day lookback window. Free users are limited to a 7-day lookback; Pro users can query further back. Export is Pro-only.
GET/api/articles/rss
API Key
▼
Custom RSS 2.0 feed for any keyword, source, or category. Public — no API key required (mirrors the free 7-day lookback window).
GET/api/articles/{id}
API KeyPRO DEV
▼
Retrieve a single article by its ID. Requires a Pro Developer API key.
POST/api/articles/{id}/read
API Key
▼
Mark an article as read for the authenticated user. Auth is optional — unauthenticated requests are silently ignored.
GET/api/articles/read-history
API Key
▼
Return the authenticated user's read history as full article objects, newest read first.
GET/api/articles/bookmarks
Key / JWT
▼
List the authenticated user's saved articles, newest saved first.
POST/api/articles/bookmarks/{article_id}
Key / JWT
▼
Save an article to the user's saved list.
DELETE/api/articles/bookmarks/{article_id}
Key / JWT
▼
Remove an article from the user's saved list.
GET/api/articles/export
API KeyPRO DEV
▼
Download up to 5000 matching articles as a CSV file. Requires a Pro Developer API key.
GET/api/articles/export/json
API KeyPRO DEV
▼
Download up to 5000 matching articles as a JSON file. Requires a Pro Developer API key.
Sources
Inspect the 10000+ news sources PulseAggregator monitors, plus spider run history. Auth is optional — these endpoints work without a key.
GET/api/sources/
API Key
▼
List all active sources with article counts and last scraped timestamps.
GET/api/sources/meta
API Key
▼
Aggregate source metadata — total counts by category, active totals.
GET/api/sources/count
API Key
▼
Total number of tracked sources.
GET/api/sources/{source_name}/meta
API Key
▼
Metadata for a single source by name.
GET/api/sources/runs
API Key
▼
Returns up to 500 spider run records — status, articles added, and errors.
Stories
Cross-source story clusters — related articles grouped by event. Requires authentication (JWT or API key). Free users can view the first 50 stories; more requires Pro.
GET/api/stories/
Key / JWT
▼
List the latest story clusters. Free users are limited to 50 stories.
GET/api/stories/{story_id}
Key / JWT
▼
Get a single story cluster by ID, including headline and summary.
GET/api/stories/{story_id}/articles
Key / JWT
▼
List the articles that make up a story cluster.
GET/api/stories/{story_id}/coverage
Key / JWT
▼
Coverage analysis for a story — how each source covered the event.
GET/api/stories/{story_id}/comparison
Key / JWT
▼
Side-by-side comparison of how outlets framed a story.
Alerts & Digests
Keyword alerts that trigger email notifications and on-demand digest previews. Auth is optional (JWT or API key). Alerts are limited to 5 per 5 minutes per IP.
POST/api/digests/alerts
Key / JWT
▼
Register a keyword alert. An email is sent when matching articles are scraped. Supports translation to a target language.
GET/api/digests/alerts
Key / JWT
▼
List all active alerts, optionally filtered by email.
GET/api/digests/alerts/count
Key / JWT
▼
Get the total count of alerts for a given email.
DELETE/api/digests/alerts/{id}
Key / JWT
▼
Remove a keyword alert by its ID.
PATCH/api/digests/alerts/{alert_id}
Key / JWT
▼
Pause or resume a keyword alert. Set paused_until to a future timestamp to snooze (or now for immediate pause); null resumes.
POST/api/digests/preview
Key / JWT
▼
Generate an on-demand digest without sending an email. Defaults to last 7 days.
POST/api/digests/preview-translate
Key / JWT
▼
Generate an on-demand digest with articles translated to a target language. Translation requires a Pro subscription.
Saved Rules
Saved search rules for quick re-runs. Requires a Pro (Reader) subscription or higher.
GET/pro/saved-rules
JWTPRO
▼
List saved rules for the current user.
POST/pro/saved-rules
JWTPRO
▼
Create a saved rule.
DELETE/pro/saved-rules/{id}
JWTPRO
▼
Delete a saved rule.
POST/pro/saved-rules/{id}/share
JWTPRO
▼
Share a saved rule with a team.
Alert Rules & Anomalies
Smart alert rules with AND/OR/NOT matching, sentiment triggers, anomaly detection and escalation. Alert rules require a Team subscription; anomaly alerts require Pro (Reader).
GET/pro/alert-rules
JWTTEAM
▼
List smart alert rules (Team subscription required).
POST/pro/alert-rules
JWTTEAM
▼
Create a smart alert rule with AND/OR/NOT logic, sensitivity, and optional sentiment/anomaly triggers (Team subscription required).
PATCH/pro/alert-rules/{rule_id}
JWTTEAM
▼
Update a smart alert rule. Only provided fields are updated.
Historical anomaly baseline for volume/velocity/sentiment.
GET/pro/anomaly-alerts
JWTPRO
▼
List configured anomaly alerts.
POST/pro/anomaly-alerts
JWTPRO
▼
Create an anomaly alert on a metric with a threshold.
PATCH/pro/anomaly-alerts/{alert_id}
JWTPRO
▼
Update an anomaly alert.
DELETE/pro/anomaly-alerts/{alert_id}
JWTPRO
▼
Delete an anomaly alert.
GET/pro/anomaly-log
JWTPRO
▼
Log of detected anomalies.
GET/pro/shared-resources
JWTPRO
▼
List saved and alert rules shared into teams the user belongs to, with team and sharer info.
Signals
Semantic signals — articles tagged with market-moving, urgency, controversy, and sentiment impact scores. Requires a Pro (Reader) subscription or higher.
GET/pro/signals/{signal}
JWTPRO
▼
Get articles tagged with a semantic signal (e.g. market-mover, urgency, controversy, sentiment-shift).
GET/pro/signals/{signal}/enhanced
JWTPRO
▼
Enhanced signal view with per-article reasoning and score breakdowns.
GET/pro/signals/correlations
JWTPRO
▼
Cross-signal correlations — how signals co-occur across articles.
POST/pro/signals
JWTPRO
▼
Manually tag an article with a signal and score.
GET/pro/signals/trends
JWTPRO
▼
Signal trends over time — score evolution per signal.
POST/pro/signals/auto-tag/{article_id}
JWTPRO
▼
Run automatic signal detection on a single article.
POST/pro/signals/auto-tag/recent
JWTPRO
▼
Run automatic signal detection across recent articles.
Webhooks
Outbound webhooks that fire on alerts and digests. Requires a Pro Developer subscription. URLs must be HTTPS and resolve to a public IP (SSRF-protected).
GET/pro/webhooks
JWTPRO DEV
▼
List webhook configs. Requires a Pro Developer subscription.
POST/pro/webhooks
JWTPRO DEV
▼
Create a webhook. URL must be HTTPS and resolve to a public IP.
PATCH/pro/webhooks/{webhook_id}
JWTPRO DEV
▼
Update a webhook config — name, URL, events, headers, or pause/resume deliveries via active.
DELETE/pro/webhooks/{webhook_id}
JWTPRO DEV
▼
Delete a webhook config.
POST/pro/webhooks/{webhook_id}/test
JWTPRO DEV
▼
Send a test delivery to verify the endpoint.
GET/pro/webhooks/{webhook_id}/deliveries
JWTPRO DEV
▼
Delivery history — status codes, retries, and payloads.
Multi-user teams for shared alert rules, saved rules, analytics, digests, collections, and story assignments. Requires a Team subscription. Team features are gated by a verified subscription, not just the plan field.
Update an assignment's status, assignee, or notes.
Exports, Analytics & Comments
Advanced exports, scheduled exports, reading analytics, and article comments. Analytics require Pro (Reader); exports require Pro Developer; comments require any authenticated user.
GET/pro/analytics
JWTPRO
▼
Personal reading analytics — articles read, categories, sources, bias trend.
GET/pro/export/with-range
JWTPRO DEV
▼
Export articles in a chosen format with a time range (1-720 hours). Requires a Pro Developer subscription.
GET/pro/export/scheduled
JWTPRO DEV
▼
List scheduled exports.
POST/pro/export/scheduled
JWTPRO DEV
▼
Create a scheduled export (e.g. daily/weekly).
PATCH/pro/export/scheduled/{export_id}
JWTPRO DEV
▼
Update a scheduled export. Only provided fields are updated.
DELETE/pro/export/scheduled/{export_id}
JWTPRO DEV
▼
Delete a scheduled export.
POST/pro/comments
JWT
▼
Post a comment on an article or a story.
GET/pro/comments
JWT
▼
List comments for an article or story.
PATCH/pro/comments/{comment_id}
JWT
▼
Edit your own comment.
DELETE/pro/comments/{comment_id}
JWT
▼
Delete your own comment.
Payments
Pro subscription payments — config and plans are public, trial signup, card vaulting, billing. Payment endpoints are rate-limited to 20 requests per minute per IP.
GET/api/payments/config
▼
Get PayPal client config (client ID, mode) for the frontend SDK.
GET/api/payments/plans
▼
Return available Pro plan tiers and pricing.
GET/api/payments/config-legacy
▼
Legacy PayPal config for the old SDK integration.
GET/api/payments/client-token
▼
Client token for the PayPal Vault/Orders SDK.
GET/api/payments/v6-sdk-proxy
▼
Proxy the PayPal JS SDK (V6) with proper CORS headers.
POST/api/payments/vault-setup-token
Key / JWT
▼
Create a PayPal setup token for card vaulting.
POST/api/payments/vault-order
Key / JWT
▼
Create a PayPal order for vault+payment combined flow.
POST/api/payments/vault-capture
Key / JWT
▼
Capture a vault order after buyer approval.
POST/api/payments/create-order
Key / JWT
▼
Create a one-time PayPal order for a plan.
POST/api/payments/vault-card
Key / JWT
▼
Vault a card from a PayPal SDK setup token. Stores the payment method for recurring billing.
POST/api/payments/start-trial
Key / JWT
▼
Start a 7-day free trial. Requires a vaulted card (call vault-card first). Each plan family (Pro Reader / Pro Developer / Team) can be trialed once, up to 3 trials total.
