Skip to main content
PATCH
Save agent draft

Authorizations

​
Authorization
string
header
required

Organization API key, generated in studio.sidenet.ai. Backend only — never in a browser.

Path Parameters

​
id
string
required
Example:

"6f1c0f4e-2b7a-4a51-9a2f-0c9d1b3e5a10"

Body

application/json
​
instructions
object[]

The agent's system prompt, as an ordered list of blocks. Each entry is one of: { type: "text", content } — inline text; { type: "prompt_block", content, rules? } — inline text with an optional display condition; { type: "prompt_block_ref", id } — a reference to a /v1/prompt-blocks block in the same organization. Content may contain {{variable}}, {{a.b}} and {{variable || 'default'}} placeholders, resolved per request from the chat body's variables plus the now.* builtins; an unsupplied placeholder is left visible. rules is a { operator: "AND"|"OR", conditions: [...] } group (max 3 levels) — the block is included only when it evaluates true. On the draft a ref floats to the block's active version; publishing PINS it, so a published agent version keeps its exact prompt until you republish (see /v1/prompt-blocks/:id/rollout). Pins are server-owned — do not send versionId.

Example:
​
model_slug
string

The concrete model to run, e.g. anthropic/claude-sonnet-4-5. Ignored when policy_slug is set.

Example:

"anthropic/claude-sonnet-4-5"

​
policy_slug
string

A routing policy to run instead of a fixed model, e.g. policy/fastest-sonnet. Overrides model_slug when set.

Example:

"policy/fastest-sonnet"

​
model_options
object

Model-level options passed through to the router — reasoning effort, native provider options, and the like.

Example:
​
model_settings
object

Generation settings: temperature, maxTokens, and similar.

Example:
​
max_steps
integer

Max LLM round-trips per run for the agentic tool loop. The final step is forced tool-free so runs always end with a text answer. null = platform default (20).

Required range: 1 <= x <= 100
Example:

8

​
tool_search
object | null

Tool search for agents with a large roster (a big API import, a wide MCP server, several connected-app toolkits). ON BY DEFAULT: with more than threshold tools attached to the agent (default 40, connected-app tools included; platform tools such as the workflow builder are not counted), only an always-loaded set stays in the prompt and the rest is reached through two meta-tools: search_tools (keywords → matching tool names and descriptions) and load_tool (exact names → callable for the rest of the conversation). One search surface per agent: API, MCP and connected-app tools share it. providers scopes it to a list of provider ids (API / MCP tools) and connected-app toolkit slugs — only their tools are searchable, everything else stays in the prompt; omit it to search the whole roster. The always-loaded set is the rendering components, the large-response retrieval tools, the workflow builder, every tool with require_approval, the connection tools, discovery: false entries, and whatever always_loaded names (tool names or ids). top_k is the number of search results (1–20, default 8). show_catalog: true also lists every searchable tool's name and a short description in the prompt, trading tokens for one fewer round-trip — worth it for a few dozen tools, not for hundreds. Under the threshold, or with enabled: false, your own API and MCP tools all go into the prompt and connected-app toolkits keep their automatic pooling above ~15 direct tools (see agentTools). Send null to go back to the platform default.

Example:
​
guardrails
object[] | null

Guardrails: safety checks that run on every turn of this agent, one entry per kind (see the guardrails guide). kind: pii (personal data in messages: emails, phone numbers, cards, ids…), moderation (hate, harassment, violence, sexual content, self-harm), prompt_injection (jailbreaks and attempts to override the instructions), system_prompt_scrub (the agent quoting its own instructions back), language (messages outside the target languages) and unicode (control characters and odd whitespace in the user message). mode says what happens when a guardrail fires: warn (default) records the violation and lets the turn continue; block ends the turn with an error the chat shows. All kinds but unicode ask a small judge model; that spend bills the organization's "LLM Judges" group, never a customer group, and a judge-backed guardrail is skipped (with a warning in the rebuild report) when the organization has no judge key. In block mode a judge that fails also stops the turn (fail-closed); in warn mode it lets the message through. enabled: false keeps an entry but turns it off. options tunes the kind — every key optional, unknown keys are rejected: threshold (0–1 confidence to fire; the defaults are 0.6 for pii, 0.5 for moderation, 0.7 for prompt_injection and language), model (a judge model slug, default a small fast one), instructions (custom judge instructions, up to 4000 characters), strategy (an action other than warn/block when the guardrail fires: redact or filter for pii and system_prompt_scrub, rewrite or filter for prompt_injection, filter for moderation, translate or detect for language — mode then only decides what a judge failure does), stage (input, output or both; pii and moderation only, default input), detection_types (pii, prompt_injection), redaction_method (pii: mask, hash, remove, placeholder; system_prompt_scrub: mask, placeholder, remove), categories (moderation), target_languages and min_text_length (language), custom_patterns and placeholder_text (system_prompt_scrub), strip_control_chars, collapse_whitespace, preserve_emojis and trim (unicode, all default true). Send null to remove every guardrail.

Maximum array length: 12
Example:
​
workflows
object[]

Workflows the agent can run, as { workflow_id, config? } entries. workflow_id is the /v1/workflows id and must belong to the same organization. The workflow's ACTIVE version is always what runs, so activating a new version reaches the agent on its next turn with no republish. The agent-facing tool name and its description come from the workflow itself — the model calls it as workflow-<workflow name>. The whole workflow runs inside one tool call, and its step progress is streamed to the client as data-tool-workflow / data-tool-workflow-step parts by /v1/chat.

Example:
​
skills
object[] | null

Skills the agent can load, as { skill_id } entries. skill_id is the /v1/skills id and must belong to the same organization. A skill is a named block of instructions the agent loads on demand — it calls its skill tool with the name when the skill's description says to — instead of carrying the text in every prompt. The agent always gets the skill's ACTIVE version, so publishing a new one reaches the agent on its next turn with no republish; a skill that is not published yet is skipped and reported in the rebuild summary. Send null to remove every skill.

Example:
​
agentTools
object[]

Tools assigned to the agent. Each entry is { tool_id, provider_id?, config?, composio_connected_account_id?, discovery?, loop_responses?, require_approval? }. discovery (integration tools only) controls where the tool schema lives at runtime: true puts it behind the agent's search_tools/load_tool discovery tools, false pins it into the prompt, and unset lets the platform decide — small toolkits stay in the prompt, large ones (beyond ~15 total tools) become discoverable so the prompt is not flooded with schemas. require_approval: true pauses every call to that tool for human approval: the chat stream emits a data-tool-call-approval chunk instead of executing (carrying a model-written reason sentence for the approval card), and the client continues the run by POSTing /v1/chat with the approval field. Set loop_responses: true on a tool to let one call cover a whole result set: it gains _fields (project only the fields needed), _all_pages (fetch and merge every page) and _for_each (call once per value of a parameter and merge the rows), and the agent is given the large-response retrieval tools automatically. Because those re-issue the request, enable it only on tools whose endpoint is safe to call repeatedly.

Example:
​
name
string

The agent's name. Agent-level, not versioned — it takes effect immediately, with no publish, and is what other agents see when this one is a subagent.

Example:

"Support agent"

​
description
string

The agent's description. Agent-level, not versioned — same immediate effect as name. Send null to clear it.

Example:

"Answers billing and account questions"

​
scorers
object[]

Scorers for this version. Each entry: name (unique key), scorerType (catalogue id), model (judge slug, LLM scorers only), sampling_rate (0-1, share of eligible runs scored, default 1), options, and an optional filter — a predicate over the run, evaluated before sampling, over requestContext.* (groupId, environment, copilotId, source, userId…), entity.*, threadId, resourceId. Operators: eq/ne/lt/lte/gt/gte (left/right as { path } or { literal }), in/notIn (value, set), exists/notExists (path), truthy/falsy (value), and/or (args), not (arg). An invalid filter answers 400.

Example:
​
agents
object[]

Subagents this one may delegate to.

Example:
​
memory
object | null

Memory settings of this version, as { options } — see the memory guide. options: lastMessages (recent messages read back, default 10), generateTitle (first title from the first message; true, false or { model, instructions }), semanticRecall (true, false or { topK, messageRange, scope }), workingMemory (true, false or { enabled, scope, template | schema, agentManaged } — scope: "resource", the default, is one record per user shared by every conversation and automation run), observationalMemory (true, false or { model, activateAfterIdle, retrieval, observation: { messageTokens, bufferTokens, bufferActivation, blockAfter, bufferOnIdle, manageWorkingMemory, threadTitle, instruction, activateAfterIdle }, reflection: { observationTokens, bufferActivation, blockAfter, activateAfterIdle, instruction } }; its scope is thread only). Unknown keys and out-of-range values answer 400 naming the path. Null = platform defaults. Model slugs bill the organization's key.

Example:

Response

The saved draft, and the agent record it belongs to

​
agent
object

The agent after the save — name/description reflect this call, and the version summary says whether the draft now differs from what is published.

​
draft
object

The whole draft after the merge, not just the fields you sent. rev has been bumped by the DB.