Get a version
Returns a single configuration version. A 404 unless the version exists and belongs to the agent in the path.
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_).
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/api/v1/sites/string/agents/string/versions/string"{ "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" }}Create a version
Saves a configuration of the agent. A saved state is immutable: to change an agent's instructions you save again rather than editing one. By default (`target.mode` `new`) the save opens a new version. With `target.mode` `append` it goes onto an existing version that can still change, and is refused with `version_locked` when that version has been live or is part of an A/B test, or `version_changed` when someone saved on it since you read it. Either way the saved state's `version` is the number of the version it lands on, as the dashboard shows it, and `savedState` its place in that version. Without the deprecated `status` field, saving never puts anything live: use `POST …/agents/{id}/go-live`. That field still accepts `champion`, which archives the agent's previous `champion` version.
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.