Change a version's status
Deprecated: put a version live with `POST …/agents/{id}/go-live`, and stop the answering agent with `POST …/take-offline`. Every answer carries `Deprecation`, `Sunset` (27 April 2027) and `Link` headers. Moves a version through its lifecycle. Only the `status` can change here: the instructions are immutable. Promoting a version to `champion` archives the agent's current champion automatically (at most one champion per agent). Moving the champion of the agent that answers on its site to another status is refused with `agent_answers_on_site`: take the agent offline (`POST …/take-offline`), or put another version live (`POST …/go-live`), instead. Promoting a version of the agent that answers on its site runs the go-live readiness check and is refused with `version_not_ready` when a condition is unmet.
Deprecated
Authorization
ApiKeyAuth A WorkOS org-scoped API key, created from the dashboard's organization settings page. Identifies the tenant every read and write is scoped to. Missing, malformed, unknown, revoked, expired, or non-organization-owned keys all return 401 (no distinction, so the response can't be used to probe which keys or org ids exist).
In: header
Path Parameters
The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.
The agent id (prefixed agt_).
The configuration version id (prefixed agtv_).
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X PATCH "https://example.com/api/v1/sites/string/agents/string/versions/string" \ -H "Content-Type: application/json" \ -d '{ "status": "champion" }'{ "data": { "id": "string", "agentId": "string", "lineId": "string", "version": 0, "label": "string", "savedState": 0, "savedStateLabel": "string", "status": "draft", "lifecycleStatus": "live", "locked": true, "lockedReason": "live", "engine": "string", "capabilities": [ "attachment" ], "startersAlignment": "left", "showStarterQuestions": true, "avatarUrl": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }}Get a version
Returns a single configuration version. A 404 unless the version exists and belongs to the agent in the path.
Rename a version
Names a version of the agent, as Rename does in the dashboard. A name is a label, not configuration: no saved state changes, and a locked version (one that has been live or is part of an A/B test) can be renamed too. `null` or an empty name clears it, so the version reads as `V` followed by its number again. The version is the `lineId` of its saved states.