Update Agent (Identity)

POST /v2/agents/update

Update Agent (Identity)

cURL

curl --request POST \
  --url https://api.velt.dev/v2/agents/update \
  --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>",
    "name": "<string>",
    "description": "<string>",
    "enabled": true
  }
}
'

import requests

url = "https://api.velt.dev/v2/agents/update"

payload = { "data": {
        "agentId": "<string>",
        "name": "<string>",
        "description": "<string>",
        "enabled": True
    } }
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>', name: '<string>', description: '<string>', enabled: true}
  })
};

fetch('https://api.velt.dev/v2/agents/update', 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/update",
  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>',
        'name' => '<string>',
        'description' => '<string>',
        'enabled' => true
    ]
  ]),
  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/update"

	payload := strings.NewReader("{\n  \"data\": {\n    \"agentId\": \"<string>\",\n    \"name\": \"<string>\",\n    \"description\": \"<string>\",\n    \"enabled\": true\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/update")
  .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    \"name\": \"<string>\",\n    \"description\": \"<string>\",\n    \"enabled\": true\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.velt.dev/v2/agents/update")

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    \"name\": \"<string>\",\n    \"description\": \"<string>\",\n    \"enabled\": true\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "result": {
    "status": "success",
    "message": "Agent updated successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}

Use this API to update identity fields (name, description, enabled) on the root agent document. No new version is created. Use Update Agent Version for behavioral edits.

Works for both custom and built-in agents, but built-in agents only support updating enabled. Server-managed fields (id, apiKey, managedBy, metadata, version, createdAt, updatedAt) cannot be set through this endpoint.

Endpoint

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

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 · required

Min 1 char. Agent ID to update (custom or built-in).

name · string

Min 1 char. New display name. Not allowed for built-in agents.

description · string

New human-readable description. Not allowed for built-in agents.

enabled · boolean

Whether the agent is active.

At least one of name, description, or enabled should be provided.

Example Requests

1. Rename a custom agent

{
  "data": {
    "agentId": "abc123def456",
    "name": "Updated Brand Checker",
    "description": "Now also checks footer typography"
  }
}

2. Disable an agent

{
  "data": {
    "agentId": "abc123def456",
    "enabled": false
  }
}

3. Enable a built-in agent

{
  "data": {
    "agentId": "spell-check",
    "enabled": true
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Agent updated successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}

Field	Type	Description
data.agentId	string	The ID of the updated agent

Failure Response

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

Errors: INVALID_ARGUMENT (sending name or description for a built-in agent — only enabled is allowed) / NOT_FOUND (agent does not exist).

{
  "result": {
    "status": "success",
    "message": "Agent updated successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}