Update agent (new revision)

put

https://api.agent700.ai/api/agents/{agentId}

Creates a new revision of an existing agent. If the agent does not
exist for the current user, a new agent may be created.

Accepts all AgentCreateRequest / AgentRevisionConfigBase fields
(including promptCachingEnabled and promptCacheKey) plus
AgentRevisionConfigUpdateOnly (reasoningEffort, thinkingEnabled,
thinkingBudgetTokens, searchDomainFilter, searchRecencyFilter) and
agent-level customShareUrl, allowPublicSharing, and hasPhoneNumber.
Omitted revision fields are preserved from the current revision.

JSON Structured Output can be enabled or disabled via the
jsonOutputEnabled and jsonSchema fields. When enabling, provide a
valid JSON Schema Draft 7 object or string. When disabling, set
jsonOutputEnabled: false and jsonSchema: null.

Set model to a name from GET /api/models (not displayName).
Deprecated or inactive catalog entries are rejected with 400.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

agentId

string

required

Agent GUID

Body Params

Agent update data. Creates a new revision of the existing agent. All fields are optional
and will use defaults if not provided. If the agent doesn't exist for the current user,
a new agent may be created. Requires a valid paid account (payment_required middleware).

Body for PUT /api/agents/{agentId}. Creates a new revision. Omitted revision
fields are copied from the current revision. Agent-level sharing and phone
fields update the parent agent record. No fields are required.

name

string

Display name for this revision.

masterPrompt

string | null

System prompt sent to the model for this agent revision.

introductoryText

string | null

User-facing greeting or intro shown before the first turn.

imageDimensions

string

Image size hint for image-generation models (e.g. 1024x1024).

model

string

Model name from GET /api/models. Deprecated or inactive models are
rejected with 400.

temperature

float

Sampling temperature for the model.

topP

float | null

Nucleus sampling parameter (top_p).

maxTokens

integer

Maximum completion tokens (subject to model limits).

scrubPii

boolean

When true, scrubs PII from messages using piiThreshold before sending
to the model.

piiThreshold

float

PII detection confidence threshold when scrubPii is enabled.

smartDocEvaluation

boolean

When true, uses embedding-based smart document evaluation for alignment
placeholders in prompts.

smartDocChunkSize

integer

Chunk size (characters) for smart document evaluation.

smartDocChunkOverlap

integer

Overlap (characters) between smart-doc chunks.

smartDocEmbeddingModel

string

Embedding model name for smart document evaluation.

smartDocTopK

integer

Top-K relevant chunks retrieved during smart document evaluation.

fullDocAnalysis

boolean

When true, runs full-document analysis over alignment placeholders.

fullDocChunkSize

integer

Chunk size (characters) for full document analysis.

fullDocChunkOverlap

integer

Overlap (characters) between full-doc chunks.

fullDocMaxLength

integer

Maximum total text length considered during full document analysis.

enableMcp

boolean

Enables MCP (Model Context Protocol) tools for this agent when the
selected model supports MCP.

mcpServerNames

array of strings

MCP server names this agent may use.

mcpServerNames

mcpAutoApprove

boolean

When true, MCP tool calls are approved automatically without user confirmation.

promptCachingEnabled

boolean | null

Defaults to true

When true, enables automatic prompt caching for models that support it
(supportsPromptCaching on GET /api/models). Anthropic requests receive
top-level cache_control; OpenAI/Mistral receive prompt_cache_key and
xAI receives x-grok-conv-id when supportsPromptCacheId is true.
Cache token usage is always billed correctly when the provider reports it.
Defaults to true for new agents. Set on POST /api/agents or
PUT /api/agents/{agentId}.

promptCacheKey

string | null

Optional cache routing key for providers that accept one
(supportsPromptCacheId). When blank/omitted and caching is enabled,
agentId is used automatically. Do not put secrets or PII in this value.
Ignored for Claude and Gemini (no provider routing-key parameter).

jsonOutputEnabled

boolean

Defaults to false

Enables JSON Structured Output, forcing responses to conform to jsonSchema.
Not available for image generation models (names starting with img).
Requires a valid schema when enabled.

jsonSchema

JSON Schema (Draft 7) for structured output. Responses return a parsed object;
requests accept a JSON object or a JSON-encoded string.

reasoningEffort

string | null

Reasoning effort for models that support explicit reasoning modes. Valid
values depend on the model (supportedReasoningEfforts on GET /api/models).

thinkingEnabled

boolean | null

Enables extended thinking for models that support it (e.g. Claude).

thinkingBudgetTokens

integer | null

Token budget for thinking when thinkingEnabled is true.

searchDomainFilter

array of strings

Optional list of domains to restrict web/search-augmented models (when supported).

searchDomainFilter

searchRecencyFilter

string | null

Optional recency filter for search-augmented models (when supported).
Provider-specific values (e.g. day, week, month).

organizationId

uuid

Used only when the agent does not exist for the caller; triggers create
instead of update (same as POST /api/agents).

customShareUrl

string | null

Public share URL slug (agent-level, not revision-specific).

allowPublicSharing

boolean

Enable or disable public sharing for this agent.

hasPhoneNumber

boolean

When true, provisions the platform default phone number on the agent.

Responses

200Agent updated

403Access denied