API Reference

AlphaSmith exposes a REST API for programmatic access to analytics, portfolio data, and predictions. The API is available to subscribers on the API tier ($99/mo).

Base URL: https://api.alphasmith.ai
Authentication: Authorization: Bearer {token}
Rate limits: 500/min (API), 200/min (Premium), 100/min (Pro)

All responses are JSON. Errors follow Laravel’s standard {message, errors?} shape. Respect 429 responses and the Retry-After header. See the API Terms of Use and sign up to get started.

Quick start

Create a key in Settings → API Keys (API tier only), then call the API with an Authorization header.

# 1. Verify your token
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.alphasmith.ai/api/auth/me

# 2. Fetch analytics for AAPL
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.alphasmith.ai/api/stocks/AAPL/analytics

# 3. Run the stock screener
curl -X POST https://api.alphasmith.ai/api/screener/stocks \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"filters":{"ssi_state":["green"],"vq_pct":{"max":25}},"limit":25}'

Authentication

Method	Path	Auth	Description
POST	`api/auth/register`	Public	Register a new user account
POST	`api/auth/login`	Public	Authenticate and receive a bearer token
POST	`api/auth/logout`	Bearer	Revoke the current token
POST	`api/auth/forgot-password`	Public	Request a password-reset email
POST	`api/auth/reset-password`	Public	Complete password reset with token
POST	`api/auth/change-password`	Bearer	Change the current password
POST	`api/auth/2fa/enable`	Bearer	Begin 2FA enrollment (returns TOTP secret)
POST	`api/auth/2fa/verify`	Bearer	Confirm 2FA enrollment with a TOTP code
POST	`api/auth/2fa/disable`	Bearer	Disable two-factor authentication

Profile & Account

Current-user info, session management, API keys, and CCPA/GDPR self-serve account deletion.

Method	Path	Auth	Description
GET	`api/auth/me`	Bearer	Fetch the current authenticated user
PUT	`api/auth/profile`	Bearer	Update profile (name, timezone, etc.)
GET	`api/auth/sessions`	Bearer	List active bearer-token sessions
DELETE	`api/auth/sessions/{tokenId}`	Bearer	Revoke a specific session token
GET	`api/settings/api-keys`	Bearer	List the user’s API keys
POST	`api/settings/api-keys`	Bearer	Create a new API key (returned once in full)
DELETE	`api/settings/api-keys/{id}`	Bearer	Revoke an API key
GET	`api/account/deletion`	Bearer	Get deletion-request status
POST	`api/account/deletion`	Bearer	Submit an account-deletion request
DELETE	`api/account/deletion`	Bearer	Cancel a pending deletion request

Portfolios

CRUD for portfolios, positions, CSV import, and portfolio-level risk/allocation views.

Method	Path	Auth	Description
GET	`api/portfolios`	Bearer	List user portfolios
POST	`api/portfolios`	Bearer	Create a portfolio
GET	`api/portfolios/{id}`	Bearer	Show a portfolio with positions
PUT	`api/portfolios/{id}`	Bearer	Update portfolio metadata
DELETE	`api/portfolios/{id}`	Bearer	Delete a portfolio
GET	`api/portfolios/{id}/health`	Bearer	Aggregate risk & SSI health for the portfolio
GET	`api/portfolios/{id}/allocation`	Bearer	Allocation breakdown by asset/sector
GET	`api/portfolios/{id}/positions`	Bearer	List positions in a portfolio
POST	`api/portfolios/{id}/positions`	Bearer	Add a position
PUT	`api/portfolios/{id}/positions/{posId}`	Bearer	Update a position
DELETE	`api/portfolios/{id}/positions/{posId}`	Bearer	Remove a position
POST	`api/portfolios/{id}/import/preview`	Bearer	Parse an uploaded CSV and preview positions
POST	`api/portfolios/{id}/import/commit`	Bearer	Commit a previously previewed CSV import

Stocks

Per-symbol data: profile, analytics (VQ/SSI/rating), price history, fundamentals, institutional holdings, options, GEX, and AI predictions.

Method	Path	Auth	Description
GET	`api/stocks/{symbol}`	Bearer	Full stock profile
GET	`api/stocks/{symbol}/analytics`	Bearer	VQ, SSI, composite rating, momentum
GET	`api/stocks/{symbol}/history`	Bearer	OHLCV price history
GET	`api/stocks/{symbol}/fundamentals`	Bearer	Fundamental financial data
GET	`api/stocks/{symbol}/institutional`	Bearer	13F institutional-holdings data
GET	`api/stocks/{symbol}/predictions`	Bearer (Pro+)	21-day AI price projection
POST	`api/stocks/{symbol}/explain`	Bearer (Pro+)	SHAP explainability for the prediction
GET	`api/stocks/{symbol}/options`	Bearer (Pro+)	Options chain for the symbol
GET	`api/stocks/{symbol}/cycles`	Bearer (Pro+)	Cycle analysis (Fourier decomposition)
GET	`api/stocks/{symbol}/quantum`	Bearer (Pro+)	Quantum composite score breakdown
GET	`api/stocks/{symbol}/gex`	Bearer (Premium+)	Gamma exposure levels
GET	`api/stocks/{symbol}/volatility`	Bearer (Premium+)	IV surface + IV rank/percentile

Markets

Overall market health and major-index quotes.

Method	Path	Auth	Description
GET	`api/market/health`	Bearer	Overall market SSI, sector breakdown, breadth
GET	`api/market/indexes`	Bearer	Quotes for S&P 500, Nasdaq, Dow, Russell

Screener

Filter stocks and options by analytics, rating, cycles, and more. Saved screeners persist per user.

Method	Path	Auth	Description
POST	`api/screener/stocks`	Bearer	Run the stock screener with custom filters
	Example request body { "filters": { "ssi_state": ["green"], "vq_pct": { "max": 25 }, "rating": ["strong_bullish", "bullish"], "sector": ["Technology"], "market_cap": { "min": 2000000000 } }, "sort": "rating_score", "limit": 50 }
POST	`api/screener/options`	Bearer (Pro+)	Run the options screener (covered calls, CSPs, spreads)
	Example request body { "strategy": "covered_call", "min_pop_pct": 70, "min_annualized_roi": 20, "max_days_to_expiry": 45, "symbols": ["AAPL", "MSFT", "NVDA"] }
GET	`api/screener/prebuilt`	Bearer	List pre-built strategy screeners
GET	`api/screener/prebuilt/{strategy}`	Bearer	Run a pre-built screener (e.g. growth, value, billionaire_picks)
GET	`api/screener/saved`	Bearer	List the user’s saved screeners
POST	`api/screener/saved`	Bearer	Save a screener configuration
DELETE	`api/screener/saved/{id}`	Bearer	Delete a saved screener

AI

AI-curated watchlists, price predictions, explainability, and model-performance transparency.

Method	Path	Auth	Description
GET	`api/ai/watchlist`	Bearer (Pro+)	Daily AI-curated watchlist
GET	`api/ai/predict/{symbol}`	Bearer (Pro+)	21-day AI price projection
POST	`api/ai/explain/{symbol}`	Bearer (Pro+)	SHAP feature importance for a prediction
GET	`api/ai/performance`	Bearer (Pro+)	Rolling model accuracy metrics
POST	`api/ai/nl-screener`	Bearer (Pro+)	Translate a natural-language query into a screener config

Options

Unusual options-activity scanner. Per-symbol chain and GEX live under Stocks.

Method	Path	Auth	Description
GET	`api/options/unusual`	Bearer (Pro+)	Scan for unusual options activity across a liquid universe

Alerts

User-defined alerts (SSI change, VQ-stop, price target, AI signal) and reusable alert rule templates.

Method	Path	Auth	Description
GET	`api/alerts`	Bearer	List alerts
POST	`api/alerts`	Bearer	Create an alert
	Example request body { "symbol": "AAPL", "alert_type": "ssi_change", "condition": { "to_state": "red" }, "delivery_channels": ["email", "push"] }
GET	`api/alerts/{id}`	Bearer	Show a specific alert
PUT	`api/alerts/{id}`	Bearer	Update an alert
DELETE	`api/alerts/{id}`	Bearer	Delete an alert
GET	`api/alerts/history`	Bearer	History of triggered alerts
GET	`api/alerts/rules`	Bearer	List saved alert-rule templates
POST	`api/alerts/rules`	Bearer	Create an alert rule
PUT	`api/alerts/rules/{rule}`	Bearer	Update an alert rule
PUT	`api/alerts/rules/{rule}/default`	Bearer	Mark a rule as the default for its alert type
DELETE	`api/alerts/rules/{rule}`	Bearer	Delete an alert rule

Watchlists

User watchlists plus bulk analytics for all symbols on a list.

Method	Path	Auth	Description
GET	`api/watchlists`	Bearer	List watchlists
POST	`api/watchlists`	Bearer	Create a watchlist
GET	`api/watchlists/{id}`	Bearer	Show a watchlist
PUT	`api/watchlists/{id}`	Bearer	Update a watchlist
DELETE	`api/watchlists/{id}`	Bearer	Delete a watchlist
GET	`api/watchlists/{id}/analytics`	Bearer	Analytics rollup for all symbols on a watchlist

Checklists

Reusable pre-trade and review checklists with per-item CRUD.

Method	Path	Auth	Description
GET	`api/checklists`	Bearer	List checklists
POST	`api/checklists`	Bearer	Create a checklist
GET	`api/checklists/{id}`	Bearer	Show a checklist with items
PUT	`api/checklists/{id}`	Bearer	Update a checklist
DELETE	`api/checklists/{id}`	Bearer	Delete a checklist
POST	`api/checklists/{id}/items`	Bearer	Add an item to a checklist
PUT	`api/checklists/{id}/items/{item}`	Bearer	Update a checklist item
DELETE	`api/checklists/{id}/items/{item}`	Bearer	Delete a checklist item

Calendar

Upcoming market events (earnings, dividends, macro data).

Method	Path	Auth	Description
GET	`api/calendar/events`	Bearer	List upcoming calendar events
GET	`api/calendar/events/{date}`	Bearer	Events for a specific date (YYYY-MM-DD)

Smart Money

Institutional and billionaire 13F filers and their holdings.

Method	Path	Auth	Description
GET	`api/smart-money/filers`	Bearer	List 13F filers
GET	`api/smart-money/filers/{cik}`	Bearer	Show a filer’s recent holdings by CIK

Backtest

Submit, poll, and retrieve results for strategy backtests.

Method	Path	Auth	Description
GET	`api/backtest/runs`	Bearer (Premium+)	List the user’s backtest runs
POST	`api/backtest/run`	Bearer (Premium+)	Submit a new backtest job
	Example request body { "name": "SSI-green breakout", "start_date": "2021-01-01", "end_date": "2025-12-31", "symbols": ["AAPL", "MSFT", "NVDA"], "strategy_config": { "entry": { "ssi_state": "green", "rating": ["bullish", "strong_bullish"] }, "exit": { "ssi_state": ["yellow", "red"] }, "sizing": { "method": "vq_kelly", "max_risk_pct": 1.0 } } }
GET	`api/backtest/runs/{id}`	Bearer (Premium+)	Retrieve a completed run with metrics
GET	`api/backtest/runs/{id}/status`	Bearer (Premium+)	Poll backtest job status
DELETE	`api/backtest/runs/{id}`	Bearer (Premium+)	Delete a backtest run

Briefings

Daily AI-generated market briefings. Read-only for any authenticated user.

Method	Path	Auth	Description
GET	`api/briefings/today`	Bearer	Today’s market briefing
GET	`api/briefings/archive`	Bearer	Paginated briefing archive
GET	`api/briefings/{date}`	Bearer	Briefing for a specific date (YYYY-MM-DD)

Activity

Combined activity feed (alerts, portfolio events) and aggregate counters.

Method	Path	Auth	Description
GET	`api/activity`	Bearer	Combined activity feed
GET	`api/activity/stats`	Bearer	Activity counters and summary stats

Services

Publication cards (daily briefings surfaced for the dashboard services panel).

Method	Path	Auth	Description
GET	`api/services/publications`	Bearer	List publication cards

Risk

Position-sizing helpers (Kelly criterion, VQ-adjusted sizing).

Method Path Auth Description

POST api/risk/position-size Bearer Recommend a position size based on account risk and VQ

Method	Path	Auth	Description
POST	`api/risk/position-size`	Bearer	Recommend a position size based on account risk and VQ
	Example request body { "symbol": "AAPL", "account_value": 100000, "risk_per_trade_pct": 1.0, "entry_price": 185.20, "method": "vq_stop" }

Example request body

{
  "symbol": "AAPL",
  "account_value": 100000,
  "risk_per_trade_pct": 1.0,
  "entry_price": 185.20,
  "method": "vq_stop"
}

Billing

Plan listing is public. Subscribe, invoice, and Stripe portal access require authentication. Stripe webhook is excluded (internal).

Method	Path	Auth	Description
GET	`api/billing/plans`	Public	List subscription plans and prices
POST	`api/billing/subscribe`	Bearer	Start a Stripe Checkout session for a tier
POST	`api/billing/portal`	Bearer	Get a Stripe customer-portal URL
GET	`api/billing/invoices`	Bearer	List past invoices

Admin

Admin-only operational endpoints. Restricted to the configured admin allowlist (config/auth.admin_emails).

Method	Path	Auth	Description
GET	`api/admin/overview`	Admin	Operational overview (users, subs, compute)
GET	`api/admin/users/recent`	Admin	Recently registered users
POST	`api/admin/briefings/generate`	Admin	Dispatch GenerateBriefingJob (returns 202)
POST	`api/admin/alerts/evaluate-now`	Admin	Force an alert-evaluation pass
POST	`api/admin/test-broadcast`	Admin	Publish a test WebSocket event (ops smoke test)

Status

Public health + status endpoint for uptime monitors and the status page.

Method	Path	Auth	Description
GET	`api/status`	Public	Overall API + compute health snapshot

Informational analytics only — not investment advice. See the API Terms of Use and Risk Disclosure.