{"schema_version":"v1","name_for_human":"Deep Values API","name_for_model":"deep_values","description_for_human":"Grounded, sourced value-investing intelligence for US public companies: curated 60-guru 13F tracking, AI multi-analyst research, intrinsic-value models, sentiment, filings, and a drop-in LLM-grounding context block.","description_for_model":"Read-only financial-intelligence API for US equities. The standout tool is ai-context, which joins company overview + fundamentals + 13F moves + SEC filings + sentiment + Deep Values AI stance into one paste-ready system prompt + structured context block for grounding an LLM about a ticker. An agent onboards itself: POST /api/v1/keys mints a key with no account, and a 402 carries a payable checkout link. JSON responses, RFC 7807 errors.","service":{"origin":"https://app.deepvalues.ai","base_url":"https://app.deepvalues.ai/api/v1","openapi_url":"https://app.deepvalues.ai/api/v1/openapi.json","docs_url":"https://app.deepvalues.ai/developers","llms_txt_url":"https://app.deepvalues.ai/llms.txt","mcp_manifest_url":"https://app.deepvalues.ai/.well-known/mcp.json","contact_email":"team@deepvalues.ai","legal_info_url":"https://app.deepvalues.ai/terms"},"onboarding":[{"step":1,"id":"try","title":"Try it with no key","body":["19 read endpoints answer without any Authorization header, up to 25 calls per IP per day (`ai-context`: 1/day). Watch `X-RateLimit-Remaining`; the `Link: …; rel=\"register\"` header points at step 2.","Keyless endpoints: `ai-context`, `intrinsic-value`, `smart-money-holdings`, `smart-money-changes`, `guru-moves`, `verdict`, `mirror-brief`, `gurus`, `guru`, `guru-portfolio`, `theses`, `indicators-buffett`, `indicators-shiller-pe`, `sentiment`, `news`, `companies-search`, `company-overview`, `fundamentals`, `filings`. /research is never keyless."],"curl":"curl -s \"https://app.deepvalues.ai/api/v1/fundamentals/AAPL\""},{"step":2,"id":"key","title":"Get a key","body":["One unauthenticated POST. No account, no browser, no human.","`{}` → a `dv_sk_test_` sandbox key: real data, never billed, 100 metadata calls/day per address, no /research.","`{\"email\":\"…\"}` → a `dv_sk_live_` key on a new prepaid account. The first key for an email carries 1 starter credit ($1); at most 3 starter grants and 10 keys per IP per day.","The raw key is shown once and is the only credential — the email is a contact label, not a login. POST again WITH the key as bearer to mint a sibling (rotation); GET https://app.deepvalues.ai/api/v1/keys/me for balance + quota; DELETE it to revoke."],"curl":"curl -s -X POST \"https://app.deepvalues.ai/api/v1/keys\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"agent@example.com\"}'"},{"step":3,"id":"prices","title":"Prices","body":["1 credit = $1.00. Prices are per successful call and often fractional — parse them as decimals: 0.001 credits ($0.001) × 8 endpoints; 0.005 credits ($0.005) × 11 endpoints; 3 credits ($3) × 1 endpoint. Everything else is free.","A call is charged only after it returns 2xx; errors are never billed. The per-endpoint price is `price_credits` in https://app.deepvalues.ai/.well-known/agent.json and in the list below. Human-readable: https://app.deepvalues.ai/en/pricing. The call below returns your exact `balanceMicro`."],"curl":"curl -s \"https://app.deepvalues.ai/api/v1/keys/me\" -H \"Authorization: Bearer $DV_API_KEY\""},{"step":4,"id":"payment","title":"Payment","body":["When the balance cannot cover a call you get HTTP 402 (RFC 7807 problem+json) with `price_credits`, `balance_micro` and a `topUp` object. Nothing was charged.","`topUp.checkoutUrl` is a ready-to-pay Stripe Checkout link for the smallest pack (null if Stripe could not be reached — then POST `topUp.checkoutEndpoint`). Packs: \"1000\" = 10 credits, \"5000\" = 50 credits, \"20000\" = 200 credits. The POST below returns `{ \"checkoutUrl\": \"https://checkout.stripe.com/…\" }`. Credits land on the key’s balance when Stripe confirms; poll keys/me, then retry.","x402 (USDC, pay-in-the-retry) is not switched on yet: the 402 body says so and carries no `accepts`."],"curl":"curl -s -X POST \"https://app.deepvalues.ai/api/v1/credits/checkout\" \\\n  -H \"Authorization: Bearer $DV_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"pack\":\"1000\"}'"},{"step":5,"id":"quotas","title":"Quotas","body":["Daily buckets per live key, reset 00:00 UTC: `metadata` 10,000, `ai_research` 50, `webhook_events` 1,000. Over quota → HTTP 429 (RFC 7807) with `retry_after_seconds`.","Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Bucket`."]}],"auth":{"type":"api_key","scheme":"http_bearer","header":"Authorization","format":"Bearer dv_sk_{live|test}_{32-char-base62}","obtain_key":{"method":"POST","url":"https://app.deepvalues.ai/api/v1/keys","auth":"none","sandbox_body":{},"live_body":{"email":"agent@example.com","label":"optional"},"starter_credits":1,"per_ip_daily_limit":10},"obtain_key_url":"https://app.deepvalues.ai/api/v1/keys","introspect_url":"https://app.deepvalues.ai/api/v1/keys/me","dashboard_url":"https://app.deepvalues.ai/account/api-keys","note":"POST https://app.deepvalues.ai/api/v1/keys needs no account, session or browser. {} returns a dv_sk_test_ sandbox key: real data, never billed, held to a small daily quota, no /research. {\"email\":\"…\"} returns a dv_sk_live_ key on a new prepaid account; the first key for an email carries 1 starter credit. Live keys debit that balance by each endpoint’s `price_credits` per successful call. The email is a contact label, not a login: keep the key, it is the only credential. People can also mint keys from the dashboard."},"pricing":{"model":"metered_pay_per_call","unit":"credit","unit_name":"credit","usd_per_credit":1,"note":"Each endpoint advertises a `price_credits`. One credit is one US dollar, and prices MAY BE FRACTIONAL — most read endpoints cost 0.001 or 0.005 credits — so parse it as a decimal, never as an integer. When metered billing is active, a successful call debits the key owner’s credit balance by that amount (free credits drained before paid). A call that cannot be covered returns HTTP 402 (RFC 7807 problem+json) with a `topUp` object the agent can act on: `checkoutUrl` (a ready Stripe Checkout link) and `checkoutEndpoint` (POST it for any pack). No data is returned and nothing is charged. Endpoints priced at 0 credits are always free. Read the exact balance from `balanceMicro` at balance_url (integer micro-credits, 1 credit = 1,000,000).","balance_url":"https://app.deepvalues.ai/api/v1/keys/me","top_up_url":"https://app.deepvalues.ai/api/v1/credits/checkout","top_up":{"method":"POST","url":"https://app.deepvalues.ai/api/v1/credits/checkout","body":{"pack":"1000"}},"packs":[{"pack":"1000","credits":10},{"pack":"5000","credits":50},{"pack":"20000","credits":200}],"pricing_page_url":"https://app.deepvalues.ai/en/pricing","payment_docs_url":"https://app.deepvalues.ai/llms.txt#payment","rails":{"api_key_credits":{"auth":"dv_sk_* bearer key","settle":"debits the key owner’s credit balance"},"x402":{"enabled":false,"protocol":"x402","version":1,"scheme":"exact","asset":"USDC","flow":"Call a priced endpoint with no Authorization header → HTTP 402 { x402Version, accepts:[{ maxAmountRequired, payTo, asset, network }] } → sign a USDC transferWithAuthorization, base64 it into X-PAYMENT, retry → 200 with the JSON + an X-PAYMENT-RESPONSE settlement receipt. No delivery, no charge: settlement only fires on a 2xx result."}}},"rate_limits":{"model":"daily_quota_buckets","reset":"00:00 UTC","buckets":[{"bucket":"metadata","daily_limit":10000,"note":"Most read endpoints; ai-context bills 3 units."},{"bucket":"ai_research","daily_limit":50,"note":"The /research briefing endpoint only."},{"bucket":"webhook_events","daily_limit":1000,"note":"Outbound webhook deliveries + test deliveries."}],"note":"Enforcement is server-side. Exceeding a bucket returns HTTP 429 with an RFC 7807 body; clients should branch on the `type` field, not parse `detail`."},"endpoints":[{"name":"keys-create","method":"POST","url":"https://app.deepvalues.ai/api/v1/keys","summary":"Mint an API key — no account, session or browser needed","returns":"The one endpoint that needs no key. Send {} for a dv_sk_test_ sandbox key (real data, small daily quota, never billed, no /research). Send {\"email\":\"…\"} for a dv_sk_live_ key on a new prepaid account; the first key for an email carries 1 starter credit ($1.00). Send it with an existing key as the bearer to mint a sibling key on the same account (rotation). The raw key is returned once. The email is a contact label, not a credential.","billing_bucket":"metadata","quota_weight":0,"value_tier":"commodity","price_credits":0,"auth":"none","doc_url":"https://app.deepvalues.ai/llms/keys-create.md"},{"name":"keys-me","method":"GET","url":"https://app.deepvalues.ai/api/v1/keys/me","summary":"This key: exact credit balance, remaining quota, environment","returns":"Returns the calling key, the exact balance of the ledger behind it (balanceMicro: integer micro-credits, 1 credit = $1.00 = 1,000,000), what is left in each daily quota bucket, and the environment. Free, and consumes no quota.","billing_bucket":"metadata","quota_weight":0,"value_tier":"commodity","price_credits":0,"auth":"bearer","doc_url":"https://app.deepvalues.ai/llms/keys-me.md"},{"name":"credits-packs","method":"GET","url":"https://app.deepvalues.ai/api/v1/credits/checkout","summary":"Credit packs on sale","returns":"Lists the prepaid credit packs this key can buy (1 credit = $1.00). Free.","billing_bucket":"metadata","quota_weight":0,"value_tier":"commodity","price_credits":0,"auth":"bearer","doc_url":"https://app.deepvalues.ai/llms/credits-packs.md"},{"name":"credits-checkout","method":"POST","url":"https://app.deepvalues.ai/api/v1/credits/checkout","summary":"Get a Stripe Checkout URL that tops up this key’s balance","returns":"Creates a one-time Stripe Checkout Session for a credit pack, bound to the calling live key’s account. When the payment completes the credits land on that balance; poll GET /keys/me. This is what a 402 `topUp.checkoutEndpoint` points at. Free, consumes no quota.","billing_bucket":"metadata","quota_weight":0,"value_tier":"commodity","price_credits":0,"auth":"bearer","doc_url":"https://app.deepvalues.ai/llms/credits-checkout.md"},{"name":"keys-revoke","method":"DELETE","url":"https://app.deepvalues.ai/api/v1/keys/me","summary":"Revoke this key","returns":"The calling key stops authenticating immediately. Any credit balance stays on the account, reachable through its other keys.","billing_bucket":"metadata","quota_weight":0,"value_tier":"commodity","price_credits":0,"auth":"bearer","doc_url":"https://app.deepvalues.ai/llms/keys-revoke.md"},{"name":"account","method":"GET","url":"https://app.deepvalues.ai/api/v1/account","summary":"Account info + current quota usage","returns":"Returns the calling key, its scopes, environment, and today's usage across all 3 buckets. Self-billing: counts as 1 metadata call.","billing_bucket":"metadata","quota_weight":1,"value_tier":"commodity","price_credits":0,"auth":"bearer","doc_url":"https://app.deepvalues.ai/llms/account.md"},{"name":"ai-context","method":"GET","url":"https://app.deepvalues.ai/api/v1/ai-context/{ticker}","summary":"Drop-in AI grounding context (DIFFERENTIATED)","returns":"Returns a system prompt + structured context block, scoped to one ticker. Drop it into OpenAI/Anthropic/any LLM SDK to ground your chatbot in current Deep Values data without months of plumbing. Bills 3 metadata units.","billing_bucket":"metadata","quota_weight":3,"value_tier":"premium","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":1,"doc_url":"https://app.deepvalues.ai/llms/ai-context.md"},{"name":"research","method":"GET","url":"https://app.deepvalues.ai/api/v1/research/{ticker}","summary":"AI multi-analyst research briefing (HEADLINE)","returns":"The differentiated endpoint: full briefing, bull case, bear case, valuation, investment plan, fair-value range. Bills against your ai_research quota (50/day at $99/mo, $0.10 overage). Currently returns cached results only; fresh-trigger via API arriving next release.","billing_bucket":"ai_research","quota_weight":1,"value_tier":"premium","price_credits":3,"auth":"bearer","doc_url":"https://app.deepvalues.ai/llms/research.md"},{"name":"intrinsic-value","method":"GET","url":"https://app.deepvalues.ai/api/v1/intrinsic-value/{ticker}","summary":"DCF + Owner Earnings + Damodaran intrinsic value","returns":"DCF + Owner Earnings + Damodaran intrinsic value","billing_bucket":"metadata","quota_weight":1,"value_tier":"mid","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/intrinsic-value.md"},{"name":"smart-money-holdings","method":"GET","url":"https://app.deepvalues.ai/api/v1/smart-money/holdings","summary":"Which curated gurus hold this ticker","returns":"Returns every guru from our 60-name roster who held the requested ticker as of the latest 13F-HR quarter (or a specific historical quarter). Each row includes shares, USD value, % of portfolio, and the auto-classified delta vs the prior quarter.","billing_bucket":"metadata","quota_weight":1,"value_tier":"mid","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/smart-money-holdings.md"},{"name":"smart-money-changes","method":"GET","url":"https://app.deepvalues.ai/api/v1/smart-money/changes","summary":"Material guru moves in a time window","returns":"All 13F position changes meeting the materiality threshold (new positions, full exits, ≥25% share-count shifts, OR ≥$100M position size) across our entire 60-guru roster, in the requested window.","billing_bucket":"metadata","quota_weight":1,"value_tier":"mid","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/smart-money-changes.md"},{"name":"guru-moves","method":"GET","url":"https://app.deepvalues.ai/api/v1/gurus/moves","summary":"Material guru moves, newest filing first, each with its verdict","returns":"The Follow the Pros feed. Every material 13F move — new position, full exit, a share count that moved by 25%, or a position of $100M or more — ordered by the date the filing became public, with a deterministic verdict line on each row. The verdict is identical for every caller: it compares the price when the investor traded, the price now and Deep Values' intrinsic value band, and it never predicts a return or recommends an action. Every row carries the company's legal name beside the ticker (`name`, e.g. \"Occidental Petroleum\"), or null where we hold none — null rather than the ticker echoed back, so a caller can tell a real name from a placeholder. Rows whose EDGAR filing date we do not yet hold fall back to when the row reached us and say so with filed_at_known: false.","billing_bucket":"metadata","quota_weight":1,"value_tier":"premium","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/guru-moves.md"},{"name":"verdict","method":"GET","url":"https://app.deepvalues.ai/api/v1/verdict/{ticker}","summary":"The verdict line for one filed move","returns":"One guru's disclosed move in one ticker, with the sentence Deep Values publishes about it and every number behind it: the company's legal name beside the ticker (`name`, null where we hold none), the three dates (traded by, filed, seen), the quarter-end close, the current price, and the intrinsic value band. `value` is the callable band (the blend ±25%) and is null whenever the verdict is not a call; `estimates` always carries what the valuation methods actually said, their lowest and highest central estimate, so a reader told we cannot call it can see why. One of six deterministic states — below_value, inside_band, above_value, ran_ahead, too_uncertain, no_value — computed the same way for every caller. The band is Deep Values' blended intrinsic value plus or minus 25%, and `too_uncertain` (\"Our estimates disagree too much to call this one.\") replaces the three band states when the methods' own central estimates are more than 3x apart, or one of them is not positive: the blend still exists and is still returned in `value`, but it is not a range anyone should be told a price sits inside. It is distinct from `no_value`, which means no valuation was computed at all.","billing_bucket":"metadata","quota_weight":1,"value_tier":"premium","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/verdict.md"},{"name":"mirror-brief","method":"GET","url":"https://app.deepvalues.ai/api/v1/mirror-brief/{ticker}","summary":"An impersonal brief on one filed move, for an agent to act on","returns":"The same move as /verdict, flattened into a brief: what the investor did, when, at what price, against our value band, plus the verdict sentence. It carries NO quantity and NO instruction — `sizing` reads \"not provided; the reader decides\". It describes a public filing and a published value range; it is not advice and not a prediction.","billing_bucket":"metadata","quota_weight":1,"value_tier":"premium","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/mirror-brief.md"},{"name":"gurus","method":"GET","url":"https://app.deepvalues.ai/api/v1/gurus","summary":"Curated guru roster","returns":"60 hand-picked institutional investors — every name a serious value investor would recognize. Filter by style.","billing_bucket":"metadata","quota_weight":1,"value_tier":"mid","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/gurus.md"},{"name":"guru","method":"GET","url":"https://app.deepvalues.ai/api/v1/gurus/{slug}","summary":"One guru: bio + top holdings","returns":"One guru: bio + top holdings","billing_bucket":"metadata","quota_weight":1,"value_tier":"mid","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/guru.md"},{"name":"guru-portfolio","method":"GET","url":"https://app.deepvalues.ai/api/v1/gurus/{slug}/portfolio","summary":"One guru's full portfolio at a quarter","returns":"One guru's full portfolio at a quarter","billing_bucket":"metadata","quota_weight":1,"value_tier":"mid","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/guru-portfolio.md"},{"name":"theses","method":"GET","url":"https://app.deepvalues.ai/api/v1/theses","summary":"Structured human investment theses","returns":"Public investment theses with structured metadata — sentiment, conviction, price target, anchored DVI run. Filter by ticker, conviction, or sentiment.","billing_bucket":"metadata","quota_weight":1,"value_tier":"mid","price_credits":0.005,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/theses.md"},{"name":"indicators-buffett","method":"GET","url":"https://app.deepvalues.ai/api/v1/indicators/buffett","summary":"Buffett Indicator with zone classification","returns":"US corporate equities ÷ GDP, with zones (significantly undervalued through significantly overvalued) and historical percentile.","billing_bucket":"metadata","quota_weight":1,"value_tier":"low","price_credits":0.001,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/indicators-buffett.md"},{"name":"indicators-shiller-pe","method":"GET","url":"https://app.deepvalues.ai/api/v1/indicators/shiller-pe","summary":"Shiller PE with historical percentile","returns":"Shiller PE with historical percentile","billing_bucket":"metadata","quota_weight":1,"value_tier":"low","price_credits":0.001,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/indicators-shiller-pe.md"},{"name":"sentiment","method":"GET","url":"https://app.deepvalues.ai/api/v1/sentiment/{ticker}","summary":"Value-investor sentiment rollup (not WSB noise)","returns":"Value-investor sentiment rollup (not WSB noise)","billing_bucket":"metadata","quota_weight":1,"value_tier":"low","price_credits":0.001,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/sentiment.md"},{"name":"news","method":"GET","url":"https://app.deepvalues.ai/api/v1/news/{ticker}","summary":"Sentiment-scored news","returns":"Sentiment-scored news","billing_bucket":"metadata","quota_weight":1,"value_tier":"low","price_credits":0.001,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/news.md"},{"name":"companies-search","method":"GET","url":"https://app.deepvalues.ai/api/v1/companies","summary":"Company search","returns":"Company search","billing_bucket":"metadata","quota_weight":1,"value_tier":"commodity","price_credits":0.001,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/companies-search.md"},{"name":"company-overview","method":"GET","url":"https://app.deepvalues.ai/api/v1/companies/{ticker}/overview","summary":"Company overview","returns":"Company overview","billing_bucket":"metadata","quota_weight":1,"value_tier":"commodity","price_credits":0.001,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/company-overview.md"},{"name":"fundamentals","method":"GET","url":"https://app.deepvalues.ai/api/v1/fundamentals/{ticker}","summary":"Income + balance + cashflow","returns":"Income + balance + cashflow","billing_bucket":"metadata","quota_weight":1,"value_tier":"commodity","price_credits":0.001,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/fundamentals.md"},{"name":"filings","method":"GET","url":"https://app.deepvalues.ai/api/v1/filings/{ticker}","summary":"SEC filings (10-K, 10-Q, 8-K, etc)","returns":"SEC filings (10-K, 10-Q, 8-K, etc)","billing_bucket":"metadata","quota_weight":1,"value_tier":"commodity","price_credits":0.001,"auth":"bearer","anonymous_daily_limit":25,"doc_url":"https://app.deepvalues.ai/llms/filings.md"},{"name":"webhooks-list","method":"GET","url":"https://app.deepvalues.ai/api/v1/webhooks","summary":"List webhook subscriptions","returns":"List webhook subscriptions","billing_bucket":"metadata","quota_weight":1,"value_tier":"commodity","price_credits":0,"auth":"bearer","doc_url":"https://app.deepvalues.ai/llms/webhooks-list.md"},{"name":"webhooks-create","method":"POST","url":"https://app.deepvalues.ai/api/v1/webhooks","summary":"Create webhook subscription","returns":"Subscribe to event types. Returns a signing_secret (shown once) used to verify the X-DV-Signature header on every delivery.","billing_bucket":"metadata","quota_weight":1,"value_tier":"commodity","price_credits":0,"auth":"bearer","doc_url":"https://app.deepvalues.ai/llms/webhooks-create.md"},{"name":"webhooks-delete","method":"DELETE","url":"https://app.deepvalues.ai/api/v1/webhooks/{id}","summary":"Delete a webhook subscription","returns":"Delete a webhook subscription","billing_bucket":"metadata","quota_weight":1,"value_tier":"commodity","price_credits":0,"auth":"bearer","doc_url":"https://app.deepvalues.ai/llms/webhooks-delete.md"},{"name":"webhooks-test","method":"POST","url":"https://app.deepvalues.ai/api/v1/webhooks/{id}/test","summary":"Send a test delivery to a webhook subscription","returns":"Queues a synthetic event delivery against the named subscription so integrators can verify signing-secret rotation and end-to-end delivery without waiting for a real event. Counts against the webhook_events metered quota.","billing_bucket":"webhook_events","quota_weight":1,"value_tier":"commodity","price_credits":0,"auth":"bearer","doc_url":"https://app.deepvalues.ai/llms/webhooks-test.md"}],"disclaimer":"Deep Values sells data and analysis, not investment advice. Outputs are informational and sourced from SEC EDGAR, 13F filings, FRED, and the Deep Values multi-analyst research pipeline; they are not a recommendation to buy or sell any security.","generated_from":"openapi-3.1-spec"}