Get Agent(s)

POST /v2/agents/get

Get Agent(s)

cURL

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>"
  }
}
'

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