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

POST

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:

agentId provided: 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.
agentId omitted: returns a list of agents with identity-only fields. Optionally filter by filter (default vs custom) and/or groupId (members of an agent group).

Built-in agents flagged 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

string

required

Your API key.

string

required

Your Auth Token.

Body

Params

object

required

Show properties

string

Min 1 char. Agent ID. When provided, returns a single agent. When omitted, returns a list.

string

"defaultOnly" (built-in only) or "customOnly" (user-created only). Ignored when agentId is provided.

string

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)

Custom agents return the full configuration including behavioral fields from the version subcollection:

{
  "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": { "useMemory": true, "maxChunks": 10 }
        },
        "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": { "team": "growth", "owner": "jane", "apiKey": "ak_xxx" },
        "executionCount": 5,
        "lastExecutedAt": 1711900000000
      }
    }
  }
}

Any auth secrets are returned as "__redacted__"; they are never sent back in plaintext. This applies to both rest-api strategy secrets stored in contextGathering.strategyOptions and mcp-tools server secrets stored in execution.mcpServers[].auth.

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)

List rows are identity-only. Built-in agents include system: true; internal agents (crawler, screenshot) are omitted.

{
  "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": { "team": "growth", "owner": "jane" },
          "executionCount": 5,
          "lastExecutedAt": 1711900000000
        }
      ]
    }
  }
}

Failure Response

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

Errors: NOT_FOUND (agent or group not found) / INVALID_ARGUMENT (invalid filter value).

{
  "result": {
    "status": "success",
    "message": "Agents fetched successfully",
    "data": {
      "agents": []
    }
  }
}

Create Agent Update Agent (Identity)

⌘I

REST APIs

SDK

Get Agent(s)

Endpoint

Headers

Body

Params

Example Requests

1. Get a single custom agent

2. Get a single built-in agent

3. List all agents (no filter)

4. List only custom agents

5. List agents in a group

Response

Success Response (single custom agent)

Success Response (single built-in agent, sanitized)

Success Response (list)

Failure Response

​Endpoint

​Headers

​Body

​Params

​Example Requests

​1. Get a single custom agent

​2. Get a single built-in agent

​3. List all agents (no filter)

​4. List only custom agents

​5. List agents in a group

​Response

​Success Response (single custom agent)

​Success Response (single built-in agent, sanitized)

​Success Response (list)

​Failure Response

Endpoint

Headers

Body

Params

Example Requests

1. Get a single custom agent

2. Get a single built-in agent

3. List all agents (no filter)

4. List only custom agents

5. List agents in a group

Response

Success Response (single custom agent)

Success Response (single built-in agent, sanitized)

Success Response (list)

Failure Response