List Agent Versions

POST /v2/agents/versions/list

List Agent Versions

cURL

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