Skip to content
Subako Docs
English
English日本語Not translated
Esc
↑↓navigate↵open⌘Jpreview

Publish an agent version

A version is immutable once published: a change is a new version, and sessions already running an older one keep it.

POST/v1/agents/{agent_id}/versions
Authorization
AuthorizationBearer token · headerrequired
Path parameters
agent_idstring<uuid>required
Agent id
Header parameters
Idempotency-Keystring
Retry the same operation with this key to return its saved receipt. Scoped by the operation's authenticated caller or resource. A different input under the same key returns 409. Receipts are retained for at least 7 days after completion, then removed by an hourly sweep. After removal the key can execute again. Fresh-only secrets are never included in a replay.
min length 1 · max length 255
Request body
requiredapplication/json
builtinBuiltinGrantsBody
The servers the platform serves itself, each at `builtin:{key}`.
Show properties
ask_userany | AskUserGrantBody
Show properties
One of:
any
any
AskUserGrantBody
widgetsWidgetGrantBody[]required
min items 1 · max items 32
Show properties
Array of WidgetGrantBody
One of:
object
typestringrequired
Allowed:select
object
typestringrequired
Allowed:text
object
typestringrequired
Allowed:confirm
object
answerobjectrequired
The JSON Schema an answer must match.
descriptionstringrequired
What the model reads to choose the widget.
max length 1024
idstringrequired
The renderer's key. A change to `props` or `answer` that would break a client takes a new id.
max length 64 · matches ^[a-z0-9_-]+$
propsobjectrequired
The JSON Schema of what the agent fills in.
typestringrequired
Allowed:custom
session_display_nameSessionDisplayNameGrantBody
Whether the agent gets a `set` tool for the session's display name. A name a user wrote is never overwritten unless it is blank; `when` decides the rest.
Show properties
whenDisplayNameWhenBodyrequired
Which session display names the agent may overwrite.
Allowed:neveremptyuntil_user_edits
functionsFunctionGrantBody[]
Show properties
Array of FunctionGrantBody
default_policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
http_credentialsHttpOriginBody[]
Origins whose credential, from the session's vaults, is attached to each request the package sends there. Each must be reachable under `network` and listed once. A call is refused, naming the origin, when the session's vaults hold none, more than one, or one that must be reconnected.
max items 16
namestringrequired
The broker serves the package at `fn:{name}`. Unique within `functions`; `parent` is reserved.
max length 32 · matches ^[a-z0-9-]+$
networkFunctionNetworkBody
Where a function's HTTP requests may go. Every variant refuses private and metadata addresses.
Show properties
One of:
object
typestringrequired
Allowed:none
object
typestringrequired
Allowed:unrestricted
object
hostsHostPatternBody[]required
min items 1 · max items 64
typestringrequired
Allowed:allowlist
sourceFunctionSourceBodyrequired
Where the package comes from. `platform` names a package the deployment ships, e.g. `files`; `workspace` names one this workspace uploaded.
Show properties
One of:
object
packagestringrequired
max length 32 · matches ^[a-z0-9-]+$
typestringrequired
Allowed:platform
object
function_idstring<uuid>required
typestringrequired
Allowed:workspace
versionVersionPinBodyrequired
The latest version at resolution time, or an exact one.
Show properties
One of:
object
typestringrequired
Allowed:latest
object
numberinteger<int32>required
min 1
typestringrequired
Allowed:pinned
timeout_secsinteger<int32> | null
How long one call may run, in seconds; 60 when unset.
min 1 · max 300
toolsToolRuleBody[]
Show properties
Array of ToolRuleBody
namestringrequired
policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
mcpMcpGrantBody[]
Show properties
Array of McpGrantBody
default_policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
namestringrequired
The broker serves the server at `mcp:{name}`. Unique within `mcp`; `parent` is reserved.
max length 32 · matches ^[a-z0-9-]+$
toolsToolRuleBody[]
Show properties
Array of ToolRuleBody
namestringrequired
policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
urlstringrequired
modelModelConfigBodyrequired
Selects the model wire format and carries that format's settings.
Show properties
One of:
object
context_windowinteger<int32>required
min 0
effortany | AnthropicEffortBody
Show properties
One of:
any
any
AnthropicEffortBody
string
image_inputany | ImageInputBody
Show properties
One of:
any
any
ImageInputBody
string
max_tokensinteger<int32>required
min 0
modelstringrequired
thinkingany | AnthropicThinkingBody
Show properties
One of:
any
any
AnthropicThinkingBody
One of:
object
typestringrequired
Allowed:adaptive
object
typestringrequired
Allowed:disabled
object
typestringrequired
Allowed:between_tools
object
budget_tokensinteger<int32>required
min 0
typestringrequired
Allowed:enabled
formatstringrequired
Allowed:anthropic
object
context_windowinteger<int32>required
min 0
image_inputany | ImageInputBody
Show properties
One of:
any
any
ImageInputBody
string
max_tokensinteger<int32>required
min 0
modelstringrequired
reasoning_effortany | ReasoningEffortBody
Show properties
One of:
any
any
ReasoningEffortBody
string
formatstringrequired
Allowed:openai_responses
sandboxesSandboxGrantBody[]
Show properties
Array of SandboxGrantBody
default_policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
environmentEnvironmentRefBodyrequired
The deployment's current image for a named platform release line.
Show properties
One of:
object
releasestringrequired
The platform image line, e.g. `2026`. A line the deployment does not offer is refused at publish.
max length 32 · matches ^[a-z0-9-]+$
typestringrequired
Allowed:platform
namestringrequired
A label this config invents; the broker serves the sandbox at `sandbox:{name}`. Unique within `sandboxes`; `parent` is reserved.
max length 32 · matches ^[a-z0-9-]+$
networkSandboxNetworkBody
Where the sandbox may reach. `unrestricted` is the internet; `none` keeps it out while the sandbox still reaches the platform's own storage for its backups and skills.
Show properties
One of:
object
typestringrequired
Allowed:unrestricted
object
typestringrequired
Allowed:none
toolsToolRuleBody[]
Show properties
Array of ToolRuleBody
namestringrequired
policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
skillsSkillGrantBody[]
Show properties
Array of SkillGrantBody
namestringrequired
A label this config invents; the broker serves the skill at `skill:{name}`. Unique within `skills`; `parent` is reserved.
max length 32 · matches ^[a-z0-9-]+$
skill_idstring<uuid>required
versionVersionPinBodyrequired
The latest version at resolution time, or an exact one.
Show properties
One of:
object
typestringrequired
Allowed:latest
object
numberinteger<int32>required
min 1
typestringrequired
Allowed:pinned
system_promptstring | null
volumeVolumeConfigBody
The roots the session tree's functions reach beyond `/volume/tmp`.
Show properties
dataVolumeDataBody
Whether the volume offers a persistent `/volume/data` root. `enabled` mounts it for the session tree's functions.
Show properties
One of:
object
typestringrequired
Allowed:disabled
object
typestringrequired
Allowed:enabled
model_provider_idstring<uuid>required
Responses
201The published version.
agent_idstring<uuid>required
configAgentConfigBodyrequired
An agent version's config: the model it runs and the tool sources it may reach.
Show properties
builtinBuiltinGrantsBody
The servers the platform serves itself, each at `builtin:{key}`.
Show properties
ask_userany | AskUserGrantBody
Show properties
One of:
any
any
AskUserGrantBody
widgetsWidgetGrantBody[]required
min items 1 · max items 32
Show properties
Array of WidgetGrantBody
One of:
object
typestringrequired
Allowed:select
object
typestringrequired
Allowed:text
object
typestringrequired
Allowed:confirm
object
answerobjectrequired
The JSON Schema an answer must match.
descriptionstringrequired
What the model reads to choose the widget.
max length 1024
idstringrequired
The renderer's key. A change to `props` or `answer` that would break a client takes a new id.
max length 64 · matches ^[a-z0-9_-]+$
propsobjectrequired
The JSON Schema of what the agent fills in.
typestringrequired
Allowed:custom
session_display_nameSessionDisplayNameGrantBody
Whether the agent gets a `set` tool for the session's display name. A name a user wrote is never overwritten unless it is blank; `when` decides the rest.
Show properties
whenDisplayNameWhenBodyrequired
Which session display names the agent may overwrite.
Allowed:neveremptyuntil_user_edits
functionsFunctionGrantBody[]
Show properties
Array of FunctionGrantBody
default_policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
http_credentialsHttpOriginBody[]
Origins whose credential, from the session's vaults, is attached to each request the package sends there. Each must be reachable under `network` and listed once. A call is refused, naming the origin, when the session's vaults hold none, more than one, or one that must be reconnected.
max items 16
namestringrequired
The broker serves the package at `fn:{name}`. Unique within `functions`; `parent` is reserved.
max length 32 · matches ^[a-z0-9-]+$
networkFunctionNetworkBody
Where a function's HTTP requests may go. Every variant refuses private and metadata addresses.
Show properties
One of:
object
typestringrequired
Allowed:none
object
typestringrequired
Allowed:unrestricted
object
hostsHostPatternBody[]required
min items 1 · max items 64
typestringrequired
Allowed:allowlist
sourceFunctionSourceBodyrequired
Where the package comes from. `platform` names a package the deployment ships, e.g. `files`; `workspace` names one this workspace uploaded.
Show properties
One of:
object
packagestringrequired
max length 32 · matches ^[a-z0-9-]+$
typestringrequired
Allowed:platform
object
function_idstring<uuid>required
typestringrequired
Allowed:workspace
versionVersionPinBodyrequired
The latest version at resolution time, or an exact one.
Show properties
One of:
object
typestringrequired
Allowed:latest
object
numberinteger<int32>required
min 1
typestringrequired
Allowed:pinned
timeout_secsinteger<int32> | null
How long one call may run, in seconds; 60 when unset.
min 1 · max 300
toolsToolRuleBody[]
Show properties
Array of ToolRuleBody
namestringrequired
policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
mcpMcpGrantBody[]
Show properties
Array of McpGrantBody
default_policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
namestringrequired
The broker serves the server at `mcp:{name}`. Unique within `mcp`; `parent` is reserved.
max length 32 · matches ^[a-z0-9-]+$
toolsToolRuleBody[]
Show properties
Array of ToolRuleBody
namestringrequired
policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
urlstringrequired
modelModelConfigBodyrequired
Selects the model wire format and carries that format's settings.
Show properties
One of:
object
context_windowinteger<int32>required
min 0
effortany | AnthropicEffortBody
Show properties
One of:
any
any
AnthropicEffortBody
string
image_inputany | ImageInputBody
Show properties
One of:
any
any
ImageInputBody
string
max_tokensinteger<int32>required
min 0
modelstringrequired
thinkingany | AnthropicThinkingBody
Show properties
One of:
any
any
AnthropicThinkingBody
One of:
object
typestringrequired
Allowed:adaptive
object
typestringrequired
Allowed:disabled
object
typestringrequired
Allowed:between_tools
object
budget_tokensinteger<int32>required
min 0
typestringrequired
Allowed:enabled
formatstringrequired
Allowed:anthropic
object
context_windowinteger<int32>required
min 0
image_inputany | ImageInputBody
Show properties
One of:
any
any
ImageInputBody
string
max_tokensinteger<int32>required
min 0
modelstringrequired
reasoning_effortany | ReasoningEffortBody
Show properties
One of:
any
any
ReasoningEffortBody
string
formatstringrequired
Allowed:openai_responses
sandboxesSandboxGrantBody[]
Show properties
Array of SandboxGrantBody
default_policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
environmentEnvironmentRefBodyrequired
The deployment's current image for a named platform release line.
Show properties
One of:
object
releasestringrequired
The platform image line, e.g. `2026`. A line the deployment does not offer is refused at publish.
max length 32 · matches ^[a-z0-9-]+$
typestringrequired
Allowed:platform
namestringrequired
A label this config invents; the broker serves the sandbox at `sandbox:{name}`. Unique within `sandboxes`; `parent` is reserved.
max length 32 · matches ^[a-z0-9-]+$
networkSandboxNetworkBody
Where the sandbox may reach. `unrestricted` is the internet; `none` keeps it out while the sandbox still reaches the platform's own storage for its backups and skills.
Show properties
One of:
object
typestringrequired
Allowed:unrestricted
object
typestringrequired
Allowed:none
toolsToolRuleBody[]
Show properties
Array of ToolRuleBody
namestringrequired
policyPolicyActionBodyrequired
What happens when the agent reaches for a tool: it runs, it waits for an approval on the session's approvals route, or it comes back refused.
Allowed:allowrequire_approvaldeny
skillsSkillGrantBody[]
Show properties
Array of SkillGrantBody
namestringrequired
A label this config invents; the broker serves the skill at `skill:{name}`. Unique within `skills`; `parent` is reserved.
max length 32 · matches ^[a-z0-9-]+$
skill_idstring<uuid>required
versionVersionPinBodyrequired
The latest version at resolution time, or an exact one.
Show properties
One of:
object
typestringrequired
Allowed:latest
object
numberinteger<int32>required
min 1
typestringrequired
Allowed:pinned
system_promptstring | null
volumeVolumeConfigBody
The roots the session tree's functions reach beyond `/volume/tmp`.
Show properties
dataVolumeDataBody
Whether the volume offers a persistent `/volume/data` root. `enabled` mounts it for the session tree's functions.
Show properties
One of:
object
typestringrequired
Allowed:disabled
object
typestringrequired
Allowed:enabled
created_atstring<date-time>required
idstring<uuid>required
model_provider_idstring<uuid>required
versioninteger<int32>required
Numbered per agent from 1.
400Malformed body, path parameter, or an invalid config.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
401Missing, malformed, or invalid bearer token.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
403Caller lacks agent.publish.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
404No such agent, or the caller cannot see it.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
409Idempotency-Key was already used for a different request.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST "https://api.us.cloud.subako.ai/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/versions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "builtin": {
    "ask_user": {},
    "session_display_name": {
      "when": "never"
    }
  },
  "functions": [
    {
      "default_policy": "allow",
      "http_credentials": [
        "string"
      ],
      "name": "string",
      "network": {
        "type": "none"
      },
      "source": {
        "package": "string",
        "type": "platform"
      },
      "timeout_secs": 1,
      "tools": [
        {
          "name": "string",
          "policy": "allow"
        }
      ]
    }
  ],
  "mcp": [
    {
      "default_policy": "allow",
      "name": "string",
      "tools": [
        {
          "name": "string",
          "policy": "allow"
        }
      ],
      "url": "string"
    }
  ],
  "model": {
    "context_window": 0,
    "effort": {},
    "image_input": {},
    "max_tokens": 0,
    "model": "string",
    "thinking": {},
    "format": "anthropic"
  },
  "sandboxes": [
    {
      "default_policy": "allow",
      "environment": {
        "release": "string",
        "type": "platform"
      },
      "name": "string",
      "network": {
        "type": "unrestricted"
      },
      "tools": [
        {
          "name": "string",
          "policy": "allow"
        }
      ]
    }
  ],
  "skills": [
    {
      "name": "string",
      "skill_id": "3cd68bb3-8b7e-48be-8232-1b99b5b4b3aa",
      "version": {
        "type": "latest"
      }
    }
  ],
  "system_prompt": "string",
  "volume": {
    "data": {
      "type": "disabled"
    }
  },
  "model_provider_id": "e8dd39c4-1070-4c00-8ab5-c345bdef77c9"
}'
Response
{
  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  "config": {
    "builtin": {
      "ask_user": {},
      "session_display_name": {
        "when": "never"
      }
    },
    "functions": [
      {
        "default_policy": "allow",
        "http_credentials": [
          "string"
        ],
        "name": "string",
        "network": {
          "type": "none"
        },
        "source": {
          "package": "string",
          "type": "platform"
        },
        "timeout_secs": 1,
        "tools": [
          {
            "name": "string",
            "policy": "allow"
          }
        ]
      }
    ],
    "mcp": [
      {
        "default_policy": "allow",
        "name": "string",
        "tools": [
          {
            "name": "string",
            "policy": "allow"
          }
        ],
        "url": "string"
      }
    ],
    "model": {
      "context_window": 0,
      "effort": {},
      "image_input": {},
      "max_tokens": 0,
      "model": "string",
      "thinking": {},
      "format": "anthropic"
    },
    "sandboxes": [
      {
        "default_policy": "allow",
        "environment": {
          "release": "string",
          "type": "platform"
        },
        "name": "string",
        "network": {
          "type": "unrestricted"
        },
        "tools": [
          {
            "name": "string",
            "policy": "allow"
          }
        ]
      }
    ],
    "skills": [
      {
        "name": "string",
        "skill_id": "3cd68bb3-8b7e-48be-8232-1b99b5b4b3aa",
        "version": {
          "type": "latest"
        }
      }
    ],
    "system_prompt": "string",
    "volume": {
      "data": {
        "type": "disabled"
      }
    }
  },
  "created_at": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "model_provider_id": "e8dd39c4-1070-4c00-8ab5-c345bdef77c9",
  "version": 0
}