# Knowledge bases

| Method | Path | Body or result |
|---|---|---|
| GET / POST | `/knowledge_bases` | List bases / create with `{ "name": "docs" }` |
| GET / DELETE | `/knowledge_bases/:name` | Read a base / delete when unreferenced |
| PATCH | `/knowledge_bases/:name/entries/:entry` | `{ "content": "# Refunds\n..." }` — creates the entry or replaces it |
| GET | `/knowledge_bases/:name/entries/:entry` | The entry, with its stored Markdown; `?version=N` for one from its history |
| DELETE | `/knowledge_bases/:name/entries/:entry` | Delete an entry |
| GET | `/knowledge_bases/:name/changes` | What preview changed that live does not have, with `conflict` per entry |
| POST | `/knowledge_bases/:name/publish` | Take preview's changes to this base live |
| GET | `/knowledge_bases/:name/history` | Every version that reached live, newest first |

Entry reads and writes, `changes` and `publish` take `environment` (a query
parameter, or a body field on writes): `preview`, the default, or `live`. A
write in preview is answered from there only and goes live when preview is
published; `"environment": "live"` writes live directly. See
[Preview and live](https://vatio.ai/docs/knowledge#preview-and-live).

`publish` answers 409 with `error_key: "knowledge_conflict"` when live changed
one of those entries after preview did, and 422 `nothing_to_publish`
when there is nothing to take live. The old `snapshots`,
`snapshots/:number/rollback`, `sites` and `refresh` paths answer 410.