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

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

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

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

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

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

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

Idempotency-KeyheaderRetry 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.agent_idpath*Agent id

Bodyapplication/json

Request body

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"
  },
  "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",
  "model_provider_id": "e8dd39c4-1070-4c00-8ab5-c345bdef77c9"
}'

const response = await fetch("https://api.us.cloud.subako.ai/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/versions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"mcp\": [\n    {\n      \"default_policy\": \"allow\",\n      \"name\": \"string\",\n      \"tools\": [\n        {\n          \"name\": \"string\",\n          \"policy\": \"allow\"\n        }\n      ],\n      \"url\": \"string\"\n    }\n  ],\n  \"model\": {\n    \"max_tokens\": 0,\n    \"model\": \"string\",\n    \"thinking\": {},\n    \"format\": \"anthropic\"\n  },\n  \"sandboxes\": [\n    {\n      \"default_policy\": \"allow\",\n      \"environment\": {\n        \"release\": \"string\",\n        \"type\": \"platform\"\n      },\n      \"name\": \"string\",\n      \"network\": {\n        \"type\": \"unrestricted\"\n      },\n      \"tools\": [\n        {\n          \"name\": \"string\",\n          \"policy\": \"allow\"\n        }\n      ]\n    }\n  ],\n  \"skills\": [\n    {\n      \"name\": \"string\",\n      \"skill_id\": \"3cd68bb3-8b7e-48be-8232-1b99b5b4b3aa\",\n      \"version\": {\n        \"type\": \"latest\"\n      }\n    }\n  ],\n  \"system_prompt\": \"string\",\n  \"model_provider_id\": \"e8dd39c4-1070-4c00-8ab5-c345bdef77c9\"\n}"
});

import requests

response = requests.post(
    "https://api.us.cloud.subako.ai/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/versions",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"mcp\": [\n    {\n      \"default_policy\": \"allow\",\n      \"name\": \"string\",\n      \"tools\": [\n        {\n          \"name\": \"string\",\n          \"policy\": \"allow\"\n        }\n      ],\n      \"url\": \"string\"\n    }\n  ],\n  \"model\": {\n    \"max_tokens\": 0,\n    \"model\": \"string\",\n    \"thinking\": {},\n    \"format\": \"anthropic\"\n  },\n  \"sandboxes\": [\n    {\n      \"default_policy\": \"allow\",\n      \"environment\": {\n        \"release\": \"string\",\n        \"type\": \"platform\"\n      },\n      \"name\": \"string\",\n      \"network\": {\n        \"type\": \"unrestricted\"\n      },\n      \"tools\": [\n        {\n          \"name\": \"string\",\n          \"policy\": \"allow\"\n        }\n      ]\n    }\n  ],\n  \"skills\": [\n    {\n      \"name\": \"string\",\n      \"skill_id\": \"3cd68bb3-8b7e-48be-8232-1b99b5b4b3aa\",\n      \"version\": {\n        \"type\": \"latest\"\n      }\n    }\n  ],\n  \"system_prompt\": \"string\",\n  \"model_provider_id\": \"e8dd39c4-1070-4c00-8ab5-c345bdef77c9\"\n}",
)

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
}

{
  "error": {
    "code": "unauthorized",
    "message": "string"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string"
  }
}