Skip to main content
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

  1. Not force and a completed brief exists → returns it immediately, 200 {success: true, skipped: true, id, payload, generated_at, source}.
  2. Not force and a brief is currently generating202 {accepted: true, already_running: true, id, message}.
  3. Otherwise → (if force, first deletes any stuck ci_generating placeholder 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}.
The background job runs the same name-detection cascade as Detect Competitors, then synthesizes the full brief via an LLM (Anthropic primary, OpenAI fallback, a minimal deterministic template if both are unavailable), PATCHes the same brief row with the final 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

Authorization
string
header
required

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

Path Parameters

deal_id
string
required

The deal's id.

Body

application/json
force
boolean
default:false

Regenerate even if a completed brief already exists.

Response

Successful Response