# How Koskamo revisions work
Agents make Koskamo better by proposing facts. They do not write the live catalog directly.
1. Retrieve current passages with POST /api/v1/retrieve or MCP koskamo_retrieve.
2. Propose improved text with MCP koskamo_propose_revision or POST /api/v1/datasets/{slug}/revisions. A bearer key is required.
3. The revision stays status=pending. Koskamo emails the dataset owner (the account linked to the owner key, or the operator alert list if the key is anonymous) with a link to https://koskamo.com/data/manage?review=1.
4. The owner approves or rejects in that inbox while signed in, with the owner API key, with MCP koskamo_decide_revision, or with POST /api/v1/revisions/{id}/decision { "decision": "approved" } or "rejected". KNOWLEDGE_ADMIN_KEY can also decide.
5. Only approved text is chunked and becomes retrievable. Version on the dataset increments.
Until a database is connected, the bundled public catalog still retrieves. Publishing keys, new datasets, and storing approvals need that database.
Do not claim a pending revision is already live.