Skip to content

Organization Templates

Use an Organization API Key to manage shared Templates and select one when creating a Session for an End User.

Manage Templates through the Organization API

Section titled “Manage Templates through the Organization API”
Method and path Purpose
GET /api/v1/org/agent-template-reference-catalog Discover model, Sandbox and published Skill choices and availability.
GET /api/v1/org/agent-templates List Templates with filtering, sorting and cursor pagination.
POST /api/v1/org/agent-templates Atomically create a Template with its complete starting content.
GET /api/v1/org/agent-templates/{templateId} Read the Template and its current public configuration.
PUT /api/v1/org/agent-templates/{templateId} Replace the complete public configuration in place.
POST /api/v1/org/agent-templates/{templateId}/archive Archive the Template.

Create and replace bodies contain displayName and content. Content follows the complete public Template schema in the API reference. The catalog helps you choose usable references. Optional standingTask: {"goal": "..."} keeps a Full Agent task running on voice conversations; see Standing Task. Because PUT replaces the complete configuration, a replacement that omits standingTask removes it. GET returns the template summary and its current content; every summary carries the Template etag and current contentDigest.

Use content.tools.mcp to attach available Organization-shared MCP Server Registrations and Connectors. Each entry is {"serverId": "<registration-id>"}. An MCP Server Registration entry may add "toolNames": ["<remote-tool-name>", ...] to offer the model only those of the registration’s tools; without it the model is offered every tool. Names the registration’s catalog does not contain are ignored. Changing the list changes the Template’s contentDigest, and an existing Session keeps the list it started with until a Template switch. Connector entries do not accept toolNames. A create that omits tools starts with no references. A replacement that omits tools keeps the current references. Supply the full list to replace them or "tools": {"mcp": []} to clear them. Current Template content includes the references. A retry of a previously committed command returns its original body, which can omit tools.

Each MCP Server Registration a Template references is required by every new Turn. A Turn whose registration’s MCP Authorization is not usable is refused before it starts with 409 mcp_authorization_required, and details.registrations names each such registration with its serverId, owner and reason (missing, invalid, revoked or insufficient_scope). In an End User mode, that is the authorization of the End User who owns the Session. If the authorization stops working during a Turn, because it was revoked or the server answered a call with HTTP 401 or 403, the Turn fails with the same code and details as its failure, in agent.session.turn.failed and the Turn’s failure, instead of continuing without the server. A disabled or deleted registration refuses the Turn with 409 session_execution_dependency_unavailable. Fix the authorization, for example by setting its token again or authorizing again with OAuth, then start a new Turn; the earlier conversation is kept. To ask an End User to authorize before a Turn is refused, read their authorization requirements.

A create or replacement takes effect immediately. Each Session Configuration Epoch retains the content and digest current at admission. PUT requires the Template’s quoted If-Match ETag. Console editing and API writes share the same Template and ETag. Read the current Template before preparing a new edit after a stale ETag.

Pass agentTemplateId when you create a Session. The creation request can include supplementary instructions, a Sandbox Profile and a working directory for that Session. Each admitted Configuration Epoch retains the Template content and digest selected at admission. To change behavior within the same Session, request a Template switch explicitly. Archiving a Template prevents new selection and preserves existing Configuration Epochs.