Versions
Versions

Discard the draft's changes

Discard the current draft's changes by re-copying the live published version onto it, prompt, tools, voice and model config all revert to exactly what is published. Use when the operator wants to throw away the draft's edits and start again from the live version. Only works when there is a draft above a published version.

POST
/workspaces/{workspace}/agents/{agent}/versions/revert

Authorization

bearerAuth
AuthorizationBearer <token>

A personal access token from Settings > API tokens.

In: header

Path Parameters

workspace*string

Workspace slug (GET /me lists yours).

agent*string

Agent slug within the workspace.

Header Parameters

Idempotency-Key?string

A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.

Length1 <= length <= 255

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

application/problem+json

curl -X POST "https://example.com/workspaces/string/agents/string/versions/revert" \  -H "Content-Type: application/json" \  -d '{}'
{
  "versionId": "string",
  "property1": null,
  "property2": null
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}

Publish the draft POST

Publish the current draft so the next live call uses it. Runs the full validator first (same rules the editor's Health page surfaces), then checks whether this version's test suite has run green on THIS version. On a validator failure the result is `{ ok: false, diagnostics }`, read them, fix them, retry. On a suite warning it is `{ ok: false, code: "suite_not_green", suite: { untested, failing, inconclusive } }`, show the operator the scenario names, then either run them with `run_all_tests`, or if the operator chooses to publish anyway, retry with `acknowledgeSuite: true`. Don't publish without explicit user intent.

Add a built-in tool POST

Add a built-in tool from the fixed template set. Built-in tools have their own runtime handler, so there is no URL, header, param or requires to set. Call list_builtin_tools first: it lists every template with what it does and the arguments the agent passes, and gives one template's full description. The everyday ones: `transfer_to_human` (escalates the call to a human), `call_and_connect` (rings a number the caller asks for and connects them; Australian mobiles, landlines and 13, 1300 and 1800 numbers only, never emergency, overseas or 19 numbers; with `stay_on_the_line: true` in its config the agent stays on the call with both people, otherwise it transfers and leaves; on an eval or a chat nobody is rung), `end_call` (politely hangs up), `take_a_message` (emails the caller's name, number and message to the routed inbox), `book_meeting` (a Cal.com booking), `search_knowledge_base` (grounds answers in the agent's knowledge base), `get_current_time` (a fresh clock reading partway through a call; every call already opens with the local date and time), `calculate` (works out a sum exactly, such as adding prices, a rate times hours or adding GST, and returns the answer in figures and in words; give it to any agent that quotes a total, because the model's own arithmetic slips), `escalate_emergency` (one fixed dial-triple-zero line, then a human, never triage), `send_text_message` (texts the caller a link they asked for), `request_details_form` + `check_captured_details` (texts a short form for written values such as an email), `send_order_verification_code` + `verify_order_code` (a 6-digit order OTP), `press_keys` (sends keypad tones, for a transfer prompt or an IVR menu), `capture_digits` (reads digits the caller keys in; needs `keypadInputEnabled` under call handling or it returns `dtmf_reception_disabled`), `add_to_do_not_call` (puts an inbound caller who opts out on the workspace do-not-call list; campaign calls and lead callbacks already have it) and `note_customer_answers` (asks the `questions` in its config in order before an offer). The rest drive demos and integrations, each listed by list_builtin_tools: the live second screen (`send_live_link` and the tools that push to its page), Square pricing and payment links, Cliniko intake and booking, the /build interview and website-guide tools, role-play, voice preview and caller playback. A template that reaches a third party takes its keys in config, always as a reference to a SECRET variable: set_builtin_config documents each template's config, and each Cliniko tool takes `api_key`, `shard` and `contact_email`. You can set `displayName` for the operator-facing label, and call `set_tool_description` afterwards for a more specific description. `name` defaults to the template name, which is right for the common case. An agent carries one tool per template: the validator blocks publish on a second, and this op refuses one rather than adding it.