> ## Documentation Index > Fetch the complete documentation index at: https://docs.octavehq.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Suggestion > Preview a single entity suggestion in full. For 'add' suggestions, returns the complete proposed new entity. For 'refine' suggestions, returns both the current entity and what it would look like after the change, so you can show the diff. Optionally include the supporting evidence (events/findings) that generated it. ## OpenAPI ````yaml get /api/v2/suggestion/get openapi: 3.0.0 info: version: 1.0.0 title: Octave API description: API for Octave workspace management and AI-powered content generation servers: - url: https://app.octavehq.com security: - ApiKeyAuth: [] paths: /api/v2/suggestion/get: get: tags: - Suggestions summary: Get Suggestion description: >- Preview a single entity suggestion in full. For 'add' suggestions, returns the complete proposed new entity. For 'refine' suggestions, returns both the current entity and what it would look like after the change, so you can show the diff. Optionally include the supporting evidence (events/findings) that generated it. operationId: getSuggestion parameters: - schema: type: string description: The suggestion oId to preview. Get this from suggestion/list. example: esug_abc123 required: true description: The suggestion oId to preview. Get this from suggestion/list. name: oId in: query - schema: type: boolean default: true description: >- When true (default), also returns the rendered preview: for 'add' the full proposed new entity, for 'refine' the entity as it would look after the change (plus the current entity to diff against). Set to false for a fast metadata-only fetch that skips preview generation. required: false description: >- When true (default), also returns the rendered preview: for 'add' the full proposed new entity, for 'refine' the entity as it would look after the change (plus the current entity to diff against). Set to false for a fast metadata-only fetch that skips preview generation. name: includePreview in: query - schema: type: boolean default: false description: >- When true, also returns the supporting events/findings that generated this suggestion (the 'why'). Defaults to false. required: false description: >- When true, also returns the supporting events/findings that generated this suggestion (the 'why'). Defaults to false. name: includeEvidence in: query - schema: type: boolean default: false description: >- When true, also returns diffChunks — before/after diff chunks for the proposed change. For entity refine suggestions these are field-level diffs of the current entity vs the previewed result; for doc-update suggestions they are anchored hunks validated against the doc, each with a clean/stale/unverified status. Defaults to false to keep responses small. required: false description: >- When true, also returns diffChunks — before/after diff chunks for the proposed change. For entity refine suggestions these are field-level diffs of the current entity vs the previewed result; for doc-update suggestions they are anchored hunks validated against the doc, each with a clean/stale/unverified status. Defaults to false to keep responses small. name: includeDiff in: query responses: '200': description: The suggestion detail (and preview, unless skipped) content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' data: $ref: '#/components/schemas/SuggestionDetail' required: - _metadata - data '404': description: Suggestion not found content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' message: type: string required: - _metadata - message deprecated: false components: schemas: Metadata: type: object properties: usage: type: number default: 0 example: 0 description: API usage requestId: type: string example: requestId description: Request ID message: type: string example: message description: Message timestamp: type: string example: '2021-01-01T00:00:00.000Z' description: Timestamp required: - requestId - timestamp SuggestionDetail: type: object properties: oId: type: string description: The suggestion's oId. status: type: string enum: - draft - pending - accepted - rejected - dismissed - expired description: >- Lifecycle status. 'pending' is awaiting review and is the only status that can be accepted or rejected. 'accepted' and 'rejected' are reviewer decisions. 'dismissed' was cleared without a decision. 'expired' means the review window ran out before anyone looked — it is not a judgement on the suggestion. 'draft' is internal. changeType: type: string enum: - add - refine description: >- Friendly framing of the change: 'add' creates a brand new library entity; 'refine' changes an existing one. example: add suggestionType: type: string enum: - create_entity - update_entity - generate_entity - refine_entity - link_entities description: The raw underlying suggestion type. targetEntityType: type: string enum: - Product - Service - Solution - Persona - UseCase - Reference - Segment - Competitor - Alternative - BuyingTrigger - CoreFeature - Objection - ProofPoint - Playbook - Agent - Hypothesis - BrandVoice - Resource description: The library entity type being added or refined. targetEntityOId: type: string nullable: true description: oId of the entity being refined (null for 'add'). name: type: string nullable: true description: Name of the entity to add or refine. message: type: string nullable: true description: Refinement instruction message ('refine' suggestions). summaryMessage: type: string nullable: true description: LLM-generated summary of what was refined ('refine'). attributes: type: array nullable: true items: type: string description: >- For 'refine' suggestions: the entity attribute names the refinement changes (e.g. ['competitorWeaknesses']). Null when the suggestion isn't attribute-scoped. reasoning: type: string description: Why this suggestion was generated. confidence: type: number nullable: true description: Model confidence in the suggestion, when scored. createdAt: type: string nullable: true format: date-time description: When the suggestion was created (ISO 8601). preview: nullable: true description: >- For 'add': the full proposed new entity. For 'refine': the entity as it would look after the change is applied. Null if not generated (omitted preview, or generation failed). currentEntity: nullable: true description: >- For 'refine': the current entity before the change, to diff against `preview`. Null for 'add'. docUpdate: type: object nullable: true properties: insight: type: string description: What changed in the field. recommendedAction: type: string description: The update the doc owner should make. proposedUpstreamEdit: type: string description: Ready-to-apply draft of the edit; may be empty. resourceName: type: string nullable: true description: The source doc's name. sourceUrl: type: string nullable: true description: >- External deep link to the source doc (Drive/Notion/Linear URL, or the page URL for website resources). primaryEntityType: type: string enum: - Product - Service - Solution - Persona - UseCase - Reference - Segment - Competitor - Alternative - BuyingTrigger - CoreFeature - Objection - ProofPoint - Playbook - Agent - Hypothesis - BrandVoice - Resource description: The drifted library entity's type. primaryEntityOId: type: string description: The drifted library entity — resolvable via entity/get. provenance: type: array nullable: true items: type: object properties: entityOId: type: string entityType: type: string entityName: type: string nullable: true rationale: type: string nullable: true changes: type: array items: type: object properties: source: type: string enum: - suggestion - user - apiKey - mcp - unknown at: type: string summary: type: string suggestionOId: type: string nullable: true findingCount: type: number nullable: true findings: type: array items: type: object properties: findingOId: type: string actor: type: string nullable: true actorTitle: type: string nullable: true companyName: type: string nullable: true companyDomain: type: string nullable: true providerName: type: string nullable: true extractionType: type: string snippetText: type: string text: type: string occurredAt: type: string required: - findingOId - extractionType - snippetText - text - occurredAt required: - source - at - summary - findings required: - entityOId - entityType - changes description: >- The upstream-change trail behind this doc update: what changed on the triggering entities (accepted suggestions / manual edits, with dates and channels) and the curated findings behind those changes. Null on rows created before provenance capture. editHunks: type: array nullable: true items: type: object properties: anchor: type: string replacement: type: string kind: type: string enum: - replace - insert_after - delete required: - anchor - replacement - kind description: >- Anchor-validated before/after edit hunks (each anchor is a verbatim excerpt of the doc at check time). Null on rows created before hunk capture. For live-doc staleness checks, use includeDiff=true and read diffChunks instead. required: - insight - recommendedAction - proposedUpstreamEdit - resourceName - sourceUrl - primaryEntityType - primaryEntityOId - provenance - editHunks description: >- For Resource-target (doc-update) suggestions: the structured drift proposal an external agent needs to apply the edit upstream. `targetEntityOId` is the doc itself. Null for library-entity suggestions, and for Resource suggestions whose payload predates the drift pipeline — check targetEntityType to tell shapes apart. evidence: type: array nullable: true items: $ref: '#/components/schemas/SuggestionEvidenceItem' description: >- Supporting events/findings that generated this suggestion. Null unless requested with includeEvidence=true. evidenceTotal: type: number nullable: true description: >- Uncapped total of supporting events behind this suggestion — `evidence` is a capped sample of these, so use this number when stating how often the pattern was seen. Null unless requested with includeEvidence=true. diffChunks: type: array nullable: true items: type: object properties: label: type: string before: type: string after: type: string kind: type: string enum: - replace - insert_after - delete status: type: string enum: - clean - stale - unverified diff: type: string required: - label - before - after - kind - status - diff description: >- Before/after diff chunks for the proposed change (each carries a ready-to-render fenced ```diff block). Null unless requested with includeDiff=true; empty when the suggestion has nothing diffable (add suggestions, doc rows stored before hunk capture, or full-doc rewrites). writeback: type: object nullable: true properties: status: type: string description: 'Write outcome: succeeded, skipped, failed, pending.' skipReason: type: string nullable: true description: Why a skipped write was skipped. target: type: string nullable: true description: >- Provider target key (e.g. google_drive). Null for rail-minted issues with no writable doc target (e.g. website pages). at: type: string nullable: true format: date-time description: When the write attempt was last updated (ISO 8601). required: - status - skipReason - target - at description: >- For accepted doc-update (Resource) suggestions: the upstream write's outcome — succeeded means the attributed comment landed in the doc. Null when no write has been attempted yet (accept is async — re-fetch to poll). required: - oId - status - changeType - suggestionType - targetEntityType - targetEntityOId - name - message - summaryMessage - attributes - reasoning - confidence - createdAt - docUpdate - evidence - evidenceTotal - diffChunks - writeback SuggestionEvidenceItem: type: object properties: eventOId: type: string description: oId of the source event the finding came from. findingOId: type: string description: oId of the extracted finding. extractionType: type: string enum: - EMAIL_INTERNAL_USE_CASE - EMAIL_INTERNAL_PROOF_POINT - EMAIL_INTERNAL_PAIN_POINT - EMAIL_INTERNAL_BENEFITS_HIGHLIGHTED - EMAIL_INTERNAL_VALUE_PROP - EMAIL_INTERNAL_SOCIAL_PROOF - EMAIL_INTERNAL_CALL_TO_ACTION - EMAIL_INTERNAL_OBJECTION_HANDLING - EMAIL_EXTERNAL_CALL_TO_ACTION - EMAIL_EXTERNAL_OBJECTION - EMAIL_EXTERNAL_QUESTION - EMAIL_EXTERNAL_INTEREST_EXPRESSION - EMAIL_EXTERNAL_FEATURE_REQUEST - EMAIL_EXTERNAL_REQUIREMENT - EMAIL_EXTERNAL_PRICING_FEEDBACK - EMAIL_EXTERNAL_COMPARATIVE_STATEMENT - EMAIL_EXTERNAL_KEY_TAKEAWAY - EMAIL_EXTERNAL_COMPETITOR_MENTION - EMAIL_EXTERNAL_NEXT_STEP - EMAIL_EXTERNAL_URGENCY_INDICATOR - EMAIL_EXTERNAL_DECISION_MAKING_SIGNAL - EMAIL_EXTERNAL_UNIQUE_LANGUAGE_USED - EMAIL_OVERALL_SENTIMENT - EMAIL_INTERNAL_TITLE_TO_PERSONA - EMAIL_EXTERNAL_TITLE_TO_PERSONA - EMAIL_SEGMENT_DESCRIPTION - SOCIAL_INTERNAL_USE_CASE - SOCIAL_INTERNAL_PROOF_POINT - SOCIAL_INTERNAL_PAIN_POINT - SOCIAL_INTERNAL_VALUE_PROP - SOCIAL_INTERNAL_SOCIAL_PROOF - SOCIAL_INTERNAL_CALL_TO_ACTION - SOCIAL_INTERNAL_BENEFITS_HIGHLIGHTED - SOCIAL_INTERNAL_OBJECTION_HANDLING - SOCIAL_INTERNAL_TITLE_TO_PERSONA - SOCIAL_SEGMENT_DESCRIPTION - SOCIAL_PLAYBOOK_TOPICS - SOCIAL_EXTERNAL_CALL_TO_ACTION - SOCIAL_EXTERNAL_OBJECTION - SOCIAL_EXTERNAL_QUESTION - SOCIAL_EXTERNAL_INTEREST_EXPRESSION - SOCIAL_EXTERNAL_FEATURE_REQUEST - SOCIAL_EXTERNAL_REQUIREMENT - SOCIAL_EXTERNAL_PRICING_FEEDBACK - SOCIAL_EXTERNAL_COMPARATIVE_STATEMENT - SOCIAL_EXTERNAL_KEY_TAKEAWAY - SOCIAL_EXTERNAL_COMPETITOR_MENTION - SOCIAL_EXTERNAL_NEXT_STEP - SOCIAL_EXTERNAL_URGENCY_INDICATOR - SOCIAL_EXTERNAL_DECISION_MAKING_SIGNAL - SOCIAL_EXTERNAL_UNIQUE_LANGUAGE_USED - SOCIAL_EXTERNAL_TITLE_TO_PERSONA - SOCIAL_OVERALL_SENTIMENT - CALL_EXTERNAL_BUSINESS_PROBLEMS - CALL_EXTERNAL_IDEAL_SOLUTION_DESCRIPTION - CALL_EXTERNAL_PRIMARY_GOALS - CALL_EXTERNAL_WHY_ON_THIS_CALL - CALL_EXTERNAL_STATUS_QUO_HOW_THEY_SOLVE_TODAY - CALL_EXTERNAL_INDUSTRY_TRENDS - CALL_EXTERNAL_COMPETITORS_TO_OUR_OFFERING - CALL_EXTERNAL_COMPETITORS_OF_THEIR_COMPANY - CALL_EXTERNAL_CURRENT_TOOL_OR_SOLUTION_PROBLEMS - CALL_EXTERNAL_OBJECTIONS - CALL_EXTERNAL_PAIN_OR_PROBLEM_AGREEMENTS - CALL_EXTERNAL_ROLE_OR_RESPONSIBILITIES_DESCRIPTION - CALL_EXTERNAL_QUESTIONS_OR_CONFUSION_ABOUT_OFFERING - CALL_EXTERNAL_CAPABILITIES_THAT_DREW_EXCITEMENT - CALL_EXTERNAL_UNIQUE_LANGUAGE_USED - CALL_EXTERNAL_FEATURE_REQUEST - CALL_INTERNAL_USE_CASES_BROUGHT_UP - CALL_INTERNAL_PROOF_POINTS - CALL_INTERNAL_REFERENCE_CUSTOMERS_OR_SOCIAL_PROOF - CALL_INTERNAL_COMPETITORS - CALL_INTERNAL_COMPETITORS_TO_OUR_OFFERING - CALL_INTERNAL_OBJECTION_HANDLING - CALL_INTERNAL_VALUE_PROP_PRESENTATIONS - CALL_INTERNAL_DIFFERENTIATED_VALUE - CALL_INTERNAL_CORE_CAPABILITIES - CALL_INTERNAL_COMPLEMENTARY_TOOLS_MENTIONED - RESOURCE_USE_CASES - RESOURCE_PROOF_POINTS - RESOURCE_REFERENCE_CUSTOMERS - RESOURCE_COMPETITORS - RESOURCE_OBJECTION_HANDLING - RESOURCE_VALUE_PROPS - RESOURCE_DIFFERENTIATED_VALUE - RESOURCE_CORE_CAPABILITIES - RESOURCE_SEGMENTS - RESOURCE_INTEGRATIONS_PARTNERS - RESOURCE_UNIQUE_LANGUAGE - RESOURCE_PAIN_POINTS - RESOURCE_TARGET_PERSONAS - RESOURCE_ALTERNATIVES - RESOURCE_BUYING_TRIGGERS - CALL_OVERALL_SENTIMENT - CALL_PURPOSE_CLASSIFICATION - CALL_TITLE_TO_PERSONA - CALL_SEGMENT_DESCRIPTION - CRM_TITLE_TO_PERSONA - CRM_SEGMENT_DESCRIPTION - EVENT_SUMMARY - BULK_IMPORT_THEMES - BULK_LOSS_REASONS - BULK_WIN_REASONS - BULK_PAIN_POINTS - BULK_USE_CASES - BULK_COMPETITORS - BULK_OBJECTIONS - BULK_SEGMENTS - BULK_PERSONAS - ADS_INTERNAL_MESSAGING_THEME - ADS_INTERNAL_TARGET_AUDIENCE - ADS_INTERNAL_COMPETITIVE_POSITIONING - ADS_INTERNAL_KEYWORD_TARGETING - ADS_EXTERNAL_ENGAGEMENT_SIGNAL - ADS_SEGMENT_DESCRIPTION - ADS_MOTION_TYPE - ADS_OFFERING_MATCH - CALL_PROSPECT_RELATIONSHIP_TO_SELLER - CALL_MOTION_TYPE - CALL_OFFERING_MATCH - EMAIL_PROSPECT_RELATIONSHIP_TO_SELLER - EMAIL_MOTION_TYPE - EMAIL_OFFERING_MATCH - CRM_MOTION_TYPE - CRM_OFFERING_MATCH - RESOURCE_OFFERING_MATCH - RESOURCE_TYPE_CLASSIFICATION - CALL_PLAYBOOK_TOPICS - EMAIL_PLAYBOOK_TOPICS - RESOURCE_PLAYBOOK_TOPICS - EMAIL_PLAYBOOK_SOURCE - SOCIAL_PLAYBOOK_SOURCE description: The extraction type of the finding. actor: type: string nullable: true description: Who the finding is attributed to, when known. text: type: string description: The verbatim source words behind the finding (what was said). snippetText: type: string description: >- The extractor's normalized claim — a short label ABOUT `text`, not a copy of it (e.g. 'Early adopter conversion rate' for a quote about giving the product to 20 clients). matchConfidence: type: string nullable: true enum: - LOW - MEDIUM - HIGH - null description: >- How confident the matcher was that this finding belongs to the suggestion's entity. Null when the extractor records no match analysis. Distinct from the suggestion's own `confidence`, which scores the proposal as a whole. actorTitle: type: string nullable: true description: The speaking contact's job title, when the CRM knows it. companyName: type: string nullable: true description: >- The company this finding is evidence FROM (the event's CRM-associated company, else an external participant's company). companyDomain: type: string nullable: true description: That company's domain. providerName: type: string nullable: true description: The integration the source event came from, when known. createdAt: type: string nullable: true format: date-time description: >- When the underlying event (call/email/meeting) actually occurred (ISO 8601). required: - eventOId - findingOId - extractionType - text - snippetText - providerName - createdAt securitySchemes: ApiKeyAuth: type: apiKey in: header name: api_key ````