Preview. The endpoints on this page are illustrative and are likely to change as they move toward general availability. Documentation is published in advance so you can start shaping your integration; treat request and response details as subject to revision.

Insight (8P) record

An Insight record is one of the eight discovery-structure records that hang off a deal — the "8Ps" of Cortex's sales-methodology framework. Each Insight record is append-only: fields are arrays of insight items, and new insights are added rather than editing existing ones. The record is the history of what the sales team learned across meetings.

Returned by /api/v1alpha1/deals/{id}/insights and /api/v1alpha1/insights/{id}.

The eight types

Name	Id prefix	Captures
Profile	prof_	Who the buyer is — role, seniority, tenure
Problem	prob_	The problem they're trying to solve
Pain	pain_	The consequences of not solving it
Power	powr_	Decision-makers, budget authority, procurement path
Position	posn_	Where Cirrus fits vs. competing options
Phases	phas_	The buying-process phases they're moving through
Process	proc_	The formal evaluation process (POCs, references, security review)
Plan	plan_	The agreed close plan — dates, owners, deliverables

The 8P type is visible from the id alone — Profile ids start prof_, Problem ids start prob_, and so on. Convenient for logs and cross-references.

The Insight schema

{
  "id": "prof_...",
  "schemaType": "profile",
  "dealId": "deal_...",
  "orgId": "org_...",
  "schemaId": "schm_...",
  "schemaVersion": 2,
  "fields": {
    "role": [
      { /* InsightItem shape */ }
    ],
    "seniority": [ /* more items */ ],
    "tenure": [ /* more items */ ]
  },
  "createdAt": "2026-06-16T17:03:22Z",
  "updatedAt": "2026-07-14T09:30:00Z"
}

Root fields

Field	Type	Description
id	string	Prefixed per 8P type.
schemaType	string	Lowercase 8P type — profile, problem, etc. Same value used in path segments on the API.
dealId	string	The parent deal, prefixed deal_.
orgId	string	Your org id.
schemaId	string	Schema the 8P is pinned to, prefixed schm_.
schemaVersion	number	Version at last update.
fields	object	Map from schema field key to an ordered array of InsightItem objects. Documented below.
createdAt, updatedAt	string	ISO 8601 UTC.

The fields map

Every schema defines its own field keys — for example, a Profile schema might have role, seniority, tenure; a Power schema might have decisionMakers, procurementPath. The fields map has one entry per schema-defined key.

Each value is an ordered array of insight items (oldest → newest). Append-only: POST /insights/{type}/fields/{fieldKey} adds to the tail. There is no update or delete verb; new understanding is captured as a new item.

Empty array when the field has no captured insights yet. Missing key when the schema doesn't define the field.

InsightItem shape

itemId string

Stable id for the individual insight item, prefixed insi_. Referenced by Q&A linkedInsight back-pointers.

value

Type per the schema field:

• string — the most common case.
• number / boolean — schema-typed primitives.
• array — some fields hold list values (e.g., a list of decision-maker names).
• object — a few schemas define compound value shapes. Treat as opaque unless you've fetched the schema definition.

importance string

low / medium / high. Author-supplied significance. Default medium on API-authored items when omitted.

rationale string

(optional) Why this matters. Free-text.

capturedFrom object

(optional) Where the insight came from. null when the insight was manually authored without a citation.

Attribute	Type	Description
meetingId	string	Meeting where the insight was captured, prefixed mtg_.
chunkId	string	(optional) Transcript chunk — enables jump-to-transcript-moment UIs. Prefixed chnk_. See Transcript.
capturedAt	string	ISO 8601 UTC. When the capture happened (usually near the meeting time).

capturedBy object

Who captured the insight. Discriminated by type:

• type: "user" — plus userId (usr_...) and displayName. Manually authored via dashboard or CLI.
• type: "cortex-agent" — plus agentName (e.g., "discovery-scribe-v2"). AI-authored by Cortex.

{
  "itemId": "insi_...",
  "value": "Director of Sales Ops",
  "importance": "high",
  "rationale": "Confirmed by attendee's LinkedIn and their intro on the discovery call",
  "capturedFrom": {
    "meetingId": "mtg_...",
    "chunkId": "chnk_...",
    "capturedAt": "2026-06-16T17:03:22Z"
  },
  "capturedBy": {
    "type": "user",
    "userId": "usr_...",
    "displayName": "Alex Rivera"
  }
}

Related models

• Deal — the parent object. insightSummary on the deal carries pointers to each of the eight Insight records.
• Q&A item — Discovery Q&As reference 8P fields via linkedInsight.schemaType + fieldKey, and auto-close when their linked field gets an insight.
• Transcript — capturedFrom cites the transcript chunk where an insight was picked up.