Research API

All endpoints require authentication and deals tool permissions. Routes are mounted under /api/research.

Run Research

POST /api/research/run

Triggers a research pipeline to generate a pre-call brief for a deal or company. The pipeline analyses the target’s website/store URL and produces opportunity insights.

Permission: deals:update

Body:

Field	Type	Required	Description
entity_type	string	Yes	deal or company
entity_id	string	Yes	Deal or company ID
store_url	string	No	URL to research. Falls back to company’s website or domain field if omitted.

Response: { brief }

The brief includes the full deal_research_briefs record with brief_content (JSON), status, shopify_detected, and other metadata.

Error responses:

• 400 — Missing entity_type or entity_id, or invalid entity_type
• 404 — Deal not found or has no company linked
• 422 — No URL available or invalid URL

Side effects:

• Logs history on the deal/company
• Notifies the deal owner (if different from the triggering user)

---

Get Brief

GET /api/research/:briefId

Returns a single research brief by ID.

Permission: deals:view

Path parameters:

Param	Type	Description
briefId	string	Brief ID

Response: { brief }

Error: 404 if brief not found.

---

List Briefs for Deal

GET /api/research/deals/:id/briefs

Returns all research briefs for a deal, ordered by most recent first.

Permission: deals:view

Path parameters:

Param	Type	Description
id	string	Deal ID

Response: { briefs }

---

List Briefs for Company

GET /api/research/companies/:id/briefs

Returns all research briefs for a company (across all entity types), ordered by most recent first.

Permission: deals:view

Path parameters:

Param	Type	Description
id	string	Company ID

Response: { briefs }

---

Refresh Brief

POST /api/research/:briefId/refresh

Re-runs the research pipeline for an existing brief. Creates a new brief record (preserving history) using the same entity and URL.

Permission: deals:update

Path parameters:

Param	Type	Description
briefId	string	Existing brief ID to refresh

Response: { brief } — the newly generated brief.

Error: 404 if original brief not found.