Generate Brief
Deals
Generate a Deal Brief
POST
Generate Brief
Gated by the Payload shape (once complete, in
ai.deal_brief config feature flag — a 403 names the flag when disabled.
Follows the same async placeholder pattern as Generate a Competitive Brief — writes a placeholder, kicks off a background job, and returns 202 immediately.
Auth
Requires a CRM manage scope and an active organization on the token. Any*:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.
Flow
- Already generating (
deals.latest_brief.model_used == "deal_brief_generating") →202 {accepted: true, already_running: true, message}. - Otherwise → deletes any stuck placeholder
deal_briefsrows, inserts a new placeholder row + placeholderdeals.latest_brief, schedules a background job, returns202 {accepted: true, already_running: false, id, latest_brief: <placeholder>, message}immediately.
force flag or “return existing if already generated” short-circuit — every call (when not already running) starts a fresh generation.
The background job calls an LLM (Anthropic) to produce a structured executive brief grounded in the deal’s contacts, activities, health factors, and open tasks, then PATCHes both the deal_briefs row and deals.latest_brief. A failure persists an error brief instead (model_used: "deal_brief_error").
Payload shape (once complete, in latest_brief / via Get a Deal)
{summary, summary_evidence: [{ref_type, ref_id, excerpt}], stakeholders: [{name, role, sentiment, last_contact_summary, risk_flag, recommended_action, evidence}], risks: [{title, description, severity, mitigation, evidence}], opportunities: [{title, description, impact, action, evidence}], strategy, next_actions: [{action, priority, owner, due_timing}], forecast_assessment: {confidence, reasoning, adjusted_close_date, adjusted_value}, model_used, brief_type}
Poll Get a Deal and read .brief until model_used is no longer "deal_brief_generating".
Errors
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The deal's id.
Body
application/json
Brief style: standard, board_ready, or qbr.
Response
Successful Response