> ## 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. # Update Suggestion > Edit a PENDING entity suggestion before accepting it. Two combinable modes: `instructions` regenerates the proposed content via AI; `edits` applies a precise partial field override with no regeneration. Works for both 'add' and 'refine' suggestions. Returns the updated preview. The suggestion stays pending — nothing is applied until you call suggestion/accept. ## OpenAPI ````yaml post /api/v2/suggestion/update 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/update: post: tags: - Suggestions summary: Update Suggestion description: >- Edit a PENDING entity suggestion before accepting it. Two combinable modes: `instructions` regenerates the proposed content via AI; `edits` applies a precise partial field override with no regeneration. Works for both 'add' and 'refine' suggestions. Returns the updated preview. The suggestion stays pending — nothing is applied until you call suggestion/accept. operationId: updateSuggestion requestBody: content: application/json: schema: type: object properties: oId: type: string description: >- The suggestion oId to revise (from suggestion/list). Only pending suggestions can be revised. example: esug_abc123 instructions: type: string description: >- REGENERATE mode. Natural-language instructions for how to change the proposal — e.g. 'make the description more concise'. The proposed content is regenerated by AI. Combine with `edits` to regenerate first, then apply precise overrides on top. edits: type: object additionalProperties: nullable: true description: >- OVERRIDE mode. A partial patch of fields on the proposed entity — only the keys you provide change; arrays replace wholesale, objects deep-merge. No AI regeneration runs. Use this to surgically fix one detail of an otherwise-good proposal. Inspect the current proposal with suggestion/get first to see the field shape. mode: type: string enum: - replace - append default: replace description: >- Applies to `instructions` only: 'replace' (default) swaps the prior instruction for this one; 'append' layers it on top. required: - oId responses: '200': description: The revised suggestion preview content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' data: $ref: '#/components/schemas/SuggestionDetail' required: - _metadata - data '400': description: Neither instructions nor edits provided, or suggestion not pending content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' message: type: string required: - _metadata - message '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 ````