Skip to main content
POST
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

​
string
required
Your API authentication key

​
Body Parameters

The agent is nested under an agent key.
​
object
required
The agent to create. Fields below.
​
string
required
Agent display name. Maximum 255 characters.
​
string
required
Agent icon as a base64-encoded SVG (or PNG) — a plain string, with no data: prefix. Maximum 65535 characters.
​
object
required
The agent implementation: the prompts the agent runs with, plus the model that runs them. See Blueprint. Maximum 256KB JSON-encoded.
​
string[]
required
Categories the agent is filed under in the marketplace. Maximum 5 entries. See Categories.
​
string
What the agent does, shown under its name. Maximum 2048 characters.
​
object
The agent’s input schema, keyed by each variable’s variableName. Maximum 100 entries and 512KB JSON-encoded. See Variable object.
​
object
The agent’s output schema, keyed by each variable’s variableName. Same shape and limits as inputs.
​
string
default:"active"
Agent status — active, inactive, soon or deprecated.
​
boolean
default:"true"
Show the “new” badge on the agent tile.
​
boolean
default:"false"
Show the “popular” badge on the agent tile.
​
boolean
default:"false"
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.
​
string
required
System prompt the agent runs with. Must be non-empty.
​
string
required
User prompt template. Must be non-empty. Reference the agent’s inputs with {{variableName}}.
​
string
Model the agent runs on, for example gpt-4o. Must be one the platform routes to — see Models and providers.
​
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.
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.

​
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.
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 inside inputs and outputs. The map key must equal the variable’s variableName.
​
string
required
Stable identifier for the variable, unique within the schema. Maximum 255 characters.
​
string
required
Programmatic key. Must equal the key this entry sits under. Maximum 255 characters.
​
object[]
required
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.
​
string
Human-readable label rendered in the workflow builder. Maximum 255 characters. When omitted, the agent service applies its own default.
​
string
Description shown next to the variable in the builder. Maximum 2048 characters.
​
any
default:"null"
Pre-filled default value. Its type must match one of allowedTypes.
​
boolean
default:"false"
When true, the workflow may leave this variable unset.
​
object[]
Annotations the builder uses for grouping and filtering, each { variableName, value, description }. Maximum 20.
​
any[]
Enum-style choice list. When non-empty the builder renders a dropdown. Each entry is free-form JSON. Maximum 20.
​
string
Which of allowedTypes is currently active. Must be one of them — consumers fall back to the first entry when unset.
​
string[]
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.
​
boolean
default:"true"
When false, the builder hides the “remove variable” affordance.
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

​
string
required
The agent id. Pass it as {agentId} to Update an Agent.
​
string
required
Agent display name.
​
string
Agent description.
​
string
Agent icon.
​
string[]
Categories the agent is filed under.
​
string
Agent status.
​
boolean
Whether the “new” badge is shown.
​
boolean
Whether the “popular” badge is shown.
​
string
Id of the version this call created.
​
string
Owning workspace, or null when the agent is visible across the marketplace.

​
Errors

​
Bad Request
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.
​
Unauthorized
Missing, invalid, or expired API key.
​
Forbidden
The API key is not org-scoped, or the key owner lacks the Agent: Full permission in the organization.
​
Unprocessable Entity
Rejected downstream after passing validation here — most often an organization that is not verified to publish to the marketplace.