--- name: drip-api description: Use when a user wants to search premium financial newsletters, browse indexed publications, purchase one or more paid articles, fetch paid stock-picker calls, or synthesize selected articles. Paid posts and stock picks are gated by x402/MPP micropayments. homepage: https://dripstack.com metadata: version: 1.1 --- # Drip API ## When to use - user asks about a topic and wants article recommendations from premium financial newsletters - user wants to browse the full catalog of indexed publications before choosing one - user names a Substack publication or shares a Substack URL - user shares a direct article link they want to read - user asks for recent stock-picker calls or investment picks ## Base URL `https://dripstack.com` — OpenAPI spec at `https://dripstack.com/openapi.json` (paid post route includes MPP `x-payment-info.offers[]`; trust the live `402` challenge over discovery amounts) ## Publication Slugs Publication slugs are normalized hosts. Leading `www.` is removed for non-Substack custom domains. - `https://bytesbeyondborders.substack.com` -> `bytesbeyondborders.substack.com` - `https://www.reallygoodbusinessideas.com` -> `reallygoodbusinessideas.com` ## API Routes ### `GET /api/v1/search` Searches across all indexed articles in our database. Use this as the default discovery surface for topic browsing instead of loading the full publication catalog into memory. Query parameters: - `q` (required): natural-language search query - `limit` (optional): number of article results to return, from 1-10; use `10` by default Response includes `items[]`, ranked article candidates with `publicationSlug`, `slug`, `title`, `subtitle`, `publishedAt`, `snippet`, `whyMatched`, and relevance fields. Show user-facing search result options as `{title} ({publicationSlug}, {YYYY-MM-DD})` when `publishedAt` is present, or `{title} ({publicationSlug})` when no date is available. Convert full ISO timestamps like `2026-05-12T13:58:57.000Z` to `2026-05-12`. Use `publicationSlug` + `slug` from a selected item to purchase the article. ### `GET /api/v1/publications` Lists every publication indexed in our database, each with `slug`, `title`, `description`, `siteUrl`, and `lastSyncedAt`. Use this when the user explicitly wants to browse the entire catalog of publications and choose which one to explore. Do not use it for topic discovery when `/api/v1/search` can answer with ranked article candidates. ### `GET /api/v1/publications/{publicationSlug}` Returns publication metadata plus `posts`: an array of post summaries with `slug`, `title`, `subtitle`. The server may import on demand if not already stored. `404` if not found. ### `POST /api/v1/publications/{publicationSlug}` Imports a publication. Returns `{ postCount }`. ### `GET /api/v1/publications/{publicationSlug}/{postSlug}` (paid) Returns post metadata and `synthesizedSummary`. `404` if not found, `503` with code `summary_not_ready` when the summary is not ready (retry later; no payment), `402` if payment is required. OpenAPI `x-payment-info.offers[]` is advisory; retry using credentials that satisfy the returned challenge. ### `GET /api/v1/stock-picks` (paid) Returns extracted stock-picker calls. Defaults to the past five UTC extraction days; pass `date=YYYY-MM-DD` for one extraction date. Optional `limit` is 1-500 and defaults to 200. Use an x402 or MPP payment-aware client; plain requests return `402`. Runtime price is based on distinct attributed source articles returned, and settlement records sales for those source articles. ## Payment Paid routes return `402`. Use an x402 or MPP payment-aware client (not plain `curl`). If a plain fetch/curl returns `402`, retry the same request through the payment-aware client rather than treating it as final failure. Infer the live price from the paid endpoint response or payment challenge; do not assume a default amount. For topic search results, use the returned `publicationSlug` and `slug` directly. For direct publication browsing, fetch the publication catalog first to get a valid `post.slug`. ## Choose The Flow This skill is a **guided search and purchase flow**. At the start, the agent may offer the user two paths: ask a general question and get the top relevant articles to purchase, or browse the entire publication catalog and choose a publication to explore. The agent walks the user through three checkpoints: 1. **Query** — what should we search across premium financial newsletters? 2. **Article options** — show the top 10 ranked article matches from `/api/v1/search?q=...&limit=10` 3. **Purchase** — which article result or results does the user want to buy? The user (not the agent) chooses at each checkpoint. The agent only purchases articles after the user has explicitly picked them or clearly requested a multi-article synthesis from selected results. | User asks... | Agent should... | | --- | --- | | "What should I read about AI capex?" | Search articles with `GET /api/v1/search?q={query}&limit=10`, then show choices as `Title (publicationSlug, YYYY-MM-DD)` | | "Show all publications" | Browse the catalog with `GET /api/v1/publications` | | "Show posts from Doomberg" | Resolve the publication, call `GET /api/v1/publications/{publicationSlug}`, then show post choices | | "Read this article" | Resolve the direct article, confirm purchase if needed, then fetch the paid post | | "Compare these three" | Purchase the selected articles and synthesize across them | | "Show recent stock picks" | Fetch `GET /api/v1/stock-picks` with an x402 or MPP payment-aware client | ## Flows ### Flow A — Search articles (default entry point) Use when the user does not yet name a publication or article. 1. **Ask for the query first.** If the user has not stated one, ask what they want to search across premium financial newsletters, and mention that they can either ask a general question for article recommendations or browse the full publication catalog. Offer 2-4 short example queries from the website chat interface, such as: - `What stocks are financial analysts watching most closely this week?` - `What is Michael Burry most bearish on right now, based on his latest blog posts?` - `Summarize Citrini's current market thesis.` - `Are AI stocks in a bubble? Give me the bull and bear cases from recent finance writers.` Keep this prompt to one or two sentences. Do not list publications yet, and do not fetch anything until the user gives a query. 2. **Search.** Once the user gives a query, call `GET /api/v1/search?q={query}&limit=10`. Do not specify search mode; the endpoint defaults to hybrid search. Do not call `GET /api/v1/publications` for this flow, and do not read the full publication catalog into memory. 3. **Offer purchase options.** Present up to 10 returned `items[]` as article choices. For each option, show exactly `{title} ({publicationSlug}, {YYYY-MM-DD})` when `publishedAt` is present, or `{title} ({publicationSlug})` when no date is available. Convert `publishedAt` to date-only `YYYY-MM-DD`; do not show the full timestamp. Do not show article slugs, subtitles, snippets, relevance scores, match reasons, or other internal metadata in the user-facing options. Keep the selected item's `publicationSlug` and `slug` available for the purchase URL. Do not summarize as if the full article has been read. Ask which article or articles the user wants to purchase. 4. **Fetch selected article(s).** Once the user picks one or more results, call `GET /api/v1/publications/{publicationSlug}/{postSlug}` for each selected item using its `publicationSlug` and `slug` with an x402 or MPP payment-aware client, then apply the response contract below. ### Search result display When showing article search results to the user: | Field | User-visible? | Use | | --- | --- | --- | | `title` | Yes | Render as `{title} ({publicationSlug}, {YYYY-MM-DD})` when date is present | | `publicationSlug` | Yes | Render inside parentheses after the title | | `publishedAt` | Yes, when present | Render as date-only `YYYY-MM-DD` after `publicationSlug` | | `slug` | No | Keep internally for purchase URL | | `subtitle`, `snippet`, `whyMatched`, scores | No | Keep internal or ignore | Example user-facing search options: ``` 1. AI's $600B Question (fabricatedknowledge.com, 2026-05-10) 2. The Capex Cycle Turns (netinterest.co, 2026-05-08) 3. Chips, Margins, and the Buildout (tmtbreakout.com) ``` Search results are a menu, not an answer. Do not answer substantive questions from search metadata alone. Answer only after paid article summaries are fetched, or ask the user to select article(s) to purchase. ### Flow B — Specific publication Use when the user names a publication or shares a Substack URL. Call `GET /api/v1/publications/{publicationSlug}`, present 3-5 recent post titles, and ask which post or posts they want to purchase. If a single publication clearly matches the user's wording, proceed without asking them to confirm the hostname. ### Flow C — Browse catalog Use when the user asks to browse available publications, see the full catalog, list publications, or choose from newsletters before searching articles. 1. Call `GET /api/v1/publications` 2. Present a concise catalog view in this format: `Publication Title (slug) — short description`. If the response is long, group or trim the display while making it clear the catalog can be narrowed by topic. 3. Ask which publication they want to explore. 4. Once they choose a publication, call `GET /api/v1/publications/{publicationSlug}`, present 3-5 recent post titles, and ask which post or posts they want to purchase. 5. Once the user picks one or more posts, call `GET /api/v1/publications/{publicationSlug}/{postSlug}` for each selected post with an x402 or MPP payment-aware client and apply the response contract below. ### Flow D — Direct article URL or post slug Use when the user shares a direct Substack post URL or asks about one specific post. 1. Resolve `publicationSlug` and `postSlug` from the URL or context 2. Confirm with the user that they want to purchase this article (state title and price) before fetching, unless they have already explicitly asked to read/buy it 3. Call `GET /api/v1/publications/{publicationSlug}/{postSlug}` and apply the response contract below ## Response contract Applies whenever a paid article is fetched. **Single or multiple articles.** If the user picks one article, purchase and summarize that article. If the user picks multiple articles, or asks for a synthesis/comparison across results, purchase each selected article and synthesize across them. **Default output**: for one fetched article, return a rich curated summary — synthesis, notable claims, caveats, implications. For multiple fetched articles, return a cross-article synthesis that compares the relevant claims, tensions, mechanisms, caveats, and implications across sources. Format can vary (narrative, bullets, mini-sections); do not reuse the same template each turn. Vary section headers and opening sentences across consecutive summaries. Only emit raw/full content when the user explicitly asks for it. **References** (append at the end, one line per fetched article): ``` Source: {Title} — {Publication}, {date if available} — {URL if available} ``` **Freshness**: include the publication date in each source line when available. **Failure**: if a paid fetch fails, surface the failure rather than substituting model knowledge. On `503` `summary_not_ready`, ask the user to retry shortly. If some selected articles succeed and others fail, synthesize only from the successfully fetched articles and clearly name the failed fetches. Verify each `post.slug` came from search results or the publication response. ## Purchase guardrails - Do not purchase anything until the user selects article options or clearly requests purchase/synthesis from selected results - If the user says "buy the top N", "use the best N", or similar, treat that as explicit selection of the top N currently displayed search results - Single-article purchase is fine when one article is selected - Multi-article purchase is fine when the user selects multiple articles or asks for comparison/synthesis - Do not answer from unfetched paid content; search results can guide selection, but paid article claims must come from fetched article summaries - If search returns no useful article matches, say so plainly and ask for a focused refinement rather than answering from model knowledge ## Voice - Speak naturally to the user. Never narrate the skill, the flow, or your internal reasoning ("I'll follow Flow A", "per the skill", "I should ask you for a topic first") - Do not mention this skill by name, other tools, MCP servers, priority decisions between instructions, or what you're "ignoring" — the user does not need to see any of that - Keep prompts short. The topic question is one or two sentences, not a bulleted menu with explanations - Output only what the user needs to make the next choice ## Invariants - Prefer the OpenAPI document before guessing route shapes - Use publication and post slugs exactly as returned by the API - ALWAYS ask the user for a search query before calling `/api/v1/search`; never enumerate the full catalog for topic discovery - For topic discovery, call `/api/v1/search?q={query}&limit=10` and offer the returned articles as purchase options - Only call `/api/v1/publications` when the user directly asks to browse the catalog, asks what publications are available, or names a specific publication - Fetch a publication catalog before attempting a paid post only when the selected post did not come from `/api/v1/search` - Purchase only articles the user has explicitly chosen or clearly requested for synthesis - Multiple paid fetches are allowed when the user selects multiple articles or asks for a synthesis/comparison across selected results - Search result options shown to the user must be formatted as `Title (publicationSlug, YYYY-MM-DD)` when a date exists, otherwise `Title (publicationSlug)` ## Examples ```bash # Search indexed articles across premium financial newsletters curl "https://dripstack.com/api/v1/search?q=AI%20capex%20bubble%20and%20hyperscaler%20margins&limit=10" # Browse the full publication catalog curl https://dripstack.com/api/v1/publications # Publication catalog (selected publication flow only; imports on demand if not stored) curl https://dripstack.com/api/v1/publications/bytesbeyondborders.substack.com # Paid post — requires x402/MPP client, only after the user picks the post # GET https://dripstack.com/api/v1/publications/bytesbeyondborders.substack.com/{postSlug} ``` ## Golden interaction User: What are the best recent pieces on AI capex risk? Agent: Searches `GET /api/v1/search?q=AI%20capex%20risk&limit=10`, shows options as `Title (publicationSlug, YYYY-MM-DD)`, then buys only the selected article(s) and summarizes or synthesizes from fetched bodies.