Update Agent Version (Behavioral)

POST /v2/agents/version/update

Update Agent Version (Behavioral)

cURL

curl --request POST \
  --url https://api.velt.dev/v2/agents/version/update \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "agentId": "<string>",
    "rawInstructions": "<string>",
    "instructions": "<string>",
    "phaseTimeoutMs": 123,
    "contextGathering": {},
    "execution": {},
    "response": {},
    "postProcess": {},
    "input": {},
    "scope": {},
    "setup": {}
  }
}
'

import requests

url = "https://api.velt.dev/v2/agents/version/update"

payload = { "data": {
        "agentId": "<string>",
        "rawInstructions": "<string>",
        "instructions": "<string>",
        "phaseTimeoutMs": 123,
        "contextGathering": {},
        "execution": {},
        "response": {},
        "postProcess": {},
        "input": {},
        "scope": {},
        "setup": {}
    } }
headers = {
    "x-velt-api-key": "<x-velt-api-key>",
    "x-velt-auth-token": "<x-velt-auth-token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-velt-api-key': '<x-velt-api-key>',
    'x-velt-auth-token': '<x-velt-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      agentId: '<string>',
      rawInstructions: '<string>',
      instructions: '<string>',
      phaseTimeoutMs: 123,
      contextGathering: {},
      execution: {},
      response: {},
      postProcess: {},
      input: {},
      scope: {},
      setup: {}
    }
  })
};

fetch('https://api.velt.dev/v2/agents/version/update', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.velt.dev/v2/agents/version/update",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        'agentId' => '<string>',
        'rawInstructions' => '<string>',
        'instructions' => '<string>',
        'phaseTimeoutMs' => 123,
        'contextGathering' => [
                
        ],
        'execution' => [
                
        ],
        'response' => [
                
        ],
        'postProcess' => [
                
        ],
        'input' => [
                
        ],
        'scope' => [
                
        ],
        'setup' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-velt-api-key: <x-velt-api-key>",
    "x-velt-auth-token: <x-velt-auth-token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.velt.dev/v2/agents/version/update"

	payload := strings.NewReader("{\n  \"data\": {\n    \"agentId\": \"<string>\",\n    \"rawInstructions\": \"<string>\",\n    \"instructions\": \"<string>\",\n    \"phaseTimeoutMs\": 123,\n    \"contextGathering\": {},\n    \"execution\": {},\n    \"response\": {},\n    \"postProcess\": {},\n    \"input\": {},\n    \"scope\": {},\n    \"setup\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
	req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/agents/version/update")
  .header("x-velt-api-key", "<x-velt-api-key>")
  .header("x-velt-auth-token", "<x-velt-auth-token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"agentId\": \"<string>\",\n    \"rawInstructions\": \"<string>\",\n    \"instructions\": \"<string>\",\n    \"phaseTimeoutMs\": 123,\n    \"contextGathering\": {},\n    \"execution\": {},\n    \"response\": {},\n    \"postProcess\": {},\n    \"input\": {},\n    \"scope\": {},\n    \"setup\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.velt.dev/v2/agents/version/update")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"agentId\": \"<string>\",\n    \"rawInstructions\": \"<string>\",\n    \"instructions\": \"<string>\",\n    \"phaseTimeoutMs\": 123,\n    \"contextGathering\": {},\n    \"execution\": {},\n    \"response\": {},\n    \"postProcess\": {},\n    \"input\": {},\n    \"scope\": {},\n    \"setup\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "result": {
    "status": "success",
    "message": "Agent version created successfully",
    "data": {
      "version": 4
    }
  }
}

Use this API to update behavioral/version fields on a custom agent. Creates a new version N+1 in the versions subcollection, updates the version pointer on the root document, and bumps updatedAt.

In-flight executions stay pinned to whatever version they started on — the update only affects future executions.

The schema uses .passthrough() so additional behavioral fields are forwarded. Deep validation happens in the service layer via updateCustomAgentConfigSchema.

Custom agents only. Use Update Agent for identity edits on built-in agents.

Endpoint

POST https://api.velt.dev/v2/agents/version/update

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

agentId · string · required

Min 1 char. Custom agent ID.

rawInstructions · string

Original user-provided instructions.

instructions · string

Processed/enhanced instructions.

phaseTimeoutMs · number

Per-phase timeout in milliseconds (positive integer).

contextGathering · object

Context gathering config. Same shape as Create Agent.

execution · object

Execution config. Same shape as Create Agent.

response · object

Response formatting config. Same shape as Create Agent.

postProcess · object

Post-processing pipeline config. Same shape as Create Agent.

input · object

Input declaration config. Same shape as Create Agent.

scope · object

Scope and targeting config. Same shape as Create Agent.

setup · object

Setup assistant metadata. Same shape as Create Agent.

Example Requests

1. Update instructions and post-processing

{
  "data": {
    "agentId": "abc123def456",
    "instructions": "Check headings use 'Inter' font. Verify #1A73E8 on all CTAs and links.",
    "postProcess": {
      "guardrails": { "enabled": true },
      "matchAndMerge": { "enabled": true }
    }
  }
}

2. Update context gathering strategies

{
  "data": {
    "agentId": "abc123def456",
    "contextGathering": {
      "strategies": ["web-page-text", "web-page-html", "web-page-screenshot"]
    }
  }
}

3. Enable cross-page execution

{
  "data": {
    "agentId": "abc123def456",
    "scope": {
      "crossPage": {
        "enabled": true,
        "targetProperty": "brandConsistency",
        "pageDiscovery": "manual",
        "pages": ["https://example.com", "https://example.com/about"]
      }
    }
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Agent version created successfully",
    "data": {
      "version": 4
    }
  }
}

Field	Type	Description
data.version	number	New version number after the update

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

Errors: NOT_FOUND (agent does not exist) / INVALID_ARGUMENT (validation failure or attempting to update a built-in agent’s behavior).

{
  "result": {
    "status": "success",
    "message": "Agent version created successfully",
    "data": {
      "version": 4
    }
  }
}