Skip to main content
POST
/
api
/
signals
/
search
Start a signal search
curl --request POST \
  --url https://app.puffle.ai/api/signals/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "filterPrompt": "<string>"
}
'
{
  "searchId": "aa111111-1111-1111-1111-111111111111",
  "status": "pending"
}

​
Overview

Creates a new signal_searches row and enqueues the signalSearch Trigger.dev orchestrator, which fans out across every enabled datasource adapter (LinkedIn posts, Reddit, news, SEC filings, G2/Capterra, Hacker News, X, Bluesky, web mentions). The response is immediate (201 with a searchId); poll getSignalSearch for progress.

​
Body

  • query (string, required, 1-500 chars) — the freeform search text dispatched to every adapter.
  • filterPrompt (string, optional, up to 1000 chars) — an LLM relevance instruction applied server-side once raw results arrive.
The same path also supports GET (list prior searches — listSignalSearches) and DELETE (clear all search history — clearSignalSearchHistory). Both are documented in the OpenAPI spec under the same path; this page covers the creation flow.

​
AI agent notes

Concurrency guard. Only one pending or running search younger than 10 minutes is allowed per user. Concurrent starts return 409 with A search is already in progress. Wait for the active search to complete (poll getSignalSearch) before starting another.Lifecycle. pending then running then completed (or failed). Results stream in per-source, so polling getSignalSearch during a running state returns partial rows — the UI can render them incrementally.Chained call. On a 201 response, pass the returned searchId to getSignalSearch to poll results.Retry safety. If the Trigger.dev dispatch fails, the server rolls back the signal_searches row so the caller can retry without leaving orphan records.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
query
string
required

Freeform search text, 1-500 chars. Dispatched to every enabled adapter.

Required string length: 1 - 500
​
filterPrompt
string

Optional LLM relevance filter instruction, up to 1000 chars. Applied server-side after results are fetched.

Maximum string length: 1000

Response

Search created and Trigger.dev task dispatched.

​
searchId
string<uuid>
required
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
​
status
enum<string>
required

Lifecycle state of a signal search. pending = created, task not yet started. running = Trigger.dev task in flight. completed = all sources scanned (results may still be filtered). failed = orchestrator errored.

Available options:
pending,
running,
completed,
failed