Skip to main content

​
Overview

The Agents API lets you register your own agents in the Opus marketplace programmatically — the agent itself, the prompts it runs, and the typed inputs and outputs it exposes to a workflow. These endpoints author the agent catalog: the definition of an agent, shared across your whole organization. Connecting an agent into a workspace so a workflow can run it is a separate, workspace-scoped step done in the Opus app.

​
Base URL

All API requests should be made to the following base URL:

​
Authentication

All API endpoints require authentication with your Opus API key, sent in the x-service-key header.
Your key determines your identity and your organization. Every endpoint here requires the Agent: Full permission at organization level — a workspace-level grant is not sufficient, because an agent authored here belongs to the organization rather than to a workspace. A request with a missing, invalid, or expired key returns 401. A key that is not org-scoped, or whose owner lacks Agent: Full in the organization, returns 403.
Your API key is a unique, secret credential. Store it securely and never expose it in client-side code.
Your organization must be verified to publish to the marketplace. An unverified organization passes validation here and is rejected downstream with 422.

​
Authoring Flow

Authoring an agent takes a single call. Unlike the Integrations API, there is no provider to create first — your organization’s agent provider is created on demand on your first agent.
1

Create the Agent

POST / registers the agent under your organization with its prompts and IO schema. Keep the returned id.
2

Revise It

PATCH /{agentId} updates any subset of fields. Each call cuts a new agent version, so the previous state stays addressable.
There is no providerId field anywhere in this section. The organization comes from your API key and the agent service resolves that organization’s canonical provider itself — accepting one from the caller would allow authoring into another organization’s provider.

​
Agent Classes

An agent is driven either by raw prompts or by a blueprint of ordered steps. This API authors Custom Agents only — blueprint carries a systemPrompt and a userPrompt, and the class is pinned for you. There is no agentClass field to set. Opus Agents — the kind authored inside the Opus app, from an objective, input/process/output descriptions and ordered steps — cannot be created here. They can still be revised through Update an Agent, which accepts either shape. An agent’s class is fixed when it is created and cannot be changed afterwards — a blueprint in the wrong shape would leave the agent unable to run. blueprint is otherwise forwarded to the agent service untouched and stored verbatim, so nothing in it beyond the prompts and the model it names is validated structurally. The documented fields are a base, not a ceiling: extra fields are kept and forwarded.

​
Inputs and Outputs

inputs and outputs describe the agent’s signature to the workflow builder. Both are maps keyed by the variable’s own variableName:
The key and the variableName inside it must match. Each variable needs at least one entry in allowedTypes; for composite types, allowedTypes[].typeDefinition describes the shape inside.

​
Usage Notes

  • Nothing is workspace-scoped. An agent authored here belongs to your organization. No workspace id is accepted anywhere in this section.
  • An agent is not runnable on create. It is a catalog entry until it is connected into a workspace.
  • Create authors Custom Agents only. A blueprint without a non-empty systemPrompt and userPrompt is rejected with 400. Either casing is accepted.
  • Models are checked before the agent is stored. Both endpoints reject a blueprint naming a model the platform cannot route to, or a provider that contradicts the model beside it. See Models and providers.
  • Update replaces, it does not merge. blueprint, inputs and outputs are swapped wholesale by PATCH. Send the complete object you want stored.
  • 400 is us, 422 is downstream. A 400 means this API rejected your body. A 422 means it passed validation here and was rejected further down — most often an organization not verified to publish to the marketplace.

​
Limits

​
Available Endpoints

Create an Agent

Register an agent with its class, blueprint, and IO schema

Update an Agent

Revise an agent your organization owns, cutting a new version