> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dripstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Topic Search

> Search indexed newsletters and podcasts by topic. Free, ranked by relevance.

`GET /api/v1/search` is the default discovery route. Use it when the question is
a **topic** ("what are writers saying about AI capex?") rather than a ticker,
person, or named publication.

Free, no auth. Results are **candidates** — ranked post cards with
`priceCents`. The `synthesizedSummary` still comes from the
[paid publication-post route](/concepts/payment-flow).

MCP: `search_posts`.

## Request

`q` is required (minimum 2 characters). Default `limit` is 10.

```bash theme={null}
curl "https://dripstack.com/api/v1/search?q=AI%20infrastructure%20spending&limit=10"
```

| Parameter | Required | Description |
| - | - | - |
| `q` | yes | Natural-language query, minimum 2 characters |
| `limit` | optional | 1-30, defaults to 10 |
| `mode` | optional | `hybrid` (default) blends lexical and semantic; `fts` is lexical only |
| `platform` | optional | `substack`, `beehiiv`, `rss`, `podcast`, `email`, or `twitter` |
| `source` | optional | `newsletter`, `podcast`, or `all`. `newsletter` covers Substack, Beehiiv, RSS, email, and Twitter |
| `publicationSlug` | optional | Restrict results to one publication |
| `publishedAfter` / `publishedBefore` | optional | `YYYY-MM-DD`, inclusive UTC calendar day bounds |

Do not combine a `platform` that conflicts with `source` (for example
`platform=podcast` with `source=newsletter`) — that returns `400`.
`publishedAfter` must not be later than `publishedBefore`.

Search starts with publications curated for chat and can fall back to other
indexed publications when the initial matches are weak. `publicationSlug`
restricts the search to that publication. Disabled publications are excluded
from returned items.

## Response

```json theme={null}
{
  "mode": "hybrid",
  "asOf": "2026-06-15T10:30:00Z",
  "query": "AI infrastructure spending",
  "normalizedQuery": "ai infrastructure spending",
  "matchConfidence": "strong",
  "searchTierUsed": "scoped",
  "timeWindow": null,
  "freshnessCoverage": null,
  "count": 1,
  "totalCount": 1,
  "items": [
    {
      "publicationSlug": "stratechery",
      "slug": "the-ai-infrastructure-boom",
      "title": "The AI Infrastructure Boom",
      "subtitle": "Why hyperscalers are spending billions on GPU clusters",
      "priceCents": 50,
      "isPodcast": false,
      "isScopedPublisher": true,
      "relevanceScore": 42,
      "matchedTokenCount": 2,
      "totalTokenCount": 3,
      "topicCoverageRatio": 0.6666666666666666,
      "snippet": "Nvidia's datacenter revenue hit $26B last quarter as hyperscalers race to build out GPU clusters...",
      "whyMatched": ["Title matches AI + infrastructure"],
      "publishedAt": "2026-06-14T12:00:00Z"
    }
  ]
}
```

`matchConfidence` is `strong`, `weak`, or `none`. Present each item as
`{title} ({publicationSlug}, YYYY-MM-DD) — $X.XX` when `priceCents` is known.
Keep `publicationSlug` + `slug` for the paid fetch.

`searchTierUsed` is `scoped` or `non_scoped`. `timeWindow` describes a date
window inferred from the query, or is `null`; `freshnessCoverage` reports
coverage of that window and whether older results were used as a fallback.
`count` is the number of returned items. `totalCount` is the number of ranked
candidates before the response limit and disabled-publication filter, not a
count of every matching article in the catalog.

`isPodcast` is true for episodes — the paid post response then includes a
`transcript` when ready.

Invalid params return `400`. Unexpected failures return `500` with
`error: "Search failed. Please retry."`, `code: "internal_error"`, and a
recovery `hint`.

## Topic search vs entity search vs company lookup

| Question | Route |
| - | - |
| What are writers saying about **this topic**? | This page — `GET /api/v1/search` |
| Articles that **mention** a ticker, company, person, org, or theme | [Entity Search](/entity-search/ticker) — recency, not relevance |
| Who **is** NVDA / nvidia.com? | [Company Lookup](/companies) — identity card, not articles |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.