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, the response contains the agent’s identity fields.
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).

Endpoint

POST https://api.velt.dev/v2/agents/get

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

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

filter

string

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

groupId

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 },
          "deletePreviousSuggestions": { "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" }
        }
      }
    }
  }
}

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.executionCount / lastExecutedAt are returned only on list responses, not on single-agent fetches.

Success Response (single built-in agent)

Built-in agents return their identity fields: id, name, description, enabled, managedBy, system, and input when the agent declares one.

{
  "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",
        "system": true
      }
    }
  }
}

Success Response (list)

List rows are identity-only. Built-in agents include system: true.

{
  "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",
          "executionCount": 142,
          "lastExecutedAt": 1711900000000
        },
        {
          "id": "abc123def456",
          "name": "Brand Consistency Checker",
          "description": "Validates brand colors and typography",
          "enabled": true,
          "managedBy": "customer",
          "version": 3,
          "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)

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)

​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)

Success Response (list)

Failure Response