REST API v1

API Reference

Full programmatic access to accounts, signals, runs, ICPs, and workspace data. Authenticate with a Bearer API key generated from your settings panel.

Base URL

https://app.gethunch.ai

Auth

Authorization: Bearer sk-...

Format

JSON (application/json)

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from Settings > API Keys. Keys are shown once at creation and cannot be retrieved afterward.

curl

curl https://app.gethunch.ai/api/v1/accounts \
  -H "Authorization: Bearer sk-your-api-key"

200Success

401Invalid or missing API key

429Rate limit exceeded

Accounts

GET/api/v1/accountsList accounts

Returns all accounts in your workspace, sorted by score descending. Paginated at 50/page by default (max 100).

Query parameters

Name	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Results per page (max: 100)
status	string	Filter by status: active, suggested, inactive, rejected
owner_id	string	Filter by assigned team member ID
tag	string	Filter by account tag
domain	string	Filter by domain (partial match)

POST/api/v1/accountsAdd accounts

Add one or more accounts to your workspace. Send a single object or an array of up to 500.

Request body

Field	Type	Required	Description
name	string	required	Company name
domain	string	optional	Company domain
status	string	optional	Initial status (default: suggested)
tags	string[]	optional	Array of tags
owner_id	string	optional	Assign to a team member

GET/api/v1/accounts/:idGet account

Returns the full account record including firmographics, ICP score, and the why-now brief.

PATCH/api/v1/accounts/:idUpdate account

Update status, tags, owner, or other mutable fields on a single account.

GET/api/v1/accounts/:id/signalsGet signals for account

Returns every signal detected on this account, including headline, narrative, evidence sources, and suggested outreach copy.

Signals

GET/api/v1/signalsList signal definitions

Returns all signal definitions in your workspace, including their plain English description, priority, status, and last run info.

POST/api/v1/signals/:id/runTrigger a signal run

Kicks off a signal research run for all active accounts. Useful for programmatic scheduling or CI pipeline triggers.

Runs

GET/api/v1/runsList signal runs

Returns recent signal run history including status, stats (accounts matched, cost), and timestamps.

GET/api/v1/runs/:idGet run details

Returns the full details of a single run including per-account results.

ICPs

GET/api/v1/icpsList ICP profiles

Returns all Ideal Customer Profiles defined in your workspace.

POST/api/v1/icpsCreate ICP

Create a new ICP profile with a plain English description. Hunch uses this when evaluating account fit.

Request body

Field	Type	Required	Description
raw_text	string	required	Plain English ICP description
is_active	boolean	optional	Whether this ICP is the active one (default: false)

PATCH/api/v1/icps/:idUpdate ICP

Update the text or active status of an existing ICP.

DELETE/api/v1/icps/:idDelete ICP

Permanently deletes an ICP profile.

Workspace

GET/api/v1/workspaceGet workspace

Returns workspace metadata including name, plan account limit, active account count, and credits remaining.

GET/api/v1/membersList team members

Returns all members of the workspace with their email, display name, and role.

API keys

GET/api/v1/keysList API keys

Returns all API keys for your workspace. The full key is only shown at creation time.

POST/api/v1/keysCreate API key

Creates a new API key. The full key is returned once and cannot be retrieved again.

Request body

Field	Type	Required	Description
name	string	required	Human-readable label for this key

DELETE/api/v1/keys/:idRevoke API key

Immediately revokes an API key. Any requests using this key will return 401.

Response format

All responses return JSON. List endpoints include pagination metadata. Single-resource endpoints return the object directly.

List response

json

{
  "data": [...],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}

Error response

json

{
  "error": "Invalid or missing API key",
  "status": 401
}

Need push-based delivery?

The REST API is pull-based. For real-time push delivery, configure an outbound webhook to receive signed payloads the moment a signal fires.

Webhook docs