curl --request POST \
--url https://operator.opus.com/api/v1/agent \
--header 'Content-Type: application/json' \
--header 'x-service-key: {YOUR_SERVICE_KEY}' \
--data '{
"agent": {
"name": "Adder",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return the total.",
"model": "gpt-4o",
"provider": "openai"
},
"inputs": {
"firstNumber": {
"id": "1",
"variableName": "firstNumber",
"displayName": "First Number",
"allowedTypes": [{ "type": "float" }]
},
"secondNumber": {
"id": "2",
"variableName": "secondNumber",
"displayName": "Second Number",
"allowedTypes": [{ "type": "float" }]
}
},
"outputs": {
"sumResult": {
"id": "1",
"variableName": "sumResult",
"displayName": "Sum Result",
"allowedTypes": [{ "type": "float" }]
}
}
}
}'
import requests
url = "https://operator.opus.com/api/v1/agent"
headers = {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
"agent": {
"name": "Adder",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return the total.",
"model": "gpt-4o",
"provider": "openai",
},
"inputs": {
"firstNumber": {
"id": "1",
"variableName": "firstNumber",
"displayName": "First Number",
"allowedTypes": [{"type": "float"}],
},
"secondNumber": {
"id": "2",
"variableName": "secondNumber",
"displayName": "Second Number",
"allowedTypes": [{"type": "float"}],
},
},
"outputs": {
"sumResult": {
"id": "1",
"variableName": "sumResult",
"displayName": "Sum Result",
"allowedTypes": [{"type": "float"}],
}
},
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
const response = await fetch("https://operator.opus.com/api/v1/agent", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}",
},
body: JSON.stringify({
agent: {
name: "Adder",
description: "Adds two numbers and returns the total",
icon: "{BASE64_ICON}",
categories: ["numerical_computation"],
blueprint: {
systemPrompt: "You are a careful arithmetic assistant.",
userPrompt: "Add {{firstNumber}} and {{secondNumber}} and return the total.",
model: "gpt-4o",
provider: "openai",
},
inputs: {
firstNumber: {
id: "1",
variableName: "firstNumber",
displayName: "First Number",
allowedTypes: [{ type: "float" }],
},
secondNumber: {
id: "2",
variableName: "secondNumber",
displayName: "Second Number",
allowedTypes: [{ type: "float" }],
},
},
outputs: {
sumResult: {
id: "1",
variableName: "sumResult",
displayName: "Sum Result",
allowedTypes: [{ type: "float" }],
},
},
},
}),
});
const data = await response.json();
console.log(data);
{
"id": "{AGENT_ID}",
"name": "Adder",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation"],
"status": "active",
"isNew": true,
"isPopular": false,
"versionId": "{AGENT_VERSION_ID}",
"groupId": null
}
Agents
Create an Agent
Register a Custom Agent with its prompts and IO schema
POST
/
api
/
v1
/
agent
curl --request POST \
--url https://operator.opus.com/api/v1/agent \
--header 'Content-Type: application/json' \
--header 'x-service-key: {YOUR_SERVICE_KEY}' \
--data '{
"agent": {
"name": "Adder",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return the total.",
"model": "gpt-4o",
"provider": "openai"
},
"inputs": {
"firstNumber": {
"id": "1",
"variableName": "firstNumber",
"displayName": "First Number",
"allowedTypes": [{ "type": "float" }]
},
"secondNumber": {
"id": "2",
"variableName": "secondNumber",
"displayName": "Second Number",
"allowedTypes": [{ "type": "float" }]
}
},
"outputs": {
"sumResult": {
"id": "1",
"variableName": "sumResult",
"displayName": "Sum Result",
"allowedTypes": [{ "type": "float" }]
}
}
}
}'
import requests
url = "https://operator.opus.com/api/v1/agent"
headers = {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
"agent": {
"name": "Adder",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return the total.",
"model": "gpt-4o",
"provider": "openai",
},
"inputs": {
"firstNumber": {
"id": "1",
"variableName": "firstNumber",
"displayName": "First Number",
"allowedTypes": [{"type": "float"}],
},
"secondNumber": {
"id": "2",
"variableName": "secondNumber",
"displayName": "Second Number",
"allowedTypes": [{"type": "float"}],
},
},
"outputs": {
"sumResult": {
"id": "1",
"variableName": "sumResult",
"displayName": "Sum Result",
"allowedTypes": [{"type": "float"}],
}
},
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
const response = await fetch("https://operator.opus.com/api/v1/agent", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}",
},
body: JSON.stringify({
agent: {
name: "Adder",
description: "Adds two numbers and returns the total",
icon: "{BASE64_ICON}",
categories: ["numerical_computation"],
blueprint: {
systemPrompt: "You are a careful arithmetic assistant.",
userPrompt: "Add {{firstNumber}} and {{secondNumber}} and return the total.",
model: "gpt-4o",
provider: "openai",
},
inputs: {
firstNumber: {
id: "1",
variableName: "firstNumber",
displayName: "First Number",
allowedTypes: [{ type: "float" }],
},
secondNumber: {
id: "2",
variableName: "secondNumber",
displayName: "Second Number",
allowedTypes: [{ type: "float" }],
},
},
outputs: {
sumResult: {
id: "1",
variableName: "sumResult",
displayName: "Sum Result",
allowedTypes: [{ type: "float" }],
},
},
},
}),
});
const data = await response.json();
console.log(data);
{
"id": "{AGENT_ID}",
"name": "Adder",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation"],
"status": "active",
"isNew": true,
"isPopular": false,
"versionId": "{AGENT_VERSION_ID}",
"groupId": null
}
Register a Custom Agent in the marketplace under your organization.
The agent is authored at the organization level, so it is not bound to a workspace and is not runnable until it is connected into one. Returns the agent
id, which you pass to Update an Agent.
Requires the Agent: Full permission at organization level.
Every agent created here is a Custom Agent. There is no
agentClass field to set — the class is pinned, and blueprint must carry the prompts the agent runs with.There is no provider call to make first. Your organization’s agent provider is created on demand on your first agent, and
providerId is not accepted in the body.Headers
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.The agent implementation: the prompts the agent runs with, plus the model that runs them. See Blueprint. Maximum 256KB JSON-encoded.
Categories the agent is filed under in the marketplace. Maximum 5 entries. See Categories.
The agent’s input schema, keyed by each variable’s
variableName. Maximum 100 entries and 512KB JSON-encoded. See Variable object.The agent’s output schema, keyed by each variable’s
variableName. Same shape and limits as inputs.Show the “beta” badge on the agent tile. Accepted on create but not echoed back in the response.
Your organization is always taken from the API key — it cannot be set in the body. Nothing here is workspace-scoped.
Blueprint
The prompts the agent runs with.User prompt template. Must be non-empty. Reference the agent’s inputs with
{{variableName}}.Model the agent runs on, for example
gpt-4o. Must be one the platform routes to — see Models and providers.systemPrompt and userPrompt may be sent in either camelCase or snake_case (system_prompt, user_prompt). A blueprint missing either one, or carrying an empty or whitespace-only value for it, is rejected with 400.Apart from the prompts and these two pairs,
blueprint is forwarded untouched and stored verbatim — nothing else in it is validated structurally beyond its encoded size. The fields above are a base, not a ceiling: extra fields are kept, and unrecognised keys are forwarded exactly as they arrived. The documented camelCase keys are renamed to the agent service’s snake_case at the boundary.Models and providers
model and provider are checked before the agent is created, and the same rules apply to backupModel and backupProvider. Both pairs are accepted in either casing (backup_model, backup_provider).
A model is accepted when the platform’s model registry knows it, or when its name begins with a prefix belonging to a provider the platform routes to — gpt-, o followed by a digit, and chatgpt for openai, claude for anthropic, gemini for google. The prefix fallback means a model released before the registry catches up is still accepted, so claude-opus-9-future passes while llama-3-70b-instruct does not.
When both a model and a provider are given, the provider must be the one that model actually runs on — { "model": "gpt-4o", "provider": "anthropic" } is rejected.
Each pair is checked only when it names a model or a provider. A blueprint that names neither is accepted as it stands.
Providers
A provider named on its own, with no model beside it, must be one of these. Anything else —mistral, say — is rejected.
| Provider | Routes to |
|---|---|
openai | GPT models, called directly |
anthropic | Claude models, called directly |
google | Gemini models |
bedrock | Claude and GPT models through AWS Bedrock, ids prefixed bedrock/ |
compass | GPT models through Compass, ids prefixed compass/ |
custom_openai | Custom OpenAI-compatible endpoints. Not offered in the app’s model picker |
custom_anthropic | Custom Anthropic-compatible endpoints. Not offered in the app’s model picker |
Commonly used models
A sample of the current lineup, not the whole of it — the registry moves with the platform, and this page will lag it. The model picker in the Opus app is the live list.model | provider | Shown in the app as |
|---|---|---|
gpt-5.6-terra | openai | GPT 5.6 Terra |
gpt-5.2 | openai | GPT 5.2 |
gpt-4o | openai | GPT 4o |
claude-opus-5 | anthropic | Claude Opus 5 |
claude-sonnet-5 | anthropic | Claude Sonnet 5 |
claude-haiku-4-5-20251001 | anthropic | Claude Haiku 4.5 |
gemini-3.5-flash | google | Gemini 3.5 Flash |
gemini-2.5-pro | google | Gemini 2.5 Pro |
bedrock/claude-opus-5 | bedrock | Claude Opus 5 (Bedrock) |
compass/gpt-5.1 | compass | GPT 5.1 (Compass) |
Models reached through Bedrock or Compass carry the provider in the id itself, and the two halves must agree.
{ "model": "bedrock/claude-sonnet-5", "provider": "bedrock" } is accepted; the same model named bare, as { "model": "claude-sonnet-5", "provider": "bedrock" }, resolves to anthropic and is rejected.Variable object
Each value insideinputs and outputs. The map key must equal the variable’s variableName.
Value types this variable accepts. Between 1 and 11 entries. Each has a
type — one of int, float, bool, str, object, file, array, date, binary, json_string, node — plus optional typeDefinition and typeDefinitionEnforced.Human-readable label rendered in the workflow builder. Maximum 255 characters. When omitted, the agent service applies its own default.
Annotations the builder uses for grouping and filtering, each
{ variableName, value, description }. Maximum 20.Enum-style choice list. When non-empty the builder renders a dropdown. Each entry is free-form JSON. Maximum 20.
Which of
allowedTypes is currently active. Must be one of them — consumers fall back to the first entry when unset.Fields the builder locks, preventing the workflow author from changing them — any of
variable_name, display_name, description, is_nullable, tags, options, allowed_types. Maximum 20.For composite types,
typeDefinition describes the shape inside: a nested variable map for object, a single nested variable for array, or a date format string for date. Omit it for scalars. Set typeDefinitionEnforced to hold the workflow author to it exactly.Categories
One to five of:parsing_and_serialization, validation_and_normalization, transformation_and_mapping, aggregation_and_analysis, numerical_computation, statistical_computation, optimization_and_search, text_processing, document_and_ocr_processing, media_processing, control_flow_and_orchestration, state_and_caching, io_and_storage, networking_and_apis, security_and_identity.
Response
The agent id. Pass it as
{agentId} to Update an Agent.Errors
Invalid body — a missing required field, a value over its limit, more than 5 categories, a
blueprint without a non-empty systemPrompt and userPrompt, a blueprint naming a model or provider the platform cannot route to, or an inputs/outputs entry that is not a valid variable.The API key is not org-scoped, or the key owner lacks the Agent: Full permission in the organization.
Rejected downstream after passing validation here — most often an organization that is not verified to publish to the marketplace.
curl --request POST \
--url https://operator.opus.com/api/v1/agent \
--header 'Content-Type: application/json' \
--header 'x-service-key: {YOUR_SERVICE_KEY}' \
--data '{
"agent": {
"name": "Adder",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return the total.",
"model": "gpt-4o",
"provider": "openai"
},
"inputs": {
"firstNumber": {
"id": "1",
"variableName": "firstNumber",
"displayName": "First Number",
"allowedTypes": [{ "type": "float" }]
},
"secondNumber": {
"id": "2",
"variableName": "secondNumber",
"displayName": "Second Number",
"allowedTypes": [{ "type": "float" }]
}
},
"outputs": {
"sumResult": {
"id": "1",
"variableName": "sumResult",
"displayName": "Sum Result",
"allowedTypes": [{ "type": "float" }]
}
}
}
}'
import requests
url = "https://operator.opus.com/api/v1/agent"
headers = {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}"
}
payload = {
"agent": {
"name": "Adder",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation"],
"blueprint": {
"systemPrompt": "You are a careful arithmetic assistant.",
"userPrompt": "Add {{firstNumber}} and {{secondNumber}} and return the total.",
"model": "gpt-4o",
"provider": "openai",
},
"inputs": {
"firstNumber": {
"id": "1",
"variableName": "firstNumber",
"displayName": "First Number",
"allowedTypes": [{"type": "float"}],
},
"secondNumber": {
"id": "2",
"variableName": "secondNumber",
"displayName": "Second Number",
"allowedTypes": [{"type": "float"}],
},
},
"outputs": {
"sumResult": {
"id": "1",
"variableName": "sumResult",
"displayName": "Sum Result",
"allowedTypes": [{"type": "float"}],
}
},
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
const response = await fetch("https://operator.opus.com/api/v1/agent", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-service-key": "{YOUR_SERVICE_KEY}",
},
body: JSON.stringify({
agent: {
name: "Adder",
description: "Adds two numbers and returns the total",
icon: "{BASE64_ICON}",
categories: ["numerical_computation"],
blueprint: {
systemPrompt: "You are a careful arithmetic assistant.",
userPrompt: "Add {{firstNumber}} and {{secondNumber}} and return the total.",
model: "gpt-4o",
provider: "openai",
},
inputs: {
firstNumber: {
id: "1",
variableName: "firstNumber",
displayName: "First Number",
allowedTypes: [{ type: "float" }],
},
secondNumber: {
id: "2",
variableName: "secondNumber",
displayName: "Second Number",
allowedTypes: [{ type: "float" }],
},
},
outputs: {
sumResult: {
id: "1",
variableName: "sumResult",
displayName: "Sum Result",
allowedTypes: [{ type: "float" }],
},
},
},
}),
});
const data = await response.json();
console.log(data);
{
"id": "{AGENT_ID}",
"name": "Adder",
"description": "Adds two numbers and returns the total",
"icon": "{BASE64_ICON}",
"categories": ["numerical_computation"],
"status": "active",
"isNew": true,
"isPopular": false,
"versionId": "{AGENT_VERSION_ID}",
"groupId": null
}
Was this page helpful?