---
title: "Publish an agent"
method: POST
path: "/v1/workspaces/{workspaceId}/agents/{id}:publish"
tags: ["AgentService", "Agents"]
---

# Publish an agent

`POST /v1/workspaces/{workspaceId}/agents/{id}:publish`

Transitions an agent to STATE_PUBLISHED, making it available for objectives. The agent must have at least one variation.

## Path parameters

- `workspaceId` string, required
- `id` string, required

## Request body

- PublishAgentRequest — Publish agent request
  - `workspaceId` string — Workspace ID.
  - `id` string — Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

## Response `200`

OK

- Agent — Agent resource
  - `metadata` ResourceMetadata, required — Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
    - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")
    - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
    - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID)
    - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
    - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
    - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
    - `profileId` string, required — ID of the actor (user or service account) that created this resource
    - `createdAt` string, date-time, required — Timestamp when this resource was created
    - `updatedAt` string, date-time — Timestamp when this resource was last updated
  - `spec` AgentSpec, required — Agent specification (user-provided configuration)
    - `description` string — Description of the agent's purpose
    - `webhookEventsUrl` string — The URL that Cadenya will send events for any objective assigned to the agent.
    - `variationSelectionMode` 'VARIATION_SELECTION_MODE_UNSPECIFIED' | 'VARIATION_SELECTION_MODE_RANDOM' | 'VARIATION_SELECTION_MODE_WEIGHTED', enum, required — Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
    - `systemPromptDataSchema` object — SystemPromptDataSchema enforces the shape of system_prompt_data when objectives are created. This is valuable when using liquid formatting in agent variation system prompt templates. The schema is also used when the agent is attached as a sub-agent, as it becomes the tool's input parameter schema. If omitted, the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.
    - `outputDefinition` object — Optional output definition for objectives created for this agent. When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here. Use this option when you want structured data to be created by your objectives.
    - `enableEpisodicMemory` boolean — Enable episodic memory for objectives created for this agent. When true, objective creation requires an episodic_memory key and the system finds or creates a memory layer for that (agent, key) pair, letting the agent store and retrieve memories across objectives that share the key. Memory is agent-level so all variations of the agent share the same layers.
    - `episodicMemoryTtl` integer — How long episodic memories should be retained. Each new objective slides the layer's expiry forward by this duration, and stored entries expire this long after they are written. If not set, episodic memories are retained indefinitely.
  - `info` AgentInfo — AgentInfo contains simple information about an agent for display or quick reference
    - `variationCount` integer
    - `createdBy` Profile — A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
      - `metadata` AccountResourceMetadata, required — AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
        - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")
        - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
        - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
        - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
        - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
        - `profileId` string, required
        - `createdAt` string, date-time
      - `spec` ProfileSpec, required — Configuration for a profile.
        - `email` string — Email address of the profile. Required and unique within an account for user profiles.
        - `name` string — Display name (e.g., "Bobby Tables").
        - `type` 'PROFILE_TYPE_UNSPECIFIED' | 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM', enum, required — Whether this profile represents a human user, an API key, or a system principal.
  - `state` 'STATE_UNSPECIFIED' | 'STATE_DRAFT' | 'STATE_PUBLISHED' | 'STATE_ARCHIVED', enum, required — The current lifecycle state of the agent. Output only. Agents are created in STATE_DRAFT; use the :publish, :unpublish, :archive, and :unarchive actions to transition between states.

## Other responses

- `default` — Default error response

---

[API](https://skmtc.net/cadenya/apis/cadenya-api.md) · [All operations](https://skmtc.net/cadenya/apis/cadenya-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cadenya/cadenya-api/versions/ac1a7f084068/schema)