Generate Competitive Intelligence
Deals
Generate a Competitive Brief
POST
Generate Competitive Intelligence
Gated by the
ai.competitive_intelligence config feature flag — a 403 names the flag when disabled.
The representative async AI-generation endpoint on this router — it writes a placeholder row, kicks off a background job, and returns 202 immediately so the request never blocks on an LLM call. Generate a Deal Brief follows the identical pattern.
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
- Not
forceand a completed brief exists → returns it immediately,200 {success: true, skipped: true, id, payload, generated_at, source}. - Not
forceand a brief is currently generating →202 {accepted: true, already_running: true, id, message}. - Otherwise → (if
force, first deletes any stuckci_generatingplaceholder rows), inserts a placeholder brief row, schedules a background job, and returns immediately:202 {accepted: true, skipped: false, id, payload: <placeholder>, generated_at, source: "ci_generating", message}.
payload and a ci_<source> label, and re-syncs deal_competitors from the resulting battlecard names. A failure mid-job persists an error payload into the same row (source: "ci_error") instead of leaving it stuck generating — poll Get the Latest Competitive Brief until payload.metadata._ci_generating is gone.
Payload shape (once complete)
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
Regenerate even if a completed brief already exists.
Response
Successful Response