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
string
required
Your API authentication key
Path Parameters
string
required
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.
object
required
The fields to change. All of them are optional.
string
Agent display name. Maximum 255 characters.
string
What the agent does, shown under its name. Maximum 2048 characters.
string
Agent icon as a base64-encoded SVG (or PNG) — a plain string, with no
data: prefix. Maximum 65535 characters.object
Replacement implementation, in the shape matching the agent’s class. Replaces the stored blueprint wholesale. Maximum 256KB JSON-encoded. See Blueprint shapes.
object
Replacement input schema, keyed by each variable’s
variableName. Same shape and limits as on create — see Variable object.object
Replacement output schema. Same shape and limits as
inputs.string[]
Replacement category list. Maximum 5 entries. See Categories.
string
Agent status —
active, inactive, soon or deprecated.boolean
Show the “new” badge on the agent tile.
boolean
Show the “popular” badge on the agent tile.
boolean
Show the “beta” badge on the agent tile. Accepted but not echoed back in the response.
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.object
required
The blueprint itself. Fields below.
string
required
What the agent is for, in one sentence.
string
required
What the agent receives.
object[]
required
The inputs, itemised. Each entry is
{ name, description }.string
required
How the agent gets from input to output.
string
required
What the agent produces.
object[]
required
The outputs, itemised. Each entry is
{ name, description }.object[]
required
Ordered steps the agent must take, each
{ name, description }. The authoring tools expect between two and five; this endpoint does not enforce that.string
Longer prose about the agent, carried alongside the objective. Stored and handed back unchanged.
string
Model the agent runs on, for example
gpt-4o. Must be one the platform routes to.string
Provider of that model, for example
openai. Must agree with the model when both are given.string
Model to fall back to. Validated the same way as
model.string
Provider of the fallback model. Validated the same way as
provider.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
string
required
The agent id.
string
required
Agent display name.
string
Agent description.
string
Agent icon.
string[]
Categories the agent is filed under.
string
Agent status.
string
Id of the new version this call created.
string
Owning workspace, or
null when the agent is visible across the marketplace.Errors
Bad Request
Invalid body, an
agentId that is not a UUID, or a blueprint naming a model or provider the platform cannot route to.Unauthorized
Missing, invalid, or expired API key.
Forbidden
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.
Not Found
No agent with that id.
Unprocessable Entity
Rejected downstream after passing validation here.
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?