---
title: "Semantic search over events (pgvector cosine, keyword fallback)"
method: GET
path: "/api/v1/search"
---

# Semantic search over events (pgvector cosine, keyword fallback)

`GET /api/v1/search`

## Request

- Base URL: `https://heatpulse.cc`
- URL: `https://heatpulse.cc/api/v1/search`
- Auth: none declared

## Query parameters

- `q` string, required
- `limit` integer

## Response `200`

Matches; mode is 'semantic' or 'keyword'

- object
  - `q` string
  - `mode` string
  - `count` integer
  - `events` Event[]
    - `id` integer
    - `slug` string
    - `title` string
    - `summary` string: Original editorial summary (not a publisher excerpt)
    - `why_it_matters` string, nullable
    - `category` string
    - `tags` string[]
    - `heat` number: Cross-source heat score
    - `source_count` integer
    - `first_seen` string
    - `domains` string[]
    - `langs` string[]
    - `url` string: Canonical page path on heatpulse.cc

## Other responses

- `400`: Missing/invalid q, or non-integer limit
- `429`: Rate limited (60 req/min/IP, 300/min global — each call costs one embedding)

---

[API](https://skmtc.dev/heatpulse/apis/heatpulse-agent-api.md) · [All operations](https://skmtc.dev/heatpulse/apis/heatpulse-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/heatpulse/apis/heatpulse-agent-api/revisions/13aa08eaae7e?raw)