Docs/API Reference/POST /v1/search

POST /v1/search

Keyword or semantic (hybrid dense + sparse) search over your org's Dataset.

Request

Send a JSON body with Content-Type: application/json. Only q is required.

curl -X POST https://api.prowlo.com/v1/search \
  --header "Authorization: Bearer prowlo_your_key" \
  --header "Content-Type: application/json" \
  --data '{"q":"reddit monitoring","mode":"semantic","limit":10}'

Search modes

keyword (default) is a case-insensitive substring match over title and body — no embeddings needed. semantic fuses vector similarity with full-text ranking (RRF) to surface the most relevant records.

Semantic unavailable?

If embeddings aren’t configured, semantic mode returns 503 SEMANTIC_UNAVAILABLE. Fall back to mode: "keyword".

Parameters

Parameter	Type	Default	Description
q *	string	—	The search query.
mode	keyword \| semantic	keyword	keyword = ILIKE over title/body. semantic = hybrid vector + full-text with RRF fusion.
subreddits	string[]	—	Filter to one or more channel names (case-insensitive), e.g. SaaS,webdev.
platforms	string[]	—	Filter by platform. Currently reddit or hackernews.
tags	string[]	—	Filter by org-assigned record tags (applies to matched records).
watcher_id	string	—	Restrict to records from one specific Watcher (must belong to your org). An unknown id returns an empty result.
min_score	number	—	Minimum post score (net upvotes).
min_comments	number	—	Minimum comment count.
has_link	boolean	—	When true, only posts with an external link URL.
has_image	boolean	—	When true, only posts with an image URL (heuristic on the link).
from	string	—	Only records created on or after this ISO 8601 date.
to	string	—	Only records created on or before this ISO 8601 date.
limit	number	20	Results per page. Max 100.
cursor	string	—	Opaque cursor from a previous response’s nextCursor. Treat as opaque.
include	string[]	—	Each term must appear in title or body (AND).
exclude	string[]	—	None of these terms may appear in title or body.

Try itPOST /v1/search

q *The search query.modekeyword = ILIKE over title/body. semantic = hybrid vector + full-text with RRF fusion.subredditsFilter to one or more channel names (case-insensitive), e.g. SaaS,webdev.platformsFilter by platform. Currently reddit or hackernews.tagsFilter by org-assigned record tags (applies to matched records).watcher_idRestrict to records from one specific Watcher (must belong to your org). An unknown id returns an empty result.min_scoreMinimum post score (net upvotes).min_commentsMinimum comment count.has_linkWhen true, only posts with an external link URL.has_imageWhen true, only posts with an image URL (heuristic on the link).fromOnly records created on or after this ISO 8601 date.toOnly records created on or before this ISO 8601 date.limitResults per page. Max 100.cursorOpaque cursor from a previous response’s nextCursor. Treat as opaque.includeEach term must appear in title or body (AND).excludeNone of these terms may appear in title or body.

curl -X POST https://api.prowlo.com/v1/search \
  --header "Authorization: Bearer $PROWLO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

Run uses your browser session against /api/v1/search with your key — identical parameters, just a same-origin host instead of api.prowlo.com.

Responsesample response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "rec_01HXYZ123456",
        "platform": "reddit",
        "redditId": "1abc2de",
        "subreddit": "SaaS",
        "title": "Looking for a Reddit monitoring tool for our startup",
        "permalink": "https://www.reddit.com/r/SaaS/comments/1abc2de/looking_for_a_reddit_monitoring_tool/",
        "url": null,
        "score": 47,
        "numComments": 23,
        "redditCreatedAt": "2026-06-12T14:22:08.000Z",
        "author": "founder_pete",
        "hasLink": false,
        "tags": [],
        "matched": false,
        "intent": "BUYING",
        "snippet": "We've been trying to find conversations about our space on Reddit but it's taking hours manually. Anyone know of a tool that…",
        "relevance": 0.924
      }
    ],
    "nextCursor": "20",
    "mode": "semantic",
    "tier": "quick",
    "embeddedCount": 1842,
    "channels": [
      "SaaS",
      "startups",
      "webdev"
    ]
  }
}

Response

Same record shape as /v1/records, plus search metadata. In semantic mode each item carries a relevance score (0–1) and a snippet; the envelope adds mode, tier, embeddedCount, and channels.

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "rec_01HXYZ123456",
        "platform": "reddit",
        "redditId": "1abc2de",
        "subreddit": "SaaS",
        "title": "Looking for a Reddit monitoring tool for our startup",
        "permalink": "https://www.reddit.com/r/SaaS/comments/1abc2de/looking_for_a_reddit_monitoring_tool/",
        "url": null,
        "score": 47,
        "numComments": 23,
        "redditCreatedAt": "2026-06-12T14:22:08.000Z",
        "author": "founder_pete",
        "hasLink": false,
        "tags": [],
        "matched": false,
        "intent": "BUYING",
        "snippet": "We've been trying to find conversations about our space on Reddit but it's taking hours manually. Anyone know of a tool that…",
        "relevance": 0.924
      }
    ],
    "nextCursor": "20",
    "mode": "semantic",
    "tier": "quick",
    "embeddedCount": 1842,
    "channels": [
      "SaaS",
      "startups",
      "webdev"
    ]
  }
}

Pagination: both keyword and semantic search return a nextCursor — pass it as cursor for the next page (null on the last page).

← GET /v1/records API Reference →