---
title: "Search story clusters"
method: GET
path: "/api/stories/search"
---

# Search story clusters

`GET /api/stories/search`

## Request

- Base URL: `https://techsnif.com`
- URL: `https://techsnif.com/api/stories/search`
- Auth: none declared

Relevance-ranked full-text search over headlines and excerpts, with substring fallback for word prefixes. Set mode=semantic to rank by embedding cosine similarity instead, which matches paraphrases and related concepts.

## Query parameters

- `q` string, required
- `mode` 'keyword' | 'semantic'
- `limit` integer
- `offset` integer
- `publisher` string

## Response `200`

Search results. The response includes a mode field (keyword or semantic) reflecting the search that actually ran.

- StoryListResponse
  - `stories` StoryCluster[]
    - `id` string
    - `slug` string
    - `headline` string
    - `excerpt` string
    - `whyItMatters` string: AI-generated 2-3 sentence context blurb (top stories only)
    - `topics` string[]
    - `rank` integer
    - `headlineTier` integer: 1=standard, 2=major, 3=top story
    - `leadUrl` string, uri
    - `leadTitle` string
    - `sourcePublisher` string
    - `sourceAuthor` string
    - `imageUrl` string, uri
    - `publishedAt` string, date-time
    - `firstSeenAt` string, date-time
    - `lastSeenAt` string, date-time
    - `xPostUrl` string, uri
    - `links` object[]
      - `id` string
      - `title` string
      - `url` string, uri
      - `publisher` string
      - `author` string
      - `linkType` 'lead' | 'sub' | 'more' | 'related'
      - `position` integer
    - `commentaryLinks` object[]
      - `id` string
      - `platform` string
      - `label` string
      - `url` string, uri
      - `position` integer
    - `techsnifArticle` object
      - `slug` string
      - `title` string
      - `publishedAt` string, date-time
  - `total` integer: Total matching clusters (for pagination)
  - `limit` integer
  - `offset` integer

## Other responses

- `400`: Invalid request parameters

---

[API](https://skmtc.dev/techsnif/apis/techsnif-api.md) · [All operations](https://skmtc.dev/techsnif/apis/techsnif-api/llms.txt) · [OpenAPI document](https://skmtc.dev/techsnif/apis/techsnif-api/revisions/7404c46acbb0?raw)