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.

Authorization

ApiKeyAuth

AuthorizationBearer <token>

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

siteId*string

The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.

id*string

The agent id (prefixed agt_).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

status?string

Deprecated

Deprecated: create the version, then put it live with POST …/agents/{id}/go-live. A request that sets it is answered with Deprecation, Sunset and Link headers. Status to create the version with. archived is not assignable at creation; use the status PATCH. Creating as champion archives the previous champion.

Default"draft"

Value in

"draft"
"candidate"
"champion"

displayName?

This version's public-facing name, keyed by language code. Omit the field entirely to inherit it from the agent's most recent version. Omission does not mean "empty" here; it exists specifically so an integrator who doesn't send identity can never blank a live assistant's name by creating a new version. Send an explicit value to change it; an explicit value is never inherited over. On an agent attached to a site, every enabled language the value leaves out (all of them with {}) is saved with the built-in name for that language ("Assistant" in English, "Assistent" in German), and the welcome messages are completed the same way: when the body carries no conversationStarters, they are carried forward from the agent's most recent version first. On such an agent an explicit {} therefore no longer clears the name: each language gets the built-in name. A name you send is kept exactly as sent. Only keys for languages enabled on the site are accepted.

avatarUrl?|

This version's public-facing avatar URL. Same omit-to-inherit rule as displayName: leave the field out to carry the avatar forward from the agent's most recent version; send an explicit URL or null to change or clear it.

enabledCapabilities?array<>

The capabilities this saved state enables: attachment, voice_dictation, quick_replies (suggested replies) and out_of_stock_products (out-of-stock products shown to shoppers, marked as out of stock). All four are off when you omit the field, and an empty list keeps them off. quick_replies and out_of_stock_products are for Shopping assistant agents: on a custom agent the request is refused with 400 invalid_request.

target?|

Where the saved state goes. new (the default) saves it as a new version, optionally named. append saves it on an existing version that can still change: lineId names the version and expectedHeadId the id of its latest saved state as you read it, so a save made by someone else in between is refused with version_changed. A version that has been live or is part of an A/B test is locked and refuses an append with version_locked: save as a new version instead.

Default

{  "mode": "new"}

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/sites/string/agents/string/versions" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "draft"
  }'

curl -X POST "https://example.com/api/v1/sites/string/agents/string/versions" \  -H "Content-Type: application/json" \  -d '{    "status": "draft"  }'

{
  "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"
  }
}

{  "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

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

201application/json

400application/problem+json

401application/problem+json

404application/problem+json

409application/problem+json

429application/problem+json

500application/problem+json

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`