Skip to content
OperadeDocs

Search documentation

Type to search documentation.

DashboardContact
Documentation
Copy page
Open raw Markdown

Publish an agent

Validate an agent draft and create a new immutable branch version.

Endpoint

POST/api/v1/workspaces/{workspace_id}/agents/{agent_id}/publish

Authentication

Operation classAuthenticationMinimum roleAPI key
customer-apiBearer API key or dashboard session cookie; dashboard mutations also require X-CX-Request: 1.memberAllowed

Parameters

NameInTypeRequiredDescription
workspace_idpathstringYes—
agent_idpathstringYes—
branch_idquerystring or nullNo—

Request body

application/json request schema

Field pathTypeReferenceFormatNullableRequiredEnumDescription
$object or nullPermintaanPublish—YesNo——
descriptionstring——NoNo——

Example

cURL
curl --request POST 'https://operade.ai/api/v1/workspaces/ws_demo/agents/agt_demo/publish' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"description":"Example release"}'
Request body JSON
{
  "description": "Example release"
}

Responses

StatusDescriptionContent
4XXHandled client errorapplication/json: ErrorResponse
201Successful Responseapplication/json: AgentPublishResponse

4XX application/json response schema

Field pathTypeReferenceFormatNullableRequiredEnumDescription
$objectErrorResponse—NoYes——
errorobjectErrorItem—NoYes——
error.codestring——NoYes——
error.detailsobject——NoNo——
error.messagestring——NoYes——

201 application/json response schema

Field pathTypeReferenceFormatNullableRequiredEnumDescription
$objectAgentPublishResponse—NoYes——
branch_idstring——NoYes——
configobjectConfigAgen—NoYes——
config.agentobjectAgentConfig—NoNo——
config.agent.first_messagestring——NoNo——
config.agent.languagestring——NoNo"id", "en"—
config.agent.promptobjectPromptConfig—NoNo——
config.agent.prompt.built_in_toolsobjectBuiltInTools—NoNo—`None` berarti mati. Bentuk ini ikut ElevenLabs, dan ia bertetangga dengan `tool_ids` di dalam `agent.prompt` — bukan di `agent` — sesuai kontrak resminya. Cuma `end_call` yang ada. Sisanya (`transfer_to_number`, `play_keypad_touch_tone`, `voicemail_detection`) semuanya soal telepon, `transfer_to_agent` butuh F6, dan `language_detection` butuh multi-bahasa yang sengaja ditunda.
config.agent.prompt.built_in_tools.end_callobject or nullSystemTool—YesNo—Tool bawaan platform: tidak punya URL, tidak punya rahasia, dan tidak bisa dibuat pelanggan. `description` kosong berarti pakai kalimat bawaan kita — bentuk yang sama dengan ElevenLabs (docs/03 `SystemToolConfig`).
config.agent.prompt.built_in_tools.end_call.descriptionstring——NoNo——
config.agent.prompt.ignore_default_personalityboolean——NoNo——
config.agent.prompt.knowledge_basearray<DokumenTerpasang>——NoNo——
config.agent.prompt.knowledge_base[]objectDokumenTerpasang—NoYes—Satu dokumen knowledge base yang dipasang ke agen ini. Nama field mengikuti `KnowledgeBaseLocator` ElevenLabs (docs/03), termasuk menyimpan `name` di sini walau bisa dibaca dari tabel dokumen. Itu disengaja: versi agen harus tetap terbaca enam bulan kemudian, bahkan kalau dokumennya sudah dihapus — tanpa nama, riwayat versinya cuma memuat id yang tidak berarti apa-apa bagi siapa pun.
config.agent.prompt.knowledge_base[].idstring——NoYes——
config.agent.prompt.knowledge_base[].namestring——NoNo——
config.agent.prompt.knowledge_base[].typestring——NoNo"text", "file", "url"—
config.agent.prompt.knowledge_base[].usage_modestring——NoNo"auto", "prompt"—
config.agent.prompt.llmstring——NoNo"gpt-5-mini", "gpt-5", "deepseek-v4-flash", "claude-haiku-4-5", "claude-sonnet-4-5", "gemini-2.5-flash"—
config.agent.prompt.max_tokensinteger——NoNo——
config.agent.prompt.promptstring——NoNo——
config.agent.prompt.ragobjectRagConfig—NoNo—Angka bawaannya sama persis dengan ElevenLabs (docs/03 `RagConfig`), kecuali jumlah potongan yang mereka biarkan sampai 20. Lima cukup untuk pertanyaan CS, dan tiap potongan tambahan dibayar tiap giliran.
config.agent.prompt.rag.enabledboolean——NoNo——
config.agent.prompt.rag.max_documents_lengthinteger——NoNo——
config.agent.prompt.rag.max_retrieved_rag_chunks_countinteger——NoNo——
config.agent.prompt.rag.max_vector_distancenumber——NoNo——
config.agent.prompt.temperaturenumber——NoNo——
config.agent.prompt.tool_idsarray<string>——NoNo——
config.agent.prompt.tool_ids[]string——NoYes——
config.conversationobjectConversationConfig—NoNo——
config.conversation.max_duration_secondsinteger——NoNo——
config.conversation.text_onlyboolean——NoNo——
config.guardrailsobjectGuardrailsConfig—NoNo——
config.guardrails.contentobjectContentGuardrails—NoNo——
config.guardrails.content.categoriesobjectContentCategories—NoNo——
config.guardrails.content.categories.harassmentobjectContentCategory—NoNo——
config.guardrails.content.categories.harassment.is_enabledboolean——NoNo——
config.guardrails.content.categories.harassment.thresholdstring——NoNo"low", "medium", "high"—
config.guardrails.content.categories.medical_and_legal_informationobjectContentCategory—NoNo——
config.guardrails.content.categories.medical_and_legal_information.is_enabledboolean——NoNo——
config.guardrails.content.categories.medical_and_legal_information.thresholdstring——NoNo"low", "medium", "high"—
config.guardrails.content.categories.profanityobjectContentCategory—NoNo——
config.guardrails.content.categories.profanity.is_enabledboolean——NoNo——
config.guardrails.content.categories.profanity.thresholdstring——NoNo"low", "medium", "high"—
config.guardrails.content.categories.religion_or_politicsobjectContentCategory—NoNo——
config.guardrails.content.categories.religion_or_politics.is_enabledboolean——NoNo——
config.guardrails.content.categories.religion_or_politics.thresholdstring——NoNo"low", "medium", "high"—
config.guardrails.content.categories.self_harmobjectContentCategory—NoNo——
config.guardrails.content.categories.self_harm.is_enabledboolean——NoNo——
config.guardrails.content.categories.self_harm.thresholdstring——NoNo"low", "medium", "high"—
config.guardrails.content.categories.sexualobjectContentCategory—NoNo——
config.guardrails.content.categories.sexual.is_enabledboolean——NoNo——
config.guardrails.content.categories.sexual.thresholdstring——NoNo"low", "medium", "high"—
config.guardrails.content.categories.violenceobjectContentCategory—NoNo——
config.guardrails.content.categories.violence.is_enabledboolean——NoNo——
config.guardrails.content.categories.violence.thresholdstring——NoNo"low", "medium", "high"—
config.guardrails.content.execution_modestring——NoNo"streaming", "blocking"—
config.guardrails.content.trigger_actionobjectTriggerAction—NoNo——
config.guardrails.content.trigger_action.feedbackstring——NoNo——
config.guardrails.content.trigger_action.typestring——NoNo"end_call", "retry"—
config.guardrails.customobjectCustomGuardrails—NoNo——
config.guardrails.custom.configsarray<CustomGuardrail>——NoNo——
config.guardrails.custom.configs[]objectCustomGuardrail—NoYes——
config.guardrails.custom.configs[].execution_modestring——NoNo"streaming", "blocking"—
config.guardrails.custom.configs[].history_message_countinteger——NoNo——
config.guardrails.custom.configs[].idstring——NoYes——
config.guardrails.custom.configs[].is_enabledboolean——NoNo——
config.guardrails.custom.configs[].modelstring——NoNo——
config.guardrails.custom.configs[].namestring——NoNo——
config.guardrails.custom.configs[].promptstring——NoNo——
config.guardrails.custom.configs[].trigger_actionobjectTriggerAction—NoNo——
config.guardrails.custom.configs[].trigger_action.feedbackstring——NoNo——
config.guardrails.custom.configs[].trigger_action.typestring——NoNo"end_call", "retry"—
config.guardrails.focusobjectToggleGuardrail—NoNo——
config.guardrails.focus.is_enabledboolean——NoNo——
config.guardrails.prompt_injectionobjectToggleGuardrail—NoNo——
config.guardrails.prompt_injection.is_enabledboolean——NoNo——
config.guardrails.versionstring——NoNo"1"—
config.platform_settingsobjectPlatformSettings—NoNo——
config.platform_settings.analysis_llmstring——NoNo"gpt-5-mini", "gpt-5"—
config.platform_settings.data_collectionobject——NoNo——
config.platform_settings.evaluationobjectEvaluationSettings—NoNo——
config.platform_settings.evaluation.criteriaarray<EvaluationCriterion>——NoNo——
config.platform_settings.evaluation.criteria[]objectEvaluationCriterion—NoYes——
config.platform_settings.evaluation.criteria[].conversation_goal_promptstring——NoYes——
config.platform_settings.evaluation.criteria[].idstring——NoYes——
config.platform_settings.evaluation.criteria[].namestring——NoYes——
config.platform_settings.sentiment_analysisobjectSentimentAnalysisSettings—NoNo——
config.platform_settings.sentiment_analysis.enabledboolean——NoNo——
config.platform_settings.testingobjectTestingSettings—NoNo——
config.platform_settings.testing.attached_testsarray<AttachedTest>——NoNo——
config.platform_settings.testing.attached_tests[]objectAttachedTest—NoYes——
config.platform_settings.testing.attached_tests[].test_idstring——NoYes——
config.platform_settings.testing.attached_tests[].workflow_node_idstring or null——YesNo——
config.platform_settings.topic_discoveryobjectTopicDiscoverySettings—NoNo——
config.platform_settings.topic_discovery.enabledboolean——NoNo——
config.proceduresarray<object>——NoNo——
config.procedures[]object——NoYes——
config.workflowobject or null——YesNo——
descriptionstring——NoYes——
guardrail_errorsarray<JsonValue>——NoYes——
guardrail_errors[]referenceJsonValue—NoYes——
version_idstring——NoYes——

Response example

Response body JSON
{
  "version_id": "string",
  "branch_id": "string",
  "description": "string",
  "config": {},
  "guardrail_errors": []
}

Errors

Reviewed common and route-declared errors are summarized here; the list is not exhaustive. Start with the distributed error index to find each code's canonical domain page.

StatusCodeDescription
401unauthenticatedAuthentication is missing, invalid, or revoked.
403forbiddenThe authenticated caller does not have access to this operation.
404not_foundThe requested workspace resource was not found.
422validation_failedThe request did not pass field or business validation.
409conflict_stale_draftThe draft is based on an older immutable version.
409nothing_to_publishThere is no valid draft change to publish.
On this page
  1. Endpoint
  2. Authentication
  3. Parameters
  4. Request body
  5. application/json request schema
  6. Example
  7. Responses
  8. 4XX application/json response schema
  9. 201 application/json response schema
  10. Response example
  11. Errors
  12. Related operations