List Agent Versions
curl --request POST \
--url https://api.velt.dev/v2/agents/versions/list \
--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>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/versions/list"
payload = { "data": { "agentId": "<string>" } }
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>'}})
};
fetch('https://api.velt.dev/v2/agents/versions/list', 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/versions/list",
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>'
]
]),
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/versions/list"
payload := strings.NewReader("{\n \"data\": {\n \"agentId\": \"<string>\"\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/versions/list")
.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 }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/versions/list")
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 }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Versions listed successfully",
"data": {
"versions": []
}
}
}
Versioning
List Agent Versions
POST
/
v2
/
agents
/
versions
/
list
List Agent Versions
curl --request POST \
--url https://api.velt.dev/v2/agents/versions/list \
--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>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/versions/list"
payload = { "data": { "agentId": "<string>" } }
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>'}})
};
fetch('https://api.velt.dev/v2/agents/versions/list', 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/versions/list",
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>'
]
]),
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/versions/list"
payload := strings.NewReader("{\n \"data\": {\n \"agentId\": \"<string>\"\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/versions/list")
.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 }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/versions/list")
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 }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Versions listed successfully",
"data": {
"versions": []
}
}
}
Use this API to fetch the version history for a custom agent. A new version is created automatically on every Update Agent Version call. Versions are returned newest-first (descending by version number). Each version is a behavioral snapshot of the agent at that point in time — identity fields (
Alongside those three
Errors:
name, description, enabled, managedBy) live on the root agent document and are not part of version snapshots.
Any auth secrets in a version snapshot are redacted ("__redacted__") before the response is returned: both rest-api strategy secrets and mcp-tools server secrets (execution.mcpServers[].auth).
Endpoint
POST https://api.velt.dev/v2/agents/versions/list
Headers
string
required
Your API key.
string
required
Your Auth Token.
Body
Params
Example Requests
{
"data": {
"agentId": "abc123def456"
}
}
Response
Success Response
{
"result": {
"status": "success",
"message": "Versions listed successfully",
"data": {
"versions": [
{
"id": "v3",
"version": 3,
"createdAt": 1711900000000,
"instructions": "Check headings use 'Inter' font. Verify #1A73E8 on all CTAs and links.",
"contextGathering": {
"strategies": ["web-page-text", "web-page-screenshot", "web-page-html"]
},
"execution": {
"executionStrategy": "ai",
"responseDescriptions": { "title": "Short name for the brand inconsistency" }
},
"postProcess": {
"guardrails": { "enabled": true },
"deletePreviousSuggestions": { "enabled": true }
}
},
{
"id": "v2",
"version": 2,
"createdAt": 1711800000000,
"instructions": "Check headings use 'Inter' font. Verify #1A73E8 on all CTAs and links.",
"contextGathering": { "strategies": ["web-page-text", "web-page-screenshot"] },
"execution": { "executionStrategy": "ai" }
},
{
"id": "v1",
"version": 1,
"createdAt": 1711700000000,
"instructions": "Check headings use Inter font...",
"contextGathering": { "strategies": ["web-page-text"] }
}
]
}
}
}
| Field | Type | Description |
|---|---|---|
data.versions | object[] | Version snapshots, newest first. |
versions[].id | string | Version document ID in the v{N} format (e.g. "v3"). |
versions[].version | number | Version number. |
versions[].createdAt | number | Epoch ms when the version was created. |
versions[] fields, every behavioral field the agent had at that version is present on each row: rawInstructions, instructions, phaseTimeoutMs, contextGathering, execution, response, postProcess, input, scope, and setup. The example above is abridged. Identity fields (name, description, enabled, managedBy) are not versioned and never appear here; read them from Get Agent.
This endpoint returns the agent’s full version history in one response. There is no pagination and no cap, so an agent with a long edit history returns a correspondingly large payload.
Failure Response
{
"error": {
"message": "ERROR_MESSAGE",
"status": "NOT_FOUND"
}
}
INVALID_ARGUMENT (missing or empty agentId) / NOT_FOUND (the workspace store database could not be resolved).
An agent that does not exist is not an error here. It returns
200 with an empty versions array, which is indistinguishable from an agent that exists but has no version history.{
"result": {
"status": "success",
"message": "Versions listed successfully",
"data": {
"versions": []
}
}
}
Was this page helpful?

