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": []
    }
  }
}

POST

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 automatically created on every behavioral update via Update Agent Version. Versions are ordered descending (newest first) and contain the full behavioral snapshot at that point in time.

Endpoint

POST https://api.velt.dev/v2/agents/versions/list

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. Agent ID.

Example Requests

List versions for an agent

{
  "data": {
    "agentId": "abc123def456"
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Versions listed successfully",
    "data": {
      "versions": [
        {
          "id": "3",
          "version": 3,
          "createdAt": 1711900000000,
          "name": "Brand Consistency Checker",
          "description": "Validates brand colors, logos, and typography across pages",
          "instructions": "Check headings use 'Inter' font. Verify #1A73E8 on all CTAs and links. Check footer uses 'Inter' for body text.",
          "contextGathering": {
            "strategies": ["web-page-text", "web-page-screenshot", "web-page-html"]
          },
          "execution": {
            "executionStrategy": "ai",
            "responseDescriptions": {
              "title": "Short name for the brand inconsistency",
              "severity": "One of: critical, high, medium, low, info"
            }
          },
          "postProcess": {
            "guardrails": { "enabled": true },
            "matchAndMerge": { "enabled": true }
          }
        },
        {
          "id": "2",
          "version": 2,
          "createdAt": 1711800000000,
          "name": "Brand Consistency Checker",
          "description": "Validates brand colors and typography",
          "instructions": "Check headings use 'Inter' font. Verify #1A73E8 on all CTAs and links.",
          "contextGathering": { "strategies": ["web-page-text", "web-page-screenshot"] },
          "execution": { "executionStrategy": "ai" },
          "postProcess": { "guardrails": { "enabled": true } }
        },
        {
          "id": "1",
          "version": 1,
          "createdAt": 1711700000000,
          "name": "Brand Consistency Checker",
          "instructions": "Check headings use Inter font...",
          "contextGathering": { "strategies": ["web-page-text"] }
        }
      ]
    }
  }
}

Field	Type	Description
`data.versions`	object[]	Version snapshots ordered descending by version

Each entry contains the full behavioral snapshot of the agent at that version.

Failure Response

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

Errors: NOT_FOUND (agent or store database not found).

{
  "result": {
    "status": "success",
    "message": "Versions listed successfully",
    "data": {
      "versions": []
    }
  }
}

Get Execution Restore Agent Version

⌘I

​Endpoint

​Headers

​Body

​Params

​Example Requests

​List versions for an agent

​Response

​Success Response

​Failure Response

Endpoint

Headers

Body

Params

Example Requests

List versions for an agent

Response

Success Response

Failure Response