> ## 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. # List Suggestions > List entity suggestions for the workspace — proposed library changes generated from analytics (calls, emails, deals) and other sources. Mirrors the Suggestions inbox: defaults to pending suggestions from the last 14 days. Each item includes its change type ('add' = new entity, 'refine' = change to an existing one), the entity name, the description (add) or instruction message (refine), and the reasoning. ## OpenAPI ````yaml get /api/v2/suggestion/list 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/list: get: tags: - Suggestions summary: List Suggestions description: >- List entity suggestions for the workspace — proposed library changes generated from analytics (calls, emails, deals) and other sources. Mirrors the Suggestions inbox: defaults to pending suggestions from the last 14 days. Each item includes its change type ('add' = new entity, 'refine' = change to an existing one), the entity name, the description (add) or instruction message (refine), and the reasoning. operationId: listSuggestions parameters: - schema: type: array items: type: string enum: - draft - pending - accepted - rejected - dismissed - expired description: >- Filter by status. Defaults to ['pending'] — the items awaiting review, matching the Suggestions inbox default. required: false description: >- Filter by status. Defaults to ['pending'] — the items awaiting review, matching the Suggestions inbox default. name: statuses in: query - schema: type: array items: type: string enum: - add - refine description: >- Filter by change type: 'add' (new entity) or 'refine' (change to an existing one). Omit to include both. required: false description: >- Filter by change type: 'add' (new entity) or 'refine' (change to an existing one). Omit to include both. name: changeTypes in: query - schema: type: array items: type: string enum: - Product - Service - Solution - Persona - UseCase - Reference - Segment - Competitor - Alternative - BuyingTrigger - CoreFeature - Objection - ProofPoint - Playbook - Agent - Hypothesis - BrandVoice - Resource description: >- Filter by the library entity type being added or refined (e.g. Persona, Product, UseCase, Competitor). Omit to include all. required: false description: >- Filter by the library entity type being added or refined (e.g. Persona, Product, UseCase, Competitor). Omit to include all. name: targetEntityTypes in: query - schema: type: integer minimum: 0 exclusiveMinimum: true description: >- Look back this many days from now. Defaults to 14 (the inbox default). Ignored when startDate is provided. required: false description: >- Look back this many days from now. Defaults to 14 (the inbox default). Ignored when startDate is provided. name: daysBack in: query - schema: type: string nullable: true format: date-time description: >- Only include suggestions created on or after this date (ISO 8601). Overrides daysBack when set. required: false description: >- Only include suggestions created on or after this date (ISO 8601). Overrides daysBack when set. name: startDate in: query - schema: type: string nullable: true format: date-time description: >- Only include suggestions created on or before this date (ISO 8601). required: false description: Only include suggestions created on or before this date (ISO 8601). name: endDate in: query - schema: type: array items: type: string enum: - analytics - brand_voice - user_created - ask_octave - ask_octave_manual - resource - crm_import - direct_findings - trends description: >- Restrict to suggestions originating from these sources (e.g. ANALYTICS, DIRECT_FINDINGS, USER_CREATED). Omit to include all sources. required: false description: >- Restrict to suggestions originating from these sources (e.g. ANALYTICS, DIRECT_FINDINGS, USER_CREATED). Omit to include all sources. name: sourceTypes in: query - schema: type: integer minimum: 0 exclusiveMinimum: true maximum: 100 default: 20 description: Max results to return (1-100, default 20). required: false description: Max results to return (1-100, default 20). name: limit in: query - schema: type: integer nullable: true minimum: 0 default: 0 description: Pagination offset (default 0). required: false description: Pagination offset (default 0). name: offset in: query - schema: type: string enum: - asc - desc default: desc description: Sort by createdAt. Defaults to 'desc' (newest first). required: false description: Sort by createdAt. Defaults to 'desc' (newest first). name: sortDirection in: query responses: '200': description: List of entity suggestions for the workspace content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' suggestions: type: array items: $ref: '#/components/schemas/SuggestionListItem' total: type: number description: Total suggestions matching the filters. counts: type: object properties: pending: type: number accepted: type: number rejected: type: number required: - pending - accepted - rejected description: >- Status counts across the timeframe/filters, ignoring the status filter. nextOffset: type: number nullable: true description: >- Offset for the next page, or null when there are no more results. required: - _metadata - suggestions - total - counts - nextOffset '400': description: Bad request 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 SuggestionListItem: type: object properties: oId: type: string description: The suggestion's oId (use with get/accept/reject/update). 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 description: >- Name of the entity to add or the entity being refined (empty string when none). description: type: string nullable: true description: Description of the entity to add ('add' suggestions). message: type: string nullable: true description: The refinement instruction message ('refine' suggestions). summaryMessage: type: string nullable: true description: LLM-generated summary of what was refined ('refine'). reasoning: type: string description: Why this suggestion was generated. createdAt: type: string nullable: true format: date-time description: When the suggestion was created (ISO 8601). required: - oId - status - changeType - suggestionType - targetEntityType - targetEntityOId - name - description - message - summaryMessage - reasoning - createdAt securitySchemes: ApiKeyAuth: type: apiKey in: header name: api_key ````