REST API

API Reference

All endpoints return JSON. Free endpoints (sources, alerts, digests) require an API key via X-API-Key header. Pro endpoints require a Pro subscription. Upgrade to Pro →

Base URLhttps://api.pulseaggregator.com

Authentication methods

JWT Bearer

Authorization: Bearer eyJ...

From /auth/login — valid 7 days. Used for account actions.

X-API-Key

X-API-Key: pa_xxxxxxxxxxxx

Required for ALL API access — free & Pro endpoints.

Endpoints marked PRO require an active Pro subscription. See pricing →

Rate limits vary by plan (Free and Pro tiers). Brute-force protection with escalating lockout. Request body size limits apply. Search lookback window depends on your plan.

Authentication

Register, log in, and manage JWT tokens and API keys. Free users get a default API key with access to limited endpoints. Pro subscription unlocks full article API access with higher rate limits.

POST/auth/register

▼

Create a new account. Returns a JWT token with limited validity.

POST/auth/login

▼

Authenticate and receive a JWT token with limited validity.

GET/auth/me

JWT

▼

Returns the current authenticated user, their language preference, API keys, and subscription status.

PATCH/auth/me

JWT

▼

Update user preferences including language for alerts and digests.

POST/auth/subscribe

JWT

▼

Create a PayPal recurring subscription for Pro. Returns a subscription_id used by the PayPal Smart Buttons.

POST/auth/contact

▼

Send a support message. No authentication required. Returns a confirmation.

POST/auth/forgot-password

▼

Request a password reset email.

POST/auth/reset-password

▼

Reset password using the token from email.

POST/auth/api-keys

JWTPRO

▼

Generate a new API key. Requires an active Pro subscription. The raw key is shown once — store it immediately.

DELETE/auth/api-keys/{id}

JWT

▼

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

Articles

Search, filter, and retrieve articles from 1000+ sources. Free users have a limited search window, Pro unlocks a longer lookback. All article endpoints require an API key. Export endpoints require Pro.

GET/api/articles/

API KeyPRO

▼

List and search articles. Requires a Pro API key via X-API-Key header. Rate limits vary by plan.

GET/api/articles/{id}

API KeyPRO

▼

Retrieve a single article by its ID. Requires Pro API key via X-API-Key header.

GET/api/articles/export

API KeyPRO

▼

Download matching articles as a CSV file. Requires a Pro API key.

GET/api/articles/export/json

API KeyPRO

▼

Download matching articles as a JSON file. Requires a Pro API key.

Sources

Inspect the 1000+ news sources PulseAggregator monitors. Requires API key.

GET/api/sources/

API Key

▼

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

GET/api/sources/runs

API Key

▼

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

Alerts & Digests

Manage keyword alerts that trigger email notifications. Free tier — requires API key for access.

POST/api/digests/alerts

API Key

▼

Register a keyword alert. An email is sent when matching articles are scraped. Supports language translation. Requires API key.

GET/api/digests/alerts

API Key

▼

List all active alerts, optionally filtered by email. Requires API key.

DELETE/api/digests/alerts/{id}

API Key

▼

Remove a keyword alert by its ID. Requires API key.

GET/api/digests/alerts/count

API Key

▼

Get the total count of alerts for a given email. Requires API key.

POST/api/digests/preview

API Key

▼

Generate an on-demand digest without sending an email. Defaults to last 7 days. Requires API key.

POST/api/digests/preview-translate

API Key

▼

Generate an on-demand digest with translated articles. Requires API key.

Payments

Manage PayPal recurring subscriptions. Requires a logged-in session (JWT).

POST/auth/payments/subscription-capture/{subscription_id}

JWT

▼

Activate Pro after the user approves a PayPal recurring subscription. Called from the Smart Buttons onApprove callback.

POST/auth/subscription/cancel

JWT

▼

Cancel a Pro subscription. Access remains active until the end of the current billing period. Also cancels the PayPal recurring subscription.

GET/auth/subscription

JWT

▼

Check the current subscription status and expiry date for the authenticated user.

GET/api/payments/history

JWT

▼

Return all payment records for the authenticated user.

Admin

Administrative endpoints. Requires X-Admin-Secret header.

POST/api/admin/run-spiders

▼

Manually trigger a full spider run.

POST/api/admin/users

▼

Create a user account (admin only).

PATCH/api/admin/users/plan

▼

Update a user's plan (admin only).

GET/api/admin/users

▼

List all users (admin only).

Pro

Pro-only endpoints for advanced users: saved rules, smart alerts, signals, teams, and webhooks. Requires active Pro subscription. Higher rate limits apply on article endpoints.

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.

GET/pro/alert-rules

JWTPRO

▼

List smart alert rules.

POST/pro/alert-rules

JWTPRO

▼

Create a smart alert rule with AND/OR/NOT logic.

GET/pro/signals/{signal}

JWTPRO

▼

Get articles tagged with a semantic signal.

GET/pro/webhooks

JWTPRO

▼

List webhook configs.

POST/pro/webhooks

JWTPRO

▼

Create a webhook for alerts.

GET/pro/teams

JWTPRO

▼

List teams (as owner or member).

POST/pro/teams

JWTPRO

▼

Create a new team.

GET/pro/export/with-range

JWTPRO

▼

Export with time range filter (1-720 hours / 30 days for Pro, 1-168 hours / 7 days for Free).

Something not working? Open a support ticket →

REST API

API Reference

All endpoints return JSON. Free endpoints (sources, alerts, digests) require an API key via X-API-Key header. Pro endpoints require a Pro subscription. Upgrade to Pro →

Base URLhttps://api.pulseaggregator.com

Authentication methods

JWT Bearer

Authorization: Bearer eyJ...

From /auth/login — valid 7 days. Used for account actions.

X-API-Key

X-API-Key: pa_xxxxxxxxxxxx

Required for ALL API access — free & Pro endpoints.

Endpoints marked PRO require an active Pro subscription. See pricing →

Rate limits vary by plan (Free and Pro tiers). Brute-force protection with escalating lockout. Request body size limits apply. Search lookback window depends on your plan.

Authentication

Register, log in, and manage JWT tokens and API keys. Free users get a default API key with access to limited endpoints. Pro subscription unlocks full article API access with higher rate limits.

POST/auth/register

▼

Create a new account. Returns a JWT token with limited validity.

POST/auth/login

▼

Authenticate and receive a JWT token with limited validity.

GET/auth/me

JWT

▼

Returns the current authenticated user, their language preference, API keys, and subscription status.

PATCH/auth/me

JWT

▼

Update user preferences including language for alerts and digests.

POST/auth/subscribe

JWT

▼

Create a PayPal recurring subscription for Pro. Returns a subscription_id used by the PayPal Smart Buttons.

POST/auth/contact

▼

Send a support message. No authentication required. Returns a confirmation.

POST/auth/forgot-password

▼

Request a password reset email.

POST/auth/reset-password

▼

Reset password using the token from email.

POST/auth/api-keys

JWTPRO

▼

Generate a new API key. Requires an active Pro subscription. The raw key is shown once — store it immediately.

DELETE/auth/api-keys/{id}

JWT

▼

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

Articles

GET/api/articles/

API KeyPRO

▼

List and search articles. Requires a Pro API key via X-API-Key header. Rate limits vary by plan.

GET/api/articles/{id}

API KeyPRO

▼

Retrieve a single article by its ID. Requires Pro API key via X-API-Key header.

GET/api/articles/export

API KeyPRO

▼

Download matching articles as a CSV file. Requires a Pro API key.

GET/api/articles/export/json

API KeyPRO

▼

Download matching articles as a JSON file. Requires a Pro API key.

Sources

Inspect the 1000+ news sources PulseAggregator monitors. Requires API key.

GET/api/sources/

API Key

▼

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

GET/api/sources/runs

API Key

▼

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

Alerts & Digests

Manage keyword alerts that trigger email notifications. Free tier — requires API key for access.

POST/api/digests/alerts

API Key

▼

Register a keyword alert. An email is sent when matching articles are scraped. Supports language translation. Requires API key.

GET/api/digests/alerts

API Key

▼

List all active alerts, optionally filtered by email. Requires API key.

DELETE/api/digests/alerts/{id}

API Key

▼

Remove a keyword alert by its ID. Requires API key.

GET/api/digests/alerts/count

API Key

▼

Get the total count of alerts for a given email. Requires API key.

POST/api/digests/preview

API Key

▼

Generate an on-demand digest without sending an email. Defaults to last 7 days. Requires API key.

POST/api/digests/preview-translate

API Key

▼

Generate an on-demand digest with translated articles. Requires API key.

Payments

Manage PayPal recurring subscriptions. Requires a logged-in session (JWT).

POST/auth/payments/subscription-capture/{subscription_id}

JWT

▼

Activate Pro after the user approves a PayPal recurring subscription. Called from the Smart Buttons onApprove callback.

POST/auth/subscription/cancel

JWT

▼

Cancel a Pro subscription. Access remains active until the end of the current billing period. Also cancels the PayPal recurring subscription.

GET/auth/subscription

JWT

▼

Check the current subscription status and expiry date for the authenticated user.

GET/api/payments/history

JWT

▼

Return all payment records for the authenticated user.

Admin

Administrative endpoints. Requires X-Admin-Secret header.

POST/api/admin/run-spiders

▼

Manually trigger a full spider run.

POST/api/admin/users

▼

Create a user account (admin only).

PATCH/api/admin/users/plan

▼

Update a user's plan (admin only).

GET/api/admin/users

▼

List all users (admin only).

Pro

Pro-only endpoints for advanced users: saved rules, smart alerts, signals, teams, and webhooks. Requires active Pro subscription. Higher rate limits apply on article endpoints.

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.

GET/pro/alert-rules

JWTPRO

▼

List smart alert rules.

POST/pro/alert-rules

JWTPRO

▼

Create a smart alert rule with AND/OR/NOT logic.

GET/pro/signals/{signal}

JWTPRO

▼

Get articles tagged with a semantic signal.

GET/pro/webhooks

JWTPRO

▼

List webhook configs.

POST/pro/webhooks

JWTPRO

▼

Create a webhook for alerts.

GET/pro/teams

JWTPRO

▼

List teams (as owner or member).

POST/pro/teams

JWTPRO

▼

Create a new team.

GET/pro/export/with-range

JWTPRO

▼

Export with time range filter (1-720 hours / 30 days for Pro, 1-168 hours / 7 days for Free).

Something not working? Open a support ticket →