Hunch

API Reference

Signals

Buying triggers written in plain English. Hunch compiles each one into detection criteria. Create, update, and delete signals, and run them on demand.

List signals

GET/signals

Returns every signal definition in the workspace, newest first.

Response
{
  "data": [
    {
      "id": "...",
      "name": "New Revenue Leader",
      "plain_english": "Did the company appoint a new CRO or VP of Revenue in the last 90 days?",
      "compiled": { "...": "compiled detection criteria" },
      "priority": "medium",
      "status": "active",
      "timeframe_days": 90,
      "muted": false,
      "auto_run_cron": "true",
      "created_at": "2026-06-01T..."
    }
  ]
}

Create a signal

POST/signals

Provide a buying trigger in plain English, Hunch compiles it into detection criteria and auto-names it if you omit name.

Body fields
plain_englishstringrequired

The buying trigger, e.g. 'Company hired a new VP of Revenue in the last 90 days'.

namestringoptional

Optional label. Auto-generated if omitted.

prioritystringoptional

high, medium (default), or low.

timeframe_daysintegeroptional

Detection window. Defaults from the compiled definition.

Request
curl -X POST https://usehunch.co/api/v1/signals \
  -H "Authorization: Bearer hunch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plain_english": "Company opened a new office in EMEA", "priority": "high" }'
Compilation uses your workspace's AI model and company context. If no model key is configured the request fails with 400.

Get a signal

GET/signals/:id

Returns the signal including its compiled detection criteria.

Update a signal

PATCH/signals/:id

Changing plain_english re-compiles the signal. Other fields update in place.

plain_englishstringoptional

New trigger text. Re-compiles the detection criteria.

namestringoptional

Rename the signal.

prioritystringoptional

high, medium, or low.

timeframe_daysintegeroptional

Detection window.

mutedbooleanoptional

Mute or unmute the signal.

statusstringoptional

active or archived.

Delete a signal

DELETE/signals/:id
Response
{ "data": { "id": "...", "deleted": true } }

Run a signal

POST/signals/:id/run

Kicks off a run for the signal, net-new discovery plus a scan of your active accounts. Returns immediately with the run id, the run executes in the background. Poll GET /runs/:id for progress.

Runs consume paid research resources, so this endpoint requires an active subscription. Without one it returns 402.
Request
curl -X POST https://usehunch.co/api/v1/signals/SIGNAL_ID/run \
  -H "Authorization: Bearer hunch_YOUR_KEY"
202 Accepted
{
  "data": {
    "run_id": "...",
    "status": "running",
    "created_at": "2026-07-03T..."
  }
}
PreviousPeopleNext Runs & discovery