Skip to main content
GET
/
api
/
v1
/
signals
/
types
/
{id}
Get a signal type
curl --request GET \
  --url https://app.puffle.ai/api/v1/signals/types/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "label": "<string>",
  "description": "<string>",
  "kind": "structured",
  "enabled": true,
  "keywords": [
    "<string>"
  ],
  "disqualifiers": [
    "<string>"
  ],
  "config": {},
  "config_schema": {},
  "built_in": true,
  "search_instructions": "<string>",
  "scoring_criteria": "<string>",
  "sources": [
    "news"
  ]
}

​
Overview

This page documents every method on /api/v1/signals/types/{id}:
  • GET — fetch the full signal type (prompts, keywords, disqualifiers, structured config, allowed sources)
  • PATCH — partial update. Only provided fields are applied. Built-in types reject changes to name and sources; keyword types require at least 1 keyword when enabled: true; structured types validate config against their config_schema. When sources changes, the signal_type_sources table is synced in the same call.
  • DELETE — remove a custom signal type. Built-in types (hiring, funding, management_change, competitor_mentions) return 400 — they cannot be deleted.
A related endpoint, POST /api/v1/signals/types/{id}/reset, restores search_instructions and scoring_criteria to the system defaults on a BUILT-IN type. It returns the full updated type (schema matches GET) and rejects custom types with 400.

​
AI agent notes

Built-in vs. custom — different rules.
OperationBuilt-inCustom
GETallowedallowed
PATCH name400allowed (409 on duplicate)
PATCH sources400allowed
PATCH prompts/keywords/config/enabledallowedallowed
DELETE400allowed (irreversible)
reset promptsallowed400
Poll after generate. POST /api/v1/signals/types/{id}/generate returns a run_id and updates the type in place. Poll GET every 10-15 s; watch for search_instructions, scoring_criteria, and (for structured types) config to change.Delete is cascade on sources, not on results. DELETE removes the type + its signal_type_sources rows, but historical signal_results classified under this type remain visible in the feed. Combine with a dismiss loop if you need to purge them.This is the public partner API — rate-limited at 100 req/min. Use this rather than the internal /api/signals/types/{id} endpoint.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string<uuid>
required

Signal type UUID.

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)$

Response

Signal type detail.

Public signal type. Returned by every signal-type endpoint and referenced from each signal via its signal_type label.

​
id
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)$
​
label
string
required

Display name, shown in the UI and echoed as signal_type.

​
description
string
required
​
kind
enum<string>
required

structured — built-in type (hiring, funding, management_change, competitor_mentions) with a typed config payload. keyword — free-form user-defined type driven by keywords + search_instructions + scoring_criteria.

Available options:
structured,
keyword
​
enabled
boolean
required

If false, the scanner skips this type entirely.

​
keywords
string[]
required
​
disqualifiers
string[]
required

Exclusion phrases. An AI judge skips hits that match any disqualifier.

​
config
object
required

Structured-type payload. Keys depend on the underlying type (e.g. roles/seniority for hiring; stages/industries for funding). Null for keyword types.

​
config_schema
object
required

JSON Schema describing the shape of config. Null for keyword types — there's no structured config.

​
built_in
boolean
required

Built-in types cannot be renamed, deleted, or have their sources changed. Only their prompts, keywords, disqualifiers, and structured config are editable.

​
search_instructions
string | null
required
​
scoring_criteria
string | null
required
​
sources
enum<string>[] | null
required

Subset of sources enabled for this type. Null means no restriction was ever set; otherwise only listed sources feed this type.

External data source that feeds signals. A signal type can be scoped to any subset of sources; the scanner fans out across the enabled set and classifies each hit.

Available options:
news,
reddit,
hacker_news,
x_twitter,
linkedin_posts,
linkedin_jobs,
g2_capterra