Dipsern
API · v1

REST endpoints for power users.

Bearer-authenticated HTTP access to the same engine that grades 2,200+ assets every morning. JSON in, JSON out, no SDK required. Available on the Premium tier ($299/mo).

QuickstartBrowse endpointsopenapi.yaml
Quickstart

Your first call in three steps.

Generate a key, set it as an environment variable, then hit any endpoint with a Bearer token. The SDK is optional — every endpoint is documented in OpenAPI 3.1.

1

Upgrade to Premium

API access ships with the Premium plan only. Visit /pricing to upgrade.

2

Generate a key

Open /dashboard/settings → API keys. The full value is shown once.

3

Make your first call

Hit any endpoint with the Authorization header. Verdict endpoint returns in <150ms.

curl
# 1. Generate a key in /dashboard/settings
export DIPSERN_KEY="dipsern_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 2. Your first call — verdict-only, <150ms
curl -H "Authorization: Bearer $DIPSERN_KEY" \
  "https://dipsern.com/api/analysis/AAPL/verdict?return_period=90"
Python
import os, requests

key = os.environ["DIPSERN_KEY"]
res = requests.get(
    "https://dipsern.com/api/analysis/AAPL/verdict",
    headers={"Authorization": f"Bearer {key}"},
    params={"return_period": 90},
    timeout=15,
)
res.raise_for_status()
grade = res.json()["grade"]
print(grade["letter"], grade["score"])
JavaScript / TypeScript
const res = await fetch(
  "https://dipsern.com/api/analysis/AAPL/verdict?return_period=90",
  { headers: { Authorization: `Bearer ${process.env.DIPSERN_KEY}` } }
)
if (!res.ok) throw new Error(`API ${res.status}`)
const { grade } = await res.json()
console.log(grade.letter, grade.score)
Authentication

One header. One Bearer token.

Every authenticated request carries an Authorization header. Keys are SHA-256 hashed at rest; the full value is never recoverable after generation. Maximum 5 active keys per user.

# Every request includes the Authorization header:
curl -H "Authorization: Bearer dipsern_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://dipsern.com/api/ranking?category=US%20Stocks

# A missing or bad key returns 401. A valid key on a non-Premium user returns 402.

What 401 means

The header was missing, malformed (no Bearer prefix), or the key has been revoked. Re-issue from /dashboard/settings.

What 402 means

The key is valid but the user is not on Premium. Upgrade at /pricing — API access activates immediately.

Reference

Every endpoint, documented.

All endpoints return JSON. Errors carry a detail field with a plain-English explanation. Pagination is automatic on the server side.

GET/api/healthBearer key

Liveness probe

Returns service status and, when ?debug=1 is passed, environment + DB connectivity diagnostics. No auth required.

Query parameters

NameTypeDescription
debugintegerPass 1 to include env-var + DB-test details.

Sample response · 200 OK

{
  "status": "ok",
  "service": "dipsern-api"
}
GET/api/assetsBearer key

List active assets

Returns every active ticker in the catalog, optionally filtered by category. Use the returned tickers in any /api/analysis call.

Query parameters

NameTypeDescription
categorystringFilter by one of: US Stocks · ETFs · BMV · Crypto · Commodities · Forex · Indices · UK/European/Japanese/Canadian/Brazilian/HK·China/Indian/Australian/Korean Stocks · CS2 Cases.

Sample response · 200 OK

{
  "assets": [
    { "ticker": "AAPL", "name": "Apple Inc.", "category": "US Stocks" },
    { "ticker": "MSFT", "name": "Microsoft", "category": "US Stocks" }
  ],
  "total": 492
}
GET/api/analysis/{ticker}Bearer key

Full Dipsern analysis

Runs the full pipeline: drawdown segmentation, forward metric, rolling median, prediction error, segment paths, and grade. Served from cache for default parameters; falls back to live computation for custom params.

Query parameters

NameTypeDescription
return_periodintegerForecast horizon in calendar days. Default 90.
num_segmentsinteger# of equal-width drawdown buckets. Default 20.
decay_factornumberEMA decay (secondary reference only). Default 0.95.
metricenumreturn | sharpe | sortino. Default return.
start_datedateYYYY-MM-DD lower bound for the historical window.
end_datedateYYYY-MM-DD upper bound for the historical window.

Sample response · 200 OK

{
  "ticker": "AAPL",
  "current_state": {
    "price": 187.42,
    "drawdown": -0.18,
    "segment": 16,
    "median_return": 12.1,
    "median_error": 8.3,
    "confirmed_count": 64
  },
  "signals": { "median_return": 12.1, "median_error": 8.3 },
  "segments": [ /* 20 rows */ ],
  "time_series": { /* dense arrays */ }
}
GET/api/analysis/{ticker}/verdictBearer key

Verdict-only (Layer 1) projection

Lightweight slice of the full analysis: current_state + signals + active_segment + grade + metadata only. Returns in <150ms from cache. Use this when you only need the grade letter and headline stats.

Query parameters

NameTypeDescription
return_periodintegerSame parameter set as /api/analysis/{ticker}.

Sample response · 200 OK

{
  "ticker": "AAPL",
  "current_state": { "drawdown": -0.18, "median_return": 12.1 },
  "grade": { "letter": "A", "score": 46.2 },
  "typical_max_drawdown": -0.58,
  "metadata": { "from_cache": true, "data_points": 11042 }
}
GET/api/asset-info/{ticker}Bearer key

Asset metadata + logo

Returns yfinance / CoinGecko / Steam metadata: long name, sector, industry, summary, logo URL, market cap, exchange, currency. Cached server-side for 7 days.

Sample response · 200 OK

{
  "ticker": "AAPL",
  "long_name": "Apple Inc.",
  "sector": "Technology",
  "industry": "Consumer Electronics",
  "logo_url": "https://logo.clearbit.com/apple.com",
  "market_cap": 3420000000000,
  "from_cache": true
}
GET/api/rankingBearer key

Ranked list of assets

Returns all assets in a category sorted by the selected metric. Served from the pre-computed ranking cache for any standard parameter combo (5 return periods × 3 metrics).

Query parameters

NameTypeDescription
categorystringSingle category filter.
categoriesstringComma-separated list (takes priority over category).
sort_byenummedian_return | win_rate | prediction_error | current_drawdown | current_price.
sortenumasc | desc. Default desc.
limitintegerMax results. Default 50.
metricenumreturn | sharpe | sortino. Default return.
return_periodintegerOne of 7, 30, 90, 180, 365.

Sample response · 200 OK

{
  "ranked_assets": [
    { "rank": 1, "ticker": "NVDA", "median_return": 28.4, "win_rate": 0.72, "score": 58.1 },
    { "rank": 2, "ticker": "AAPL", "median_return": 12.1, "win_rate": 0.64, "score": 46.2 }
  ],
  "metadata": { "filtered_assets": 492, "calculated_at": "2026-05-23T05:00:00Z" }
}
POST/api/backtestBearer key

Portfolio backtest

Runs one of three portfolio strategies (Top-N Rotation, Z-Score Timing, Long/Short) and returns the equity curve, every trade, full metrics, and benchmark series. Counts as 5 API requests for rate-limit purposes.

Request body

{
  "strategy": "topn",
  "tickers": ["AAPL", "MSFT", "NVDA"],
  "initial_capital": 100000,
  "top_n": 10,
  "rebalance": "monthly",
  "return_period": 90,
  "start_date": "2010-01-01",
  "end_date": "2024-01-01",
  "include_costs": true
}

Sample response · 200 OK

{
  "equity_curve": [{ "date": "2010-01-04", "equity": 100000 }],
  "trades": [ /* … */ ],
  "metrics": {
    "total_return": 4.82,
    "cagr": 0.137,
    "sharpe_ratio": 1.21,
    "max_drawdown": -0.34
  }
}
GET/api/keysSession cookie

List API keys

Returns every active API key for the authenticated Premium user. Requires a Supabase session cookie — not a Bearer token (you cannot manage keys with a key).

Sample response · 200 OK

[
  { "id": "uuid", "key_prefix": "dipsern_", "name": "Production", "last_used_at": "2026-05-22T08:14:00Z", "created_at": "2026-04-01T00:00:00Z" }
]
POST/api/keysSession cookie

Generate an API key

Creates a new key for the authenticated Premium user. The full key value is returned ONCE in the response — store it immediately. Max 5 active keys per user.

Request body

{ "name": "Production" }

Sample response · 200 OK

{
  "key": "dipsern_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "dipsern_",
  "name": "Production"
}
DELETE/api/keysSession cookie

Revoke an API key

Soft-revokes a key by setting is_active=false. Existing requests in flight are unaffected; the next call with that key returns 401.

Request body

{ "id": "uuid-of-the-key" }

Sample response · 200 OK

{ "ok": true }
POST/api/match-tickersSession cookie

AI ticker matcher

Resolves free-form text (brand name, partial ticker, description) to up to three active tickers via Claude Haiku 4.5 with a prompt-cached asset catalog. Used in the onboarding flow and any UI that takes natural-language ticker input.

Request body

{ "text": "the chip company that makes AI GPUs" }

Sample response · 200 OK

{
  "matches": [
    { "ticker": "NVDA", "name": "Nvidia", "category": "US Stocks", "confidence": 0.97 },
    { "ticker": "AMD",  "name": "Advanced Micro Devices", "category": "US Stocks", "confidence": 0.62 }
  ]
}
Errors

HTTP errors, decoded.

Every non-200 response carries a JSON body of the form { "detail": "…" }. Match on the status code, not the message.

CodeStatusMeaning
400Bad RequestMalformed body, invalid query param, or unknown category.
401UnauthorizedMissing, malformed, or revoked Bearer token.
402Payment RequiredValid key but the user is not on the Premium tier.
404Not FoundUnknown ticker, or asset is inactive.
422UnprocessableInsufficient price history (<300 rows) for the requested asset.
429Rate LimitedPer-minute or per-hour quota exceeded. Honor Retry-After.
500Server ErrorUnhandled exception. The detail field carries the cause.
Rate limits

Generous limits, honest headers.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 carries Retry-After.

TierPer minutePer dayNotes
Free / Lite / Pro——API access is Premium-tier only.
Premium601,000/api/backtest counts as 5 requests.

Need higher limits? Email support@dipsern.com with your use case.

Get started

Ship your first integration today.

Premium includes unlimited dashboard usage, all features, and the API. Cancel anytime.

Get an API keySee pricing

For informational purposes only. Not financial advice. Past performance does not guarantee future results.