Restore an agent definition version
POST /api/agent-definitions/{id}/versions/{versionId}/restore
Restores a previous version of an agent definition by publishing its configuration as a new version. History is preserved: the prior published version is superseded rather than overwritten. When the restored configuration already matches the current configuration, no new version is created. A restore sets the agent’s MCP connections to the version’s, so an API key needs the agents:write and mcp:write scopes and no brand or workspace restriction.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The unique identifier of the agent definition.
The unique identifier of the version to restore.
Responses
Section titled “ Responses ”The version was restored and a new published version was recorded, or the restore was a no-op.
The result of restoring a version. A restore creates a new published version rather than mutating history. When the restored content matches the current content, no new version is created.
object
Identifier of the newly published version, or of the existing current version when the restore was a no-op.
Example
v9a8b7c6-5432-10fe-dcba-0987654321abWhether a new version was created. False when the restored content already matched the current content.
Example
trueThe version number that was restored.
Example
2The caller may not restore this agent. An agent provided by oHallo answers with code: "platform_agent". People need the owner or admin role. An API key needs the agents:write and mcp:write scopes, and a key without one of them receives missing_scopes; a key restricted to a brand or workspace receives code: "key_lock".
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]No agent definition or version exists with the given ID in the authenticated tenant.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]