Update Agent Version

POST /v2/agents/version/update

Update Agent Version

cURL

curl --request POST \
  --url https://api.velt.dev/v2/agents/version/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>",
    "rawInstructions": "<string>",
    "instructions": "<string>",
    "phaseTimeoutMs": 123,
    "metadata": {},
    "contextGathering": {},
    "execution": {},
    "response": {},
    "postProcess": {},
    "input": {},
    "scope": {},
    "setup": {}
  }
}
'

{
  "result": {
    "status": "success",
    "message": "Agent version created successfully",
    "data": {
      "version": 4
    }
  }
}

Use this API to update behavioral/version fields. This creates a new version N+1 in the versions subcollection and bumps the version pointer on the root document. Only supported for custom agents.

In-flight executions stay pinned to whatever version they started on, so updating a version never disturbs a running execution.

The schema uses .passthrough(), so additional behavioral fields are forwarded to the service layer.

The merge is one level deep. Each top-level block you send (contextGathering, execution, response, postProcess, input, scope, setup) is merged onto its stored counterpart, but anything nested inside is replaced wholesale, not merged.

So sending { "scope": { "crossPage": { "enabled": false, "targetProperty": "brandConsistency", "pageDiscovery": "auto" } } } does not just flip enabled. It replaces the whole crossPage object, silently discarding the stored pages list and sourceOfTruthKnowledgeSourceId, and returns 200. Nothing warns you. The same applies to execution.mcpServers, input.userContextFields, and contextGathering.strategyOptions: send the complete nested object every time, not just the keys you want to change.

Drop a required key and you get the louder failure instead: { "scope": { "crossPage": { "enabled": false } } } is rejected with INVALID_ARGUMENT, because targetProperty and pageDiscovery are required whenever crossPage is present.

Fetch the current config with Get Agent first, apply your change to the full nested object, and send that. Read the credential warning below before you do.

Never send a redacted secret back. Get Agent returns auth secrets as the literal string "__redacted__". This endpoint has no special handling for that value, so a fetch-modify-send round trip stores "__redacted__" as the real credential and the server starts failing authentication at execution time, not at update time.

To change something else on an agent that has stored secrets, either omit execution.mcpServers and contextGathering.strategyOptions from your patch entirely, or re-send every object with its real plaintext secret. Rotating a secret is the same operation: send the new plaintext value.

​

Endpoint

POST https://api.velt.dev/v2/agents/version/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

Custom agent ID.

rawInstructions · string

Original user-provided instructions.

instructions · string

Processed/enhanced instructions.

phaseTimeoutMs · number

Per-phase timeout in milliseconds. Positive integer, no upper bound. Omit to use the platform default.

metadata · object

Arbitrary client metadata. Replaces the stored object rather than merging into it.

contextGathering · object

Context gathering config. Same shape as Create Agent.

execution · object

Execution config, including executionStrategy, the strict knowledge (Memory-RAG) block, and mcpServers for the "mcp-tools" strategy. Same shape as Create Agent.

Rotate an MCP or REST auth secret by sending the new plaintext value here. Because mcpServers is an array, sending it replaces the stored array in full: a server object sent without its auth block loses the stored secret. To keep existing secrets, either omit mcpServers entirely or re-send every server object with its real plaintext secret. Re-sending the "__redacted__" placeholder from a Get Agent response stores that string as the credential.

response · object

Response formatting config. Same shape as Create Agent.

postProcess · object

Post-processing pipeline config. Same shape as Create Agent, including findingEnrichment.commentFormat (Comment format).

input · object

Input declaration config. Same shape as Create Agent.

scope · object

Scope and targeting config. Same shape as Create Agent.

setup · object

Setup assistant metadata. Same shape as Create Agent.

​

Example Requests

​

1. Update instructions and post-processing

{
  "data": {
    "agentId": "abc123def456",
    "instructions": "Check headings use 'Inter' font. Verify #1A73E8 on all CTAs and links.",
    "postProcess": {
      "guardrails": { "enabled": true },
      "deletePreviousSuggestions": { "enabled": true }
    }
  }
}

​

2. Update context gathering strategies

{
  "data": {
    "agentId": "abc123def456",
    "contextGathering": {
      "strategies": ["web-page-text", "web-page-html", "web-page-screenshot"]
    }
  }
}

​

3. Enable cross-page via scope

{
  "data": {
    "agentId": "abc123def456",
    "scope": {
      "crossPage": {
        "enabled": true,
        "targetProperty": "brandConsistency",
        "pageDiscovery": "manual",
        "pages": ["https://example.com", "https://example.com/about"]
      }
    }
  }
}

​

4. Switch to the plain comment format

The agent’s next runs post comments with a bold title, a detail line, and the suggestion, with no Suggestion: label. The other postProcess keys you stored are kept.

{
  "data": {
    "agentId": "abc123def456",
    "postProcess": {
      "findingEnrichment": { "commentFormat": "plain" }
    }
  }
}

​

Response

​

Success Response

{
  "result": {
    "status": "success",
    "message": "Agent version created successfully",
    "data": {
      "version": 4
    }
  }
}

Field	Type	Description
data.version	number	New version number after the update

​

Failure Response

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

Errors: INVALID_ARGUMENT (validation failure, including a nested block that lost required fields to the one-level merge, a userContextFields id that is a reserved run-scope or run-control key, or blanking instructions on an agent whose effective executionStrategy still requires a prompt) / NOT_FOUND (agent does not exist).

instructions is re-validated against the merged result, not against your patch alone. The merged instructions must be non-empty whenever the merged executionStrategy is "ai", "service+ai", "stagehand-agent", or "mcp-tools". Whitespace-only counts as empty.

So clearing instructions on an existing AI agent is rejected, even though the field is optional on this endpoint.

{
  "result": {
    "status": "success",
    "message": "Agent version created successfully",
    "data": {
      "version": 4
    }
  }
}