> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning & Publishing

> Edit a draft freely, publish to freeze a version, and roll back instantly if you need to.

An agent always has two states: the **draft** you're editing and the **published** version your
callers actually reach. Every change — persona, knowledge, skills, guardrails, playbooks — lands in
the draft. Phone and chat keep serving the last published version until you publish again.

<Warning>
  A change is invisible to live calls until you **publish**. "Works in the tester, fails on the phone"
  almost always means the draft has unpublished edits. Confirm with the pre-publish diff before you
  ship.
</Warning>

## Publishing freezes a version

`POST /agents/{id}/publish` compiles the current draft and writes a new **frozen** version — an
immutable snapshot of the compiled config, stamped with a version number, who published it, and an
optional `note`. From that moment, every new call runs that frozen version. Because publishing is a
money-and-callers moment, it accepts an `Idempotency-Key` so a retried request never double-ships.

```bash theme={null}
curl -X POST https://builder.flowyte.com/api/v1/agents/AGENT_ID/publish \
  -H "Authorization: Bearer flowyte_sk_…" \
  -H "Idempotency-Key: 5f3c…" \
  -H "Content-Type: application/json" \
  -d '{"note":"Added after-hours transfer skill"}'
```

## Look before you publish

Two read-only endpoints make the trust moment safe:

* **Diff** — `GET /agents/{id}/versions/{versionId}/diff` lists exactly what changed against the
  current draft (each entry is a `field` with `before`, `after`, and a `kind` of `added`,
  `removed`, or `changed`).
* **Pre-publish report** — `GET /agents/{id}/prepublish-report` shows what the agent **will say**
  and **won't say**, what data leaves the system (which skills send which fields, and where),
  active guardrails, knowledge coverage, and any warnings.

## Rolling back

If a published version misbehaves, `POST /agents/{id}/rollback` with a `versionId` re-points the
live agent at a previous frozen version immediately — no recompile, no redeploy. Browse the history
with `GET /agents/{id}/versions`.

## In the API

| Action                     | Endpoint                                     | Scope          |
| -------------------------- | -------------------------------------------- | -------------- |
| Publish (freeze a version) | `POST /agents/{id}/publish`                  | `agents:write` |
| Roll back to a version     | `POST /agents/{id}/rollback`                 | `agents:write` |
| List version history       | `GET /agents/{id}/versions`                  | `agents:read`  |
| What-changed diff          | `GET /agents/{id}/versions/{versionId}/diff` | `agents:read`  |
| Pre-publish report         | `GET /agents/{id}/prepublish-report`         | `agents:read`  |

<Tip>
  A clean release loop: edit the draft → [test it](/concepts/testing) → read the pre-publish report →
  publish with a `note`. Keep the note descriptive — it's what you'll scan when deciding which version
  to roll back to.
</Tip>