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

object

required

Show properties

string

required

Min 1 char. Agent ID.

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.

Alongside those three 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"
  }
}

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

⌘I

REST APIs

SDK

List Agent Versions

Endpoint

Headers

Body

Params

Example Requests

Response

Success Response

Failure Response

​Endpoint

​Headers

​Body

​Params

​Example Requests

​Response

​Success Response

​Failure Response

Endpoint

Headers

Body

Params

Example Requests

Response

Success Response

Failure Response