Get Agent(s)
curl --request POST \
--url https://api.velt.dev/v2/agents/get \
--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>",
"filter": "<string>",
"groupId": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/get"
payload = { "data": {
"agentId": "<string>",
"filter": "<string>",
"groupId": "<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>', filter: '<string>', groupId: '<string>'}})
};
fetch('https://api.velt.dev/v2/agents/get', 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/get",
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>',
'filter' => '<string>',
'groupId' => '<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/get"
payload := strings.NewReader("{\n \"data\": {\n \"agentId\": \"<string>\",\n \"filter\": \"<string>\",\n \"groupId\": \"<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/get")
.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 \"filter\": \"<string>\",\n \"groupId\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/get")
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 \"filter\": \"<string>\",\n \"groupId\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Agents fetched successfully",
"data": {
"agents": []
}
}
}
Agents
Get Agent(s)
POST
/
v2
/
agents
/
get
Get Agent(s)
curl --request POST \
--url https://api.velt.dev/v2/agents/get \
--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>",
"filter": "<string>",
"groupId": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/get"
payload = { "data": {
"agentId": "<string>",
"filter": "<string>",
"groupId": "<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>', filter: '<string>', groupId: '<string>'}})
};
fetch('https://api.velt.dev/v2/agents/get', 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/get",
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>',
'filter' => '<string>',
'groupId' => '<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/get"
payload := strings.NewReader("{\n \"data\": {\n \"agentId\": \"<string>\",\n \"filter\": \"<string>\",\n \"groupId\": \"<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/get")
.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 \"filter\": \"<string>\",\n \"groupId\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/get")
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 \"filter\": \"<string>\",\n \"groupId\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Agents fetched successfully",
"data": {
"agents": []
}
}
}
Use this API to fetch a single agent or list agents in your workspace. The endpoint behaves differently based on the provided fields:
Errors:
agentIdprovided: returns a single agent. For custom agents, the response merges identity + behavioral fields from the version subcollection. For built-in agents, only sanitized public fields are returned.agentIdomitted: returns a list of agents with identity-only fields. Optionally filter byfilter(default vs custom) and/orgroupId(members of an agent group).
metadata.internal: true (e.g. crawler, screenshot) are excluded from list responses but can still be fetched individually.
Endpoint
POST https://api.velt.dev/v2/agents/get
Headers
Your API key.
Your Auth Token.
Body
Params
Show properties
Show properties
Min 1 char. Agent ID. When provided, returns a single agent. When omitted, returns a list.
"defaultOnly" (built-in only) or "customOnly" (user-created only). Ignored when agentId is provided.Min 1 char. Agent group id. When provided (and
agentId omitted), returns only agents that are members of the group, ordered by the group’s agentIds array. Compatible with filter. Unknown group ids return NOT_FOUND.Example Requests
1. Get a single custom agent
{
"data": {
"agentId": "abc123def456"
}
}
2. Get a single built-in agent
{
"data": {
"agentId": "spell-check"
}
}
3. List all agents (no filter)
{
"data": {}
}
4. List only custom agents
{
"data": {
"filter": "customOnly"
}
}
5. List agents in a group
{
"data": {
"groupId": "grp_brand_qa"
}
}
Response
Success Response (single custom agent)
{
"result": {
"status": "success",
"message": "Agent fetched successfully",
"data": {
"agent": {
"id": "abc123def456",
"name": "Brand Consistency Checker",
"description": "Validates brand colors and typography",
"enabled": true,
"version": 3,
"managedBy": "customer",
"rawInstructions": "Check that all headings use the brand font 'Inter'...",
"instructions": "Check that all headings use the brand font 'Inter'...",
"contextGathering": {
"strategies": ["web-page-text", "web-page-screenshot"]
},
"execution": {
"executionStrategy": "ai",
"responseDescriptions": { "title": "Short name for the brand inconsistency" },
"knowledge": { "sourceIds": ["ks_brand_guidelines_v2"], "useMemory": true }
},
"response": { "useAiFormatting": false },
"postProcess": {
"guardrails": { "enabled": true },
"matchAndMerge": { "enabled": true },
"annotations": { "enabled": true, "strategy": "findings" }
},
"input": {
"inputRequirements": { "requires": ["url"] },
"userContextFields": [
{ "id": "brand_color", "title": "Primary brand color?", "type": "string", "required": true }
]
},
"scope": {
"pageScope": ["https://example.com/*"],
"crossPage": { "enabled": true, "targetProperty": "brandConsistency", "pageDiscovery": "auto" }
},
"metadata": { "type": "qa", "category": "brand" },
"executionCount": 5,
"lastExecutedAt": 1711900000000
}
}
}
}
Success Response (single built-in agent — sanitized)
Built-in agents return only public fields. Internal implementation fields (instructions, contextGathering, execution, postProcess, response, payloadSchema, supportedVariables) are stripped.
{
"result": {
"status": "success",
"message": "Agent fetched successfully",
"data": {
"agent": {
"id": "spell-check",
"name": "Spell Check",
"description": "Finds spelling mistakes and typos in page content using AI analysis",
"enabled": true,
"managedBy": "velt",
"metadata": { "type": "system", "category": "quality" },
"system": true,
"inputRequirements": { "requires": ["url"] },
"userContextFields": [],
"executionCount": 142,
"lastExecutedAt": 1711900000000
}
}
}
}
Success Response (list)
{
"result": {
"status": "success",
"message": "Agents fetched successfully",
"data": {
"agents": [
{
"id": "spell-check",
"name": "Spell Check",
"description": "Finds spelling mistakes and typos",
"system": true,
"enabled": true,
"managedBy": "velt",
"metadata": { "type": "system", "category": "quality" },
"executionCount": 142,
"lastExecutedAt": 1711900000000
},
{
"id": "abc123def456",
"name": "Brand Consistency Checker",
"description": "Validates brand colors and typography",
"enabled": true,
"managedBy": "customer",
"version": 3,
"metadata": { "type": "qa", "category": "brand" },
"executionCount": 5,
"lastExecutedAt": 1711900000000
}
]
}
}
}
Failure Response
{
"error": {
"message": "ERROR_MESSAGE",
"status": "NOT_FOUND"
}
}
NOT_FOUND (agent or group not found) / INVALID_ARGUMENT (invalid filter value).
{
"result": {
"status": "success",
"message": "Agents fetched successfully",
"data": {
"agents": []
}
}
}
Was this page helpful?
⌘I