Skip to main content
POST
/
api
/
signals
/
search
Create 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>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending"
}
CLI: 
puffle signal search create --query <query>
puffle signal search create --query <query> --filter-prompt <filter-prompt>

​
Overview

Starts a freeform search across every enabled datasource for the workspace (LinkedIn posts, Reddit, news, jobs, and more). Returns a searchId immediately with status: "pending". The flow is asynchronous: poll Get Searches with ids={searchId} until the search is completed or failed. Results stream in per source, so polling during the running state returns partial rows the UI can render incrementally.

​
Body

  • query (string, required, 1–500 chars) — the freeform search text.
  • filterPrompt (string, optional, up to 1000 chars) — an LLM relevance instruction applied server-side as raw results arrive.
See also: Get Searches · Agent Playbook.

​
AI agent notes

The signal-search journey:
  1. Ask the human for a query and optional filterPrompt.
  2. POST /api/signals/search with { query, filterPrompt? }.
  3. GET /api/signals/search?ids={searchId} — poll every 5 to 10 s.
  4. When status === "completed", inspect results[] on the polled row.
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".To change the filter, start a new search. There is no PATCH on this resource — re-filtering is intentionally not supported.

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
Required string length: 1 - 500
​
filterPrompt
string
Maximum string length: 1000

Response

Search created.

​
id
string<uuid>
required
​
status
enum<string>
required
Available options:
pending