Update Agent Version

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
    }
  }
}

POST

agents

version

update

Update Agent Version

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. This creates a new version N+1 in the versions subcollection and bumps the version pointer on the root document. Only supported for custom agents. In-flight executions stay pinned to whatever version they started on, so updating a version never disturbs a running execution. The schema uses .passthrough(), so additional behavioral fields are forwarded to the service layer.

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

Custom agent ID.

rawInstructions

string

Original user-provided instructions.

instructions

string

Processed/enhanced instructions.

phaseTimeoutMs

number

Per-phase timeout in ms (positive integer).

contextGathering

object

Context gathering config. Same shape as Create Agent.

execution

object

Execution config, including executionStrategy, the strict knowledge (Memory-RAG) block, and mcpServers for the "mcp-tools" strategy. Same shape as Create Agent. Rotating an MCP/REST auth secret is done by sending the new plaintext value here; omitting it keeps the stored secret.

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 },
      "deletePreviousSuggestions": { "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 via scope

{
  "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: INVALID_ARGUMENT (Zod validation failure) / NOT_FOUND (agent does not exist).

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

Extract Agents from File List Agent Versions

⌘I

REST APIs

SDK

Update Agent Version

Endpoint

Headers

Body

Params

Example Requests

1. Update instructions and post-processing

2. Update context gathering strategies

3. Enable cross-page via scope

Response

Success Response

Failure Response

​Endpoint

​Headers

​Body

​Params

​Example Requests

​1. Update instructions and post-processing

​2. Update context gathering strategies

​3. Enable cross-page via scope

​Response

​Success Response

​Failure Response

Endpoint

Headers

Body

Params

Example Requests

1. Update instructions and post-processing

2. Update context gathering strategies

3. Enable cross-page via scope

Response

Success Response

Failure Response