Update Agent

POST/v1/agents/{agent_id}

Update an agent configuration. Every effective change creates a new immutable version; existing sessions keep the version they started with.

Path parameters

stringagent_idrequired

Unique agent identifier beginning with agent_.

Request body

Optional<integer>version

Optional current Agent version for optimistic locking. When omitted, the server applies the update to the version it just loaded.

Optional<string>model

Replacement model identifier. Omit to preserve the current value.

Optional<string>name

Replacement name. Omit to preserve the current value.

Optional<string · null>description

Replacement description. Send null or an empty string to clear it.

Optional<string · null>system

Replacement system instructions. Send null or an empty string to clear them.

Optional<array · null>tools

Full replacement tool list. Send an empty array or null to clear all tools.

Optional<object>metadata

Full replacement metadata object. Omitted metadata is preserved; supplied metadata replaces caller-owned metadata rather than merging individual keys.

Optimistic locking

When version is supplied, a stale value returns 409 conflict. Fetch the current Agent, reapply the change, and retry with the latest version.

Array replacement

The tools array is not merged. Read the current agent and send the complete intended list when adding or removing one tool.

Errors

400invalid_request

One or more fields have invalid values.

401authentication_error

The API key is missing or invalid.

404not_found

The agent does not exist.

409conflict

The supplied version does not match the current agent version.

curl -X POST \
  "https://api.sandbase.ai/v1/agents/agent_01HqR2k7..." \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "system": "Research carefully and always cite sources."
  }'

Response200 OK

{
  "id": "agent_01HqR2k7...",
  "type": "agent",
  "version": 2,
  "name": "Research Assistant",
  "model": {"id": "claude-sonnet-4", "effort": {"type": "high"}, "speed": "standard"},
  "system": "Research carefully and always cite sources.",
  "updated_at": "2026-05-29T11:00:00Z"
}