> ## Documentation Index > Fetch the complete documentation index at: https://developer.opus.com/llms.txt > Use this file to discover all available pages before exploring further. # Introduction > Author agents for your organization entirely through the API ## 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: ``` https://operator.opus.com/api/v1/agent ``` ## Authentication All API endpoints require authentication with your Opus API key, sent in the `x-service-key` header. ```text theme={null} x-service-key: ``` 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](/api-reference/v1-integration/integration-introduction), there is no provider to create first — your organization's agent provider is created on demand on your first agent. `POST /` registers the agent under your organization with its prompts and IO schema. Keep the returned `id`. `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](/tasks/agent/custom-agent) only** — `blueprint` carries a `systemPrompt` and a `userPrompt`, and the class is pinned for you. There is no `agentClass` field to set. [Opus Agents](/tasks/agent/opus-agent) — 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](/api-reference/v1-agent/update-agent), which accepts either shape. | | Create | Update | | - | - | - | | Custom Agent | Yes | Yes | | Opus Agent | No | Yes | 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`: ```json theme={null} { "firstNumber": { "id": "1", "variableName": "firstNumber", "displayName": "First Number", "allowedTypes": [{ "type": "float" }] } } ``` 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](/api-reference/v1-agent/create-agent#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 | Field | Limit | | - | - | | `name` | 255 characters | | `description` | 2,048 characters | | `icon` | 65,535 characters | | `categories` | 5 entries | | `blueprint` | 256KB JSON-encoded | | `inputs` / `outputs` | 100 variables, 512KB JSON-encoded | | `allowedTypes` | 1–11 entries per variable | | `tags` / `options` / `nonEditableFields` | 20 entries each | ## Available Endpoints Register an agent with its class, blueprint, and IO schema Revise an agent your organization owns, cutting a new version This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.