curl --request PATCH \
--url https://operator.opus.com/api/v1/agent/{AGENT_ID} \
--header 'Content-Type: application/json' \
--header 'x-service-key: {YOUR_SERVICE_KEY}' \
--data '{
"agent": {
"name": "Adder v2",
"description": "Adds two numbers and returns the total",
"categories": ["numerical_computation", "aggregation_and_analysis"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant. Show no working.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
"model": "gpt-4o",
"provider": "openai"
},
"status": "active",
"isNew": false
}
}'
import requests
agent_id = "{AGENT_ID}"
url = f"https://operator.opus.com/api/v1/agent/{agent_id}"
headers = {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
"agent": {
"name": "Adder v2",
"description": "Adds two numbers and returns the total",
"categories": ["numerical_computation", "aggregation_and_analysis"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant. Show no working.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
"model": "gpt-4o",
"provider": "openai",
},
"status": "active",
"isNew": False,
}
}
response = requests.patch(url, json=payload, headers=headers)
print(response.json())
const agentId = "{AGENT_ID}";
const response = await fetch(`https://operator.opus.com/api/v1/agent/${agentId}`, {
method: "PATCH",
headers: {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}",
},
body: JSON.stringify({
agent: {
name: "Adder v2",
description: "Adds two numbers and returns the total",
categories: ["numerical_computation", "aggregation_and_analysis"],
blueprint: {
systemPrompt: "You are a careful arithmetic assistant. Show no working.",
userPrompt: "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
model: "gpt-4o",
provider: "openai",
},
status: "active",
isNew: false,
},
}),
});
const data = await response.json();
console.log(data);
{
"id": "{AGENT_ID}",
"name": "Adder v2",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation", "aggregation_and_analysis"],
"status": "active",
"versionId": "{NEW_AGENT_VERSION_ID}",
"groupId": null
}
Agents
Update an Agent
Revise an agent your organization owns, cutting a new version
PATCH
/
api
/
v1
/
agent
/
{agentId}
curl --request PATCH \
--url https://operator.opus.com/api/v1/agent/{AGENT_ID} \
--header 'Content-Type: application/json' \
--header 'x-service-key: {YOUR_SERVICE_KEY}' \
--data '{
"agent": {
"name": "Adder v2",
"description": "Adds two numbers and returns the total",
"categories": ["numerical_computation", "aggregation_and_analysis"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant. Show no working.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
"model": "gpt-4o",
"provider": "openai"
},
"status": "active",
"isNew": false
}
}'
import requests
agent_id = "{AGENT_ID}"
url = f"https://operator.opus.com/api/v1/agent/{agent_id}"
headers = {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
"agent": {
"name": "Adder v2",
"description": "Adds two numbers and returns the total",
"categories": ["numerical_computation", "aggregation_and_analysis"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant. Show no working.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
"model": "gpt-4o",
"provider": "openai",
},
"status": "active",
"isNew": False,
}
}
response = requests.patch(url, json=payload, headers=headers)
print(response.json())
const agentId = "{AGENT_ID}";
const response = await fetch(`https://operator.opus.com/api/v1/agent/${agentId}`, {
method: "PATCH",
headers: {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}",
},
body: JSON.stringify({
agent: {
name: "Adder v2",
description: "Adds two numbers and returns the total",
categories: ["numerical_computation", "aggregation_and_analysis"],
blueprint: {
systemPrompt: "You are a careful arithmetic assistant. Show no working.",
userPrompt: "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
model: "gpt-4o",
provider: "openai",
},
status: "active",
isNew: false,
},
}),
});
const data = await response.json();
console.log(data);
{
"id": "{AGENT_ID}",
"name": "Adder v2",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation", "aggregation_and_analysis"],
"status": "active",
"versionId": "{NEW_AGENT_VERSION_ID}",
"groupId": null
}
Revise an agent your organization owns.
Every field is optional — omitted fields keep their current value. Each call cuts a new agent version rather than editing in place, so the previous state stays addressable.
Use the
id returned by Create an Agent as {agentId}.
Requires the Agent: Full permission at organization level.
blueprint, inputs and outputs are replaced wholesale, not merged field by field. Send the complete object you want stored — a partial inputs map drops every variable you left out.Unlike create, this endpoint can target either kind of agent: a Custom Agent authored through the API, or an Opus Agent authored in the Opus app. An agent’s class is fixed when it is created and cannot be changed here — the
blueprint you send must match it. See Blueprint shapes.Headers
Path Parameters
The agent to revise. This is
id from Create an Agent — not its versionId. Must be a UUID.Body Parameters
The agent is nested under anagent key.
Agent icon as a base64-encoded SVG (or PNG) — a plain string, with no
data: prefix. Maximum 65535 characters.Replacement implementation, in the shape matching the agent’s class. Replaces the stored blueprint wholesale. Maximum 256KB JSON-encoded. See Blueprint shapes.
Replacement input schema, keyed by each variable’s
variableName. Same shape and limits as on create — see Variable object.Replacement category list. Maximum 5 entries. See Categories.
Blueprint shapes
blueprint takes one of two shapes, depending on the class of the agent you are updating. Whichever shape you send, its model/provider pair and its backupModel/backupProvider pair are validated exactly as they are on create — see Models and providers.
Custom Agents
Every agent created through Create an Agent is a Custom Agent — a model driven by a system prompt and a prompt. Send the same shape that endpoint takes, see Blueprint.Opus Agents
An Opus Agent follows a blueprint of ordered steps instead of raw prompts. These cannot be created through the API, but one authored in the Opus app can be revised here.Ordered steps the agent must take, each
{ name, description }. The authoring tools expect between two and five; this endpoint does not enforce that.Longer prose about the agent, carried alongside the objective. Stored and handed back unchanged.
blueprint is forwarded untouched and stored verbatim, and this endpoint does not check it against the agent’s class — a blueprint of steps sent to a Custom Agent is stored as-is and leaves it running on empty prompts. Send the shape that matches the agent you are updating.Response
Errors
Invalid body, an
agentId that is not a UUID, or a blueprint naming a model or provider the platform cannot route to.The agent belongs to another organization, the API key is not org-scoped, or the key owner lacks the Agent: Full permission in the organization.
curl --request PATCH \
--url https://operator.opus.com/api/v1/agent/{AGENT_ID} \
--header 'Content-Type: application/json' \
--header 'x-service-key: {YOUR_SERVICE_KEY}' \
--data '{
"agent": {
"name": "Adder v2",
"description": "Adds two numbers and returns the total",
"categories": ["numerical_computation", "aggregation_and_analysis"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant. Show no working.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
"model": "gpt-4o",
"provider": "openai"
},
"status": "active",
"isNew": false
}
}'
import requests
agent_id = "{AGENT_ID}"
url = f"https://operator.opus.com/api/v1/agent/{agent_id}"
headers = {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
"agent": {
"name": "Adder v2",
"description": "Adds two numbers and returns the total",
"categories": ["numerical_computation", "aggregation_and_analysis"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant. Show no working.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
"model": "gpt-4o",
"provider": "openai",
},
"status": "active",
"isNew": False,
}
}
response = requests.patch(url, json=payload, headers=headers)
print(response.json())
const agentId = "{AGENT_ID}";
const response = await fetch(`https://operator.opus.com/api/v1/agent/${agentId}`, {
method: "PATCH",
headers: {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}",
},
body: JSON.stringify({
agent: {
name: "Adder v2",
description: "Adds two numbers and returns the total",
categories: ["numerical_computation", "aggregation_and_analysis"],
blueprint: {
systemPrompt: "You are a careful arithmetic assistant. Show no working.",
userPrompt: "Add {{firstNumber}} and {{secondNumber}} and return only the total.",
model: "gpt-4o",
provider: "openai",
},
status: "active",
isNew: false,
},
}),
});
const data = await response.json();
console.log(data);
{
"id": "{AGENT_ID}",
"name": "Adder v2",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation", "aggregation_and_analysis"],
"status": "active",
"versionId": "{NEW_AGENT_VERSION_ID}",
"groupId": null
}
Was this page helpful?