> ## 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.

# Create Suggestion

> Queue a PENDING entity suggestion for human review. This does NOT create or modify any library entity — it produces a proposal that must be explicitly accepted (via suggestion/accept or the Suggestions inbox) before anything changes. Set changeType to 'add' (with name) to propose a new entity, or 'refine' (with the target entity oId) to propose changes to an existing one.



## OpenAPI

````yaml post /api/v2/suggestion/create
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/create:
    post:
      tags:
        - Suggestions
      summary: Create Suggestion
      description: >-
        Queue a PENDING entity suggestion for human review. This does NOT create
        or modify any library entity — it produces a proposal that must be
        explicitly accepted (via suggestion/accept or the Suggestions inbox)
        before anything changes. Set changeType to 'add' (with name) to propose
        a new entity, or 'refine' (with the target entity oId) to propose
        changes to an existing one.
      operationId: createSuggestion
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                changeType:
                  type: string
                  enum:
                    - add
                    - refine
                  description: >-
                    'add' proposes a brand new entity; 'refine' proposes changes
                    to an existing one.
                  example: add
                entityType:
                  type: string
                  enum:
                    - persona
                    - product
                    - segment
                    - use_case
                    - competitor
                    - alternative
                    - buying_trigger
                    - core_feature
                    - objection
                    - proof_point
                    - reference
                    - service
                    - solution
                    - brand_voice
                  description: >-
                    Library entity type: persona, product, segment, use_case,
                    competitor, alternative, buying_trigger, objection,
                    proof_point, reference, service, solution, brand_voice.
                  example: persona
                name:
                  type: string
                  description: Name of the new entity. Required when changeType is 'add'.
                oId:
                  type: string
                  description: >-
                    oId of the entity to refine (from the entity list
                    endpoints). Required when changeType is 'refine'.
                instructions:
                  type: string
                  description: >-
                    Detailed natural-language description of what to add or
                    change, and why.
                keyContext:
                  type: string
                  description: Additional background text to inform the proposal.
                sources:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - url
                          - text
                        description: >-
                          Source type: 'url' for web pages, 'text' for raw
                          content
                      content:
                        type: string
                        description: The URL to fetch or the text content
                    required:
                      - type
                      - content
                  description: >-
                    Optional source materials (URLs to fetch, or raw text) to
                    inform the proposal.
              required:
                - changeType
                - entityType
                - instructions
      responses:
        '200':
          description: The queued pending suggestion
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  data:
                    $ref: '#/components/schemas/SuggestionCreateResult'
                required:
                  - _metadata
                  - data
        '400':
          description: >-
            Missing required field for the change type (name for 'add', oId for
            'refine'), or invalid input
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  message:
                    type: string
                required:
                  - _metadata
                  - message
        '403':
          description: Plan does not include this entity type
          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
    SuggestionCreateResult:
      allOf:
        - $ref: '#/components/schemas/SuggestionSummary'
        - type: object
          properties:
            groupOId:
              type: string
              description: oId of the suggestion group the proposal was queued into.
            message:
              type: string
              description: Human-readable confirmation of what was queued.
          required:
            - groupOId
            - message
    SuggestionSummary:
      type: object
      properties:
        oId:
          type: string
          description: The suggestion's oId.
        status:
          type: string
          enum:
            - draft
            - pending
            - accepted
            - rejected
            - dismissed
            - expired
          description: Lifecycle status after the operation.
        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').
      required:
        - oId
        - status
        - changeType
        - suggestionType
        - targetEntityType
        - targetEntityOId
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key

````