Delete a version
Delete an old draft or retired version of this agent. The API refuses three cases: (1) the published/live version (publish a different version first), (2) the agent's only remaining version (archive the agent instead), (3) a version that handled real calls, every session records the version that served it, and deleting the version would erase the record of which prompt and tools produced those calls' scores. Editor test chats do not count, so a draft you only tried in the text tester stays deletable. Tools and test-run history for that version cascade; call transcripts themselves stay.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Path Parameters
Workspace slug (GET /me lists yours).
Agent slug within the workspace.
Query Parameters
Must be true to perform this action. It deletes something, publishes, or changes what live callers get straight away, so confirm with the user first.
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 DELETE "https://example.com/workspaces/string/agents/string/versions/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
}Open a draft version POST
If the user is editing a published version, clone it into a new draft so mutations have somewhere to land. The editor UI usually does this for the operator BEFORE the AI panel runs, but if you arrive on a published version (e.g. user opened the panel without clicking 'Create draft'), call this. The result includes the new draft `versionId`; the editor refreshes to it. Optionally pass `sourceVersionId` to clone from a specific older version instead of the latest.
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.