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.
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.
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.
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 |
A clean release loop: edit the draft → test it → 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.