Agents

Update agent

OpenAI SDK-style partial update. Only the listed fields are accepted; supplied fields replace the saved values and create a new version. No row_version is needed. Archived Agents return 404.

post/v1/agents/{agent_id}

Request

  • Base URL: https://api.sandbase.ai
  • URL: https://api.sandbase.ai/v1/agents/{agent_id}
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Headers

Idempotency-Keystring

Optional. Send a stable key so retries do not create duplicates.

OpenAI-Beta'agents=v1'

Optional OpenAI SDK header. When present it must be agents=v1.

Request body

namestring
modelstring
instructionsstring
metadataobject
service_tier'auto' | 'default' | 'flex' | 'priority' | 'fast'
runtime_profile'codex' | 'claude' | 'mcode'
toolsobject[]

Response

Updated Agent

idstring required

Agent ID (agt_ prefix).

object'agent' required
modelstring required
namestring nullable required
instructionsstring nullable required
toolsobject[] required
reasoningobject required
service_tierstring required
multi_agentobject required

Always reports enabled false.

visibility'private' | 'public' required
status'active' | 'archived' required
versioninteger required

Current version number.

row_versioninteger required

Compare-and-set token for PATCH, archive, unarchive, and restore.

projection_statusstring required

Whether the current version is ready for execution. Sessions require ready.

runtime_profile'codex' | 'claude' | 'mcode' required
descriptionstring required
metadataobject required
created_atinteger required

Unix seconds.

updated_atinteger required

Unix seconds.

archived_atinteger nullable required

Unix seconds.

failure_codestring

Changes

No recorded changes to this operation across all 1 revision of this API.