Skip to content
Subako Docs
Esc
↑↓navigate↵open⌘Jpreview

POST /v1/agents/{agent_id}/versions

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
mcpMcpGrantBody[]
Show properties
Array of McpGrantBody
default_policyPolicyActionBodyrequired
Applies to any tool not named in `tools`, including one the server adds after this version is published.
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
Allowed:allowrequire_approvaldeny
urlstringrequired
modelModelConfigBodyrequired
Selects the model wire format and carries that format's settings.
Show properties
One of:
object
max_tokensinteger<int32>required
min 0
modelstringrequired
thinkingany | AnthropicThinkingBody
Show properties
One of:
any
any
AnthropicThinkingBody
budget_tokensinteger<int32>required
min 0
formatstringrequired
Allowed:anthropic
object
context_windowinteger<int32>required
min 0
max_tokensinteger<int32>required
min 0
modelstringrequired
reasoning_effortany | ReasoningEffortBody
Show properties
One of:
any
any
ReasoningEffortBody
string
formatstringrequired
Allowed:openai_responses
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
model_provider_idstring<uuid>required
Responses
201The published version.
agent_idstring<uuid>required
configobjectrequired
The config this version was published with. Skill grants retain their requested `version` selectors, which resolve independently when each session is created.
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
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
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
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
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
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 '{
  "mcp": [
    {
      "default_policy": "allow",
      "name": "string",
      "tools": [
        {
          "name": "string",
          "policy": "allow"
        }
      ],
      "url": "string"
    }
  ],
  "model": {
    "max_tokens": 0,
    "model": "string",
    "thinking": {},
    "format": "anthropic"
  },
  "skills": [
    {
      "name": "string",
      "skill_id": "3cd68bb3-8b7e-48be-8232-1b99b5b4b3aa",
      "version": {
        "type": "latest"
      }
    }
  ],
  "system_prompt": "string",
  "model_provider_id": "e8dd39c4-1070-4c00-8ab5-c345bdef77c9"
}'
Response
{
  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  "config": {},
  "created_at": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "model_provider_id": "e8dd39c4-1070-4c00-8ab5-c345bdef77c9",
  "version": 0
}