# Staging & Publishing for Agents API Guide The Staging feature lets you make changes to an agent's configuration in a staging environment before they reach your end-users and agent integrations. Nothing you change in Staging goes live until you publish. You can also revert any previously published changes at any time. This functionality protects end-users from seeing incomplete or broken configurations. Think of Staging as a space where you can experiment, iterate, and collaborate with others freely, and only promote changes to Production when everything is ready. --- ## How It Works Every agent has two environments: **Staging** and **Production**. | Environment | Who Sees It | What It's For | |---|---|---| | **Production** | End-users & Agent Integrations | The current live configuration | | **Staging** | Editors only | A workspace to prepare the next set of changes | --- ## Editing in Staging Make your changes to the agent — update the name, description, knowledge sources, tools, guardrails, or any other configuration. All edits apply to Staging only, allowing you to review and test before propagating them to your published agent. Your staging changes are preserved until you publish them, so you can work across multiple sessions without losing progress. :::tip Working across sessions You might update the system prompt on Monday, add a new knowledge source on Wednesday, and adjust the guardrails on Friday — all in Staging — and only publish the full set of updates once you're happy with how everything works together. ::: ### Endpoints That Require a Follow-up Publish The endpoints below modify the **Staging** state only. None of these changes reach end-users until `POST /publish` is called. | Method | Endpoint | Description | |---|---|---| | `PUT` | `/api/v2/agents/{agent_id}` | Update agent | | `POST` | `/api/v2/agents/{agent_id}/instructions` | Create instructions | | `PUT` | `/api/v2/agents/{agent_id}/instructions` | Update instructions | | `DELETE` | `/api/v2/agents/{agent_id}/instructions/{instruction_id}` | Delete instruction | | `POST` | `/api/v2/agents/{agent_id}/corpora` | Bulk connect corpora | | `DELETE` | `/api/v2/agents/{agent_id}/corpora` | Bulk disconnect corpora | | `POST` | `/api/v2/agents/{agent_id}/corpora/{corpus_id}` | Connect corpus | | `PUT` | `/api/v2/agents/{agent_id}/corpora/{corpus_id}` | Update corpus connection | | `DELETE` | `/api/v2/agents/{agent_id}/corpora/{corpus_id}` | Delete corpus connection | | `POST` | `/api/v2/agents/{agent_id}/tools/{tool_id}/enable` | Enable tool | | `DELETE` | `/api/v2/agents/{agent_id}/tools/{tool_id}/disable` | Disable tool | | `PATCH` | `/api/v2/agents/{agent_id}/tools/{tool_id}/actions/{action_id}` | Update action config | | `POST` | `/api/v2/agents/{agent_id}/tools/{tool_id}/actions/{action_id}/enable` | Enable action | | `POST` | `/api/v2/agents/{agent_id}/tools/{tool_id}/actions/{action_id}/disable` | Disable action | | `PATCH` | `/api/v2/agents/{agent_id}/guardrails` | Enable/disable guardrail | | `PUT` | `/api/v2/agents/{agent_id}/access` | Update access level | | `POST` | `/api/v2/agents/{agent_id}/annotates` | Update tags | | `POST` | `/api/v2/agents/{agent_id}/sharepoint/folder` | Create a new SharePoint folder connection | | `PUT` | `/api/v2/agents/{agent_id}/sharepoint/folder` | Update the existing SharePoint folder connection | | `DELETE` | `/api/v2/agents/{agent_id}/sharepoint/folder` | Delete the SharePoint folder connection | --- ## Reviewing Changes Before Publishing Before publishing, you can review a side-by-side comparison of what has changed between Staging and Production. The comparison covers: - Agent settings (name, description, model configuration, etc.) - Instructions - Knowledge sources - Tools - Guardrails Each changed field shows the current Production value alongside the new Staging value, so you can verify everything looks correct before it goes live. :::info Only differences are shown If a field is unchanged, it will not appear in the comparison — only the fields that differ between Staging and Production are highlighted. This keeps the review focused and easy to scan, even when your agent has many configuration options. ::: ### Endpoint to Preview Before Publishing | Method | Endpoint | Description | |---|---|---| | `GET` | `/api/v2/agents/{agent_id}/staging-diff` | Preview a full diff of all changes in Staging relative to Production. Returns `has_changes: false` when there is nothing to publish. | --- ## Publishing When you are satisfied with your staging changes, publish them to make them live. Production is updated instantly and a snapshot of the changes is saved to your publish history. :::note Nothing to publish? If Staging is already identical to Production, there is nothing to publish. ::: :::warning Review before you publish Publishing is instant. Once confirmed, changes immediately reflect on the published agent. Always review using the staging diff before proceeding. ::: ### Endpoint for Publish | Method | Endpoint | Description | |---|---|---| | `POST` | `/api/v2/agents/{agent_id}/publish` | Publish all staging changes to the Production agent. Blocked when Staging is identical to Production. | ![staging.png](https://api.apidog.com/api/v1/projects/998119/resources/375770/image-preview) --- ## Publish History Every publish is recorded automatically. Each entry in your publish history shows who published, when, and a summary of what changed. You can browse this history at any time. :::tip Why publish history matters The publish history is useful for auditing purposes — for instance, if you need to understand who made a particular change and when. It also serves as the foundation for the Revert feature, since each history entry represents a known-good snapshot you can revert to. ::: ### Endpoint for Publish | Method | Endpoint | Description | |---|---|---| | `POST` | `/api/v2/agents/{agent_id}/publishes` | Publish all staging changes to the Production agent. Blocked when Staging is identical to Production. | --- ## Rollback/Restore a Publish If you need to roll back a change or return to an earlier configuration, you can restore any entry in your publish history. This is useful if a newly published configuration causes unexpected behavior. You are not limited to rollback only the most recent publish — you can select any entry from the full history and restore it. ![rollback2.png](https://api.apidog.com/api/v1/projects/998119/resources/375890/image-preview) ### Preview before rollback/restore Before committing to a rollback, you can preview what exactly changed in that publish and what would change in Staging if you rollback so there are no surprises. The preview shows the side-by-side diff view, it compares the selected history entry against the current state of Staging, so you can see exactly what will be rolled back before you commit. | Method | Endpoint | Description | |---|---|---| | `GET` | `/api/v2/agents/{agent_id}/publishes/{change_track_id}/diff` | Preview what restoring this publish would change in Staging and in Production if subsequently published. | | `GET` | `/api/v2/agents/{agent_id}/publishes/{change_track_id} ` | Side-by-side diff of what changed in that publish | ### How rollback works It restores the changes introduced by that deployment onto Staging and rollbacks any changes made after that. Production is not affected immediately. This gives you a chance to review the restored changes before it goes live. Once satisfied, publish to make the rollback live in Production. | Method | Endpoint | Description | |---|---|---| | `PUT` | `/api/v2/agents/{agent_id}/rollback` | Restores the changes made at a given `change_track_id` onto the Staging environment. Production is not affected until `POST api/v2/agents/{agent_id}/publish` is called. | :::caution Production is not immediately affected Rollback does not immediately update Production. You are always in control of when changes go live. :::