Check what blocks publishing
Dry-run the publish validator against the current version WITHOUT publishing. Returns { errorCount, riskCount, diagnostics }, errors block publish, risks don't. Call this before publish_version to see and fix blockers first; a result with errorCount 0 means publish_version won't fail validation.
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.
Header Parameters
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.
1 <= length <= 255Request 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/validate" \ -H "Content-Type: application/json" \ -d '{}'{
"errorCount": 0,
"riskCount": 0,
"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
}Update an agent from a partial spec PATCH
Make the agent's draft match a spec in one call. The spec is what export_agent_spec returns: export, edit, apply. Each field is written by the op named here, which checks it: name, description, systemPrompt (update_system_prompt), greeting, returningGreeting, outboundGreeting, channels (set_agent_channels), brief (set_brief), voice, fallbackVoice, model, fallbackModel, sttModel, judgeModel, callEngine (set_realtime), speech (set_speech_settings), turnTaking (set_turn_detection), behaviour (set_behaviour_settings), keyterms, pronunciations, vocabulary, callerMemory, guardrails (set_safety_guardrails), agentResponseGuardrails (set_agent_response_guardrails), settings (update_agent_settings: disclosures, privacy, retention, timezone), callHandling, overflowForwardNumber, closedMessage, answeringHours, closedEarly (set_manual_close), callerRouting (set_caller_routing). Lists match by name: builtinTools, httpTools (add the tool, then the set_tool_* ops), toolOrder (reorder_tools), variables ({name, value}; {name, default} for a value injected per call; {name, secret: true}, set with set_secret_variable), workflow {preCall, callEnded, postCall}, postCallAnalysis {summary, fields}, knowledge ({name, text}, {name, url}, or {name, file: true}, uploaded in the app), scenarios (create_scenario inputs). An omitted field is left as it is; null resets it to the default. replace: true makes the spec the whole config: a key left out of an object field is reset, and a list item left out is deleted, except that knowledge-search tool, which stays while the agent has knowledge. Only what differs is written, and every step is checked before the first write. Deletes run last. If a step fails, every step before it is undone and the error names the step. If the latest version is published, a draft is opened first. dryRun: true returns the plan only. Steps that change live calls at once or delete something need confirm: true after the user agrees; the refusal names them. Returns the validate_agent result. Never publishes.
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.