--- name: dripstack-substack-api description: Use to help a user browse our indexed Substack catalog by topic, pick a publication, and purchase a specific article. Paid posts are gated by x402/MPP micropayments. homepage: https://dripstack.xyz metadata: version: 1 --- # DripStack API ## When to use - user asks about a topic and wants reading recommendations from our catalog - user names a Substack publication or shares a Substack URL - user shares a direct article link they want to read ## Base URL `https://dripstack.xyz` — OpenAPI spec at `https://dripstack.xyz/openapi.json` ## 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/publications` Lists every publication indexed in our database, each with `slug`, `title`, `description`, `siteUrl`, and `lastSyncedAt`. The descriptions are the canonical discovery surface — reason over them to match user topics. Topic clusters in the catalog typically include finance, crypto, AI, tech, business/strategy, geopolitics, and culture. ### `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 full post metadata and `contentHtml`. `404` if not found, `402` if payment is required. ### Browser import `GET /import/{substackUrl}` — e.g. `https://dripstack.xyz/import/https://marcgmbh.substack.com` ## Payment Paid post routes return `402`. Use an x402 or MPP payment-aware client (not plain `curl`). Default price is `0.05 USD` unless overridden per-post. Always fetch the publication catalog first to get a valid `post.slug`. ## Interaction Model This skill is a **guided browse**, not open research. The agent never answers a topic question by fetching and synthesizing across multiple paid posts. Instead it walks the user through three checkpoints: 1. **Topic** — what subject area do you want to explore? Ask this first; do not list any publications yet 2. **Publication** — given the topic, which indexed publication (filtered to topic matches only — never the full catalog) do you want to dig into? 3. **Article** — which specific recent post in that publication do you want to purchase? The user (not the agent) chooses at each checkpoint. The agent only purchases an article after the user has explicitly picked it. ## Flows ### Flow A — Topic browse (default entry point) Use when the user does not yet name a publication or article. 1. **Ask for the topic first.** If the user has not stated one, ask which topic they'd like to explore. List the available topic clusters as a short, plain comma-separated line (finance, crypto, AI, tech, business, geopolitics, culture) — not a bulleted breakdown with descriptions. Keep the prompt to one or two sentences. Do not list publications yet, and do not fetch anything until the user names a topic 2. **Match.** Once the user names a topic, call `GET /api/v1/publications` and pick up to 5 publications whose `title`/`description` most directly cover that topic. Present only those matches with a one-line summary each (drawn from the publication's `description`) and ask the user which one they'd like to explore. **Never present the full publication list — only topic-matched results.** If nothing in the catalog matches, tell the user plainly that no indexed publication covers that topic and suggest a focused refinement — do not answer from model knowledge 3. **Publication detail.** Once the user picks a publication, call `GET /api/v1/publications/{publicationSlug}` and present: - a short summary of the publication (title + description) - 3-5 recent post titles (with `subtitle` when present); prefer most recent first Ask the user which post they'd like to purchase. Do not auto-select 4. **Purchase.** Once the user picks a post, call `GET /api/v1/publications/{publicationSlug}/{postSlug}` with an x402 or MPP payment-aware client and apply the response contract below ### Flow B — Specific publication Use when the user names a publication or shares a Substack URL. Skip step 1-2 of Flow A and start at step 3 (publication detail). If a single publication clearly matches the user's wording, proceed without asking them to confirm the hostname. ### Flow C — 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. **One article per response.** This skill purchases a single article at a time — never bundle multiple paid fetches into one synthesis. **Default output**: a rich curated summary of the fetched article — synthesis, notable claims, caveats, implications. 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. **Reference line** (append at the end): ``` Source: {Title} — {Publication}, {date if available} — {URL if available} ``` **Freshness**: include the publication date in the reference line when available. **Images**: include image links only when the URLs come from the fetched article `contentHtml`. **Failure**: if the paid fetch fails, surface the failure rather than substituting model knowledge. Verify the `post.slug` came from the publication response. ## 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 topic before calling `/api/v1/publications`; never enumerate the full catalog and never guess a slug - Only present publications that match the user's stated topic — never list the entire catalog - Fetch a publication catalog before attempting a paid post - Never purchase an article the user has not explicitly chosen - Never paid-fetch more than one article in a single response - If no indexed publication summary matches the user's topic, say so plainly and stop — do not fall back to model knowledge to answer the question ## Examples ```bash # Discovery — list indexed publications curl https://dripstack.xyz/api/v1/publications # Publication catalog (imports on demand if not stored) curl https://dripstack.xyz/api/v1/publications/bytesbeyondborders.substack.com # Paid post — requires x402/MPP client, only after the user picks the post # GET https://dripstack.xyz/api/v1/publications/bytesbeyondborders.substack.com/{postSlug} ```