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

# How do Suggestions and Revisions work?

> Suggestions propose Library updates grounded in real conversation evidence; accepted suggestions become Revisions — a full audit trail of how your strategy evolved and why.

## The learning loop

The [analytics pipeline](/concepts/analytics) turns conversations into findings. Suggestions and Revisions are how those findings change your strategy: when Octave detects a recurring pattern — a new objection across multiple calls, a competitor gaining mention frequency, a value prop landing in won deals — it proposes a concrete [Library](/concepts/library) update, your team decides, and every decision is recorded.

The loop: **Findings → Suggestion → your decision → Library update → Revision**. Nothing changes your Library without a decision, and nothing changes without a trail.

## Suggestions

A Suggestion is a proposed Library change grounded in evidence. There are two kinds:

* **Create** — propose a new entity: an [Objection](/concepts/objections) prospects keep raising, a [Competitor](/concepts/competitors) that started appearing in deals, a [Buying Trigger](/concepts/buying-triggers) that precedes your wins.
* **Refine** — propose changing an existing entity: add a newly discovered pain point to a [Persona](/concepts/personas), update a Motion ICP narrative, attach a new proof point.

Each suggestion carries the proposed content and links to the findings that motivated it, so reviewers see the actual conversation evidence, not just the proposal. Suggestions are reviewed from the dashboard, via API, or by an AI assistant through the [MCP suggestion tools](/mcp/available-tools#analytics--learning):

* **Accept** — the change is applied to the Library and takes effect for every agent and workflow on the next run.
* **Reject** — the proposal is declined and recorded, which also teaches the pipeline what your team considers noise.

You can also create suggestions yourself — from field feedback, a lost-deal review, or an assistant conversation — and route them through the same review flow instead of editing entities directly. That keeps one decision trail for every strategy change, whatever its source.

## Revisions

A Revision is the immutable record of an applied change: what changed, what the content was before and after, when, and from which suggestion it originated. Revisions answer "why does our messaging say this?" months later — you can trace a positioning statement back through the suggestion that proposed it to the calls that motivated it.

## API surface

* `GET /api/v2/suggestion/list`, `GET /api/v2/suggestion/get` — browse the review queue
* `POST /api/v2/suggestion/create`, `POST /api/v2/suggestion/update` — create and edit proposals
* `POST /api/v2/suggestion/accept`, `POST /api/v2/suggestion/reject` — decide
* `GET /api/v2/revision/list`, `GET /api/v2/revision/get` — read the change history