Save the Single Agent Draft

PATCH

/api/app/{app_slug}/single-agent/

const url = 'https://api.agentaab.com/api/app/example/single-agent/';
const options = {
  method: 'PATCH',
  headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'},
  body: '{"definition":{"kind":"single_agent","version":1,"interaction_mode":"completion","instructions":{"system":"example","user_template":"example"},"model":{"provider":"example","model":"example","credential_ref":"example","api_base":"https://example.com","temperature":1,"top_p":1,"frequency_penalty":1,"presence_penalty":1},"tools":[{"id":"example","kind":"mcp","version":"example","tool_name":"example","endpoint":"https://example.com","credential_ref":"example","credential_mode":"bearer"}],"input_schema":{},"output_schema":{},"limits":{"timeout_ms":1,"max_output_tokens":1,"max_tool_calls":1},"configuration":{}},"base_revision":"example","changelog":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://api.agentaab.com/api/app/example/single-agent/ \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "definition": { "kind": "single_agent", "version": 1, "interaction_mode": "completion", "instructions": { "system": "example", "user_template": "example" }, "model": { "provider": "example", "model": "example", "credential_ref": "example", "api_base": "https://example.com", "temperature": 1, "top_p": 1, "frequency_penalty": 1, "presence_penalty": 1 }, "tools": [ { "id": "example", "kind": "mcp", "version": "example", "tool_name": "example", "endpoint": "https://example.com", "credential_ref": "example", "credential_mode": "bearer" } ], "input_schema": {}, "output_schema": {}, "limits": { "timeout_ms": 1, "max_output_tokens": 1, "max_tool_calls": 1 }, "configuration": {} }, "base_revision": "example", "changelog": "example" }'

Validate and save the full v1 Definition only when base_revision still matches. This does not create or activate a Capability Release.

Authorizations

tokenAuth
cookieAuth

Parameters

Path Parameters

app_slug

required

string

Request Body^required

application/json

object

definition

required

Complete authoritative editable Definition for one Single Agent. Raw secret-like fields and values are rejected recursively.

object

kind

required

string

Allowed values: single_agent

version

required

integer

Allowed values: 1

interaction_mode

required

string

Allowed values: completion chat

instructions

required

object

system

required

string

<= 32000 characters

user_template

required

string

>= 1 characters <= 64000 characters

model

required

object

provider

required

string

>= 1 characters <= 100 characters

model

required

string

>= 1 characters <= 200 characters

credential_ref

string

/^[A-Z][A-Z0-9_]{2,127}$/

api_base

Optional absolute HTTPS provider endpoint without userinfo or secret query parameters.

string format: uri

temperature

required

number

<= 2

top_p

required

number

<= 1

frequency_penalty

required

number

>= -2 <= 2

presence_penalty

required

number

>= -2 <= 2

tools

required

Array<object>

<= 32 items

A pinned Tool identity and optional server-managed credential reference. Raw credential values are forbidden.

object

required

string

kind

required

string

Allowed values: mcp function

version

required

string

tool_name

required

string

endpoint

Exact absolute HTTPS endpoint. Required for MCP Tools.

string format: uri

credential_ref

Name of a server-side Worker secret binding, never a credential value.

string

/^[A-Z][A-Z0-9_]{2,127}$/

credential_mode

string

Allowed values: bearer x_api_key

input_schema

required

JSON Schema with an object root.

object

key

additional properties

any

output_schema

required

JSON Schema with an object root.

object

key

additional properties

any

limits

required

object

timeout_ms

required

integer

>= 1000 <= 120000

max_output_tokens

required

integer

>= 1 <= 32768

max_tool_calls

required

integer

<= 32

configuration

required

object

key

additional properties

any

base_revision

required

Exact opaque draft_revision returned by the latest GET or successful PATCH.

string

changelog

string

<= 500 characters

Responses

200

The saved Draft and its new opaque Revision.

application/json

object

required

string

application

required

string

definition

required

Complete authoritative editable Definition for one Single Agent. Raw secret-like fields and values are rejected recursively.

object

kind

required

string

Allowed values: single_agent

version

required

integer

Allowed values: 1

interaction_mode

required

string

Allowed values: completion chat

instructions

required

object

system

required

string

<= 32000 characters

user_template

required

string

>= 1 characters <= 64000 characters

model

required

object

provider

required

string

>= 1 characters <= 100 characters

model

required

string

>= 1 characters <= 200 characters

credential_ref

string

/^[A-Z][A-Z0-9_]{2,127}$/

api_base

Optional absolute HTTPS provider endpoint without userinfo or secret query parameters.

string format: uri

temperature

required

number

<= 2

top_p

required

number

<= 1

frequency_penalty

required

number

>= -2 <= 2

presence_penalty

required

number

>= -2 <= 2

tools

required

Array<object>

<= 32 items

A pinned Tool identity and optional server-managed credential reference. Raw credential values are forbidden.

object

required

string

kind

required

string

Allowed values: mcp function

version

required

string

tool_name

required

string

endpoint

Exact absolute HTTPS endpoint. Required for MCP Tools.

string format: uri

credential_ref

Name of a server-side Worker secret binding, never a credential value.

string

/^[A-Z][A-Z0-9_]{2,127}$/

credential_mode

string

Allowed values: bearer x_api_key

input_schema

required

JSON Schema with an object root.

object

key

additional properties

any

output_schema

required

JSON Schema with an object root.

object

key

additional properties

any

limits

required

object

timeout_ms

required

integer

>= 1000 <= 120000

max_output_tokens

required

integer

>= 1 <= 32768

max_tool_calls

required

integer

<= 32

configuration

required

object

key

additional properties

any

draft_revision

required

Opaque compare-and-set token; clients must not derive or modify it.

string

versions

required

Array<object>

object

required

string

version_number

required

integer

>= 1

is_active

required

boolean

changelog

string

created_at

required

string format: date-time

definition

Complete authoritative editable Definition for one Single Agent. Raw secret-like fields and values are rejected recursively.

object

kind

required

string

Allowed values: single_agent

version

required

integer

Allowed values: 1

interaction_mode

required

string

Allowed values: completion chat

instructions

required

object

system

required

string

<= 32000 characters

user_template

required

string

>= 1 characters <= 64000 characters

model

required

object

provider

required

string

>= 1 characters <= 100 characters

model

required

string

>= 1 characters <= 200 characters

credential_ref

string

/^[A-Z][A-Z0-9_]{2,127}$/

api_base

Optional absolute HTTPS provider endpoint without userinfo or secret query parameters.

string format: uri

temperature

required

number

<= 2

top_p

required

number

<= 1

frequency_penalty

required

number

>= -2 <= 2

presence_penalty

required

number

>= -2 <= 2

tools

required

Array<object>

<= 32 items

A pinned Tool identity and optional server-managed credential reference. Raw credential values are forbidden.

object

required

string

kind

required

string

Allowed values: mcp function

version

required

string

tool_name

required

string

endpoint

Exact absolute HTTPS endpoint. Required for MCP Tools.

string format: uri

credential_ref

Name of a server-side Worker secret binding, never a credential value.

string

/^[A-Z][A-Z0-9_]{2,127}$/

credential_mode

string

Allowed values: bearer x_api_key

input_schema

required

JSON Schema with an object root.

object

key

additional properties

any

output_schema

required

JSON Schema with an object root.

object

key

additional properties

any

limits

required

object

timeout_ms

required

integer

>= 1000 <= 120000

max_output_tokens

required

integer

>= 1 <= 32768

max_tool_calls

required

integer

<= 32

configuration

required

object

key

additional properties

any

active_version

required

object

required

string

version_number

required

integer

>= 1

is_active

required

boolean

changelog

string

created_at

required

string format: date-time

definition

Complete authoritative editable Definition for one Single Agent. Raw secret-like fields and values are rejected recursively.

object

kind

required

string

Allowed values: single_agent

version

required

integer

Allowed values: 1

interaction_mode

required

string

Allowed values: completion chat

instructions

required

object

system

required

string

<= 32000 characters

user_template

required

string

>= 1 characters <= 64000 characters

model

required

object

provider

required

string

>= 1 characters <= 100 characters

model

required

string

>= 1 characters <= 200 characters

credential_ref

string

/^[A-Z][A-Z0-9_]{2,127}$/

api_base

Optional absolute HTTPS provider endpoint without userinfo or secret query parameters.

string format: uri

temperature

required

number

<= 2

top_p

required

number

<= 1

frequency_penalty

required

number

>= -2 <= 2

presence_penalty

required

number

>= -2 <= 2

tools

required

Array<object>

<= 32 items

A pinned Tool identity and optional server-managed credential reference. Raw credential values are forbidden.

object

required

string

kind

required

string

Allowed values: mcp function

version

required

string

tool_name

required

string

endpoint

Exact absolute HTTPS endpoint. Required for MCP Tools.

string format: uri

credential_ref

Name of a server-side Worker secret binding, never a credential value.

string

/^[A-Z][A-Z0-9_]{2,127}$/

credential_mode

string

Allowed values: bearer x_api_key

input_schema

required

JSON Schema with an object root.

object

key

additional properties

any

output_schema

required

JSON Schema with an object root.

object

key

additional properties

any

limits

required

object

timeout_ms

required

integer

>= 1000 <= 120000

max_output_tokens

required

integer

>= 1 <= 32768

max_tool_calls

required

integer

<= 32

configuration

required

object

key

additional properties

any

migration

object

source

required

string

Allowed values: legacy_prompt

persisted

required

boolean

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "definition": {
    "kind": "single_agent",
    "version": 1,
    "interaction_mode": "completion",
    "tools": [
      {
        "kind": "mcp",
        "credential_mode": "bearer"
      }
    ]
  },
  "versions": [
    {
      "definition": {
        "kind": "single_agent",
        "version": 1,
        "interaction_mode": "completion",
        "tools": [
          {
            "kind": "mcp",
            "credential_mode": "bearer"
          }
        ]
      }
    }
  ],
  "active_version": {
    "definition": {
      "kind": "single_agent",
      "version": 1,
      "interaction_mode": "completion",
      "tools": [
        {
          "kind": "mcp",
          "credential_mode": "bearer"
        }
      ]
    }
  },
  "migration": {
    "source": "legacy_prompt",
    "persisted": false
  }
}

400

The Definition is invalid or contains raw secret material.

application/json

object

error

required

string

code

string

draft_revision

string

issues

Array<object>

object

code

required

string

path

required

string

message

required

string

Example^generated

{
  "error": "example",
  "code": "example",
  "draft_revision": "example",
  "issues": [
    {
      "code": "example",
      "path": "example",
      "message": "example"
    }
  ]
}

409

A newer Draft exists. The response code is single_agent_revision_conflict and includes its opaque Draft Revision.

application/json

object

error

required

string

code

string

draft_revision

string

issues

Array<object>

object

code

required

string

path

required

string

message

required

string

Example^generated

{
  "error": "example",
  "code": "example",
  "draft_revision": "example",
  "issues": [
    {
      "code": "example",
      "path": "example",
      "message": "example"
    }
  ]
}

413

The bounded Draft payload exceeds 256 KiB.

application/json

object

error

required

string

code

string

draft_revision

string

issues

Array<object>

object

code

required

string

path

required

string

message

required

string

Example^generated

{
  "error": "example",
  "code": "example",
  "draft_revision": "example",
  "issues": [
    {
      "code": "example",
      "path": "example",
      "message": "example"
    }
  ]
}

Save the Single Agent Draft

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

Example

400

Examplegenerated

409

Examplegenerated

413

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated