Skip to content
cadenya
Get started
API Reference

Agents

AgentService manages AI agents at the WORKSPACE level. Agents are workspace-scoped resources that define AI behavior and tool access. All operations are implicitly scoped to the workspace determined by the JWT token.

Authentication: Bearer token (JWT) Scope: Workspace-level operations

List agents
client.agents.list(AgentListParams { cursor, includeInfo, limit, 2 more } query?, RequestOptionsoptions?): CursorPagination<Agent { metadata, spec, info } >
GET/v1/agents
Create a new agent
client.agents.create(AgentCreateParams { metadata, spec, defaultVariation } body, RequestOptionsoptions?): Agent { metadata, spec, info }
POST/v1/agents
Get an agent by ID
client.agents.retrieve(stringid, RequestOptionsoptions?): Agent { metadata, spec, info }
GET/v1/agents/{id}
Delete an agent
client.agents.delete(stringid, RequestOptionsoptions?): void
DELETE/v1/agents/{id}
Update an agent
client.agents.update(stringid, AgentUpdateParams { metadata, spec, updateMask } body, RequestOptionsoptions?): Agent { metadata, spec, info }
PATCH/v1/agents/{id}
ModelsExpand Collapse
Agent { metadata, spec, info }

Agent resource

metadata: ResourceMetadata { id, accountId, createdAt, 5 more }

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

id: string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

createdAt: string

Timestamp when this resource was created

formatdate-time
name: string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

profileId: string

ID of the actor (user or service account) that created this resource

workspaceId: string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

externalId?: string

External ID for the resource (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

spec: AgentSpec { status, variationSelectionMode, description, webhookEventsUrl }

Agent specification (user-provided configuration)

status: "AGENT_STATUS_UNSPECIFIED" | "AGENT_STATUS_DRAFT" | "AGENT_STATUS_PUBLISHED" | "AGENT_STATUS_ARCHIVED"

Status of the agent

formatenum
One of the following:
"AGENT_STATUS_UNSPECIFIED"
"AGENT_STATUS_DRAFT"
"AGENT_STATUS_PUBLISHED"
"AGENT_STATUS_ARCHIVED"
variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" | "VARIATION_SELECTION_MODE_RANDOM" | "VARIATION_SELECTION_MODE_WEIGHTED"

Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified

formatenum
One of the following:
"VARIATION_SELECTION_MODE_UNSPECIFIED"
"VARIATION_SELECTION_MODE_RANDOM"
"VARIATION_SELECTION_MODE_WEIGHTED"
description?: string

Description of the agent's purpose

webhookEventsUrl?: string

The URL that Cadenya will send events for any objective assigned to the agent.

info?: AgentInfo { createdBy, variationCount }

AgentInfo contains simple information about an agent for display or quick reference

createdBy?: Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

metadata: AccountResourceMetadata { id, accountId, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: string

Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

name: string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

profileId: string
externalId?: string

External ID for the resource (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

spec: ProfileSpec { type, email, name }

ProfileSpec contains the profile-specific fields

type: "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum
One of the following:
"PROFILE_TYPE_USER"
"PROFILE_TYPE_API_KEY"
"PROFILE_TYPE_SYSTEM"
email?: string

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

variationCount?: number
AgentInfo { createdBy, variationCount }

AgentInfo contains simple information about an agent for display or quick reference

createdBy?: Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

metadata: AccountResourceMetadata { id, accountId, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: string

Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

name: string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

profileId: string
externalId?: string

External ID for the resource (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

spec: ProfileSpec { type, email, name }

ProfileSpec contains the profile-specific fields

type: "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum
One of the following:
"PROFILE_TYPE_USER"
"PROFILE_TYPE_API_KEY"
"PROFILE_TYPE_SYSTEM"
email?: string

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

variationCount?: number
AgentSpec { status, variationSelectionMode, description, webhookEventsUrl }

Agent specification (user-provided configuration)

status: "AGENT_STATUS_UNSPECIFIED" | "AGENT_STATUS_DRAFT" | "AGENT_STATUS_PUBLISHED" | "AGENT_STATUS_ARCHIVED"

Status of the agent

formatenum
One of the following:
"AGENT_STATUS_UNSPECIFIED"
"AGENT_STATUS_DRAFT"
"AGENT_STATUS_PUBLISHED"
"AGENT_STATUS_ARCHIVED"
variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" | "VARIATION_SELECTION_MODE_RANDOM" | "VARIATION_SELECTION_MODE_WEIGHTED"

Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified

formatenum
One of the following:
"VARIATION_SELECTION_MODE_UNSPECIFIED"
"VARIATION_SELECTION_MODE_RANDOM"
"VARIATION_SELECTION_MODE_WEIGHTED"
description?: string

Description of the agent's purpose

webhookEventsUrl?: string

The URL that Cadenya will send events for any objective assigned to the agent.

Page { nextCursor, total }
nextCursor?: string
total?: number

AgentsWebhook Deliveries

AgentService manages AI agents at the WORKSPACE level. Agents are workspace-scoped resources that define AI behavior and tool access. All operations are implicitly scoped to the workspace determined by the JWT token.

Authentication: Bearer token (JWT) Scope: Workspace-level operations

List webhook deliveries
client.agents.webhookDeliveries.list(stringagentID, WebhookDeliveryListParams { cursor, eventType, limit, objectiveId } query?, RequestOptionsoptions?): CursorPagination<WebhookDelivery { data, metadata } >
GET/v1/agents/{agentId}/webhook_deliveries
ModelsExpand Collapse
WebhookDelivery { data, metadata }
data: WebhookDeliveryData { agentId, attemptCount, eventType, 11 more }

Webhook delivery data

agentId: string

Related resources

attemptCount: number
eventType: "OBJECTIVE_EVENT_TYPE_UNSPECIFIED" | "OBJECTIVE_EVENT_TYPE_USER_MESSAGE" | "OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED" | 9 more

The type of objective event that triggered this webhook delivery

formatenum
One of the following:
"OBJECTIVE_EVENT_TYPE_UNSPECIFIED"
"OBJECTIVE_EVENT_TYPE_USER_MESSAGE"
"OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED"
"OBJECTIVE_EVENT_TYPE_TOOL_APPROVED"
"OBJECTIVE_EVENT_TYPE_TOOL_DENIED"
"OBJECTIVE_EVENT_TYPE_TOOL_CALLED"
"OBJECTIVE_EVENT_TYPE_SUB_OBJECTIVE_CREATED"
"OBJECTIVE_EVENT_TYPE_ERROR"
"OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE"
"OBJECTIVE_EVENT_TYPE_TOOL_RESULT"
"OBJECTIVE_EVENT_TYPE_TOOL_ERROR"
"OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED"
httpStatusCode: number

Response details (no response_body to avoid storing large payloads)

formatint32
lastAttemptAt: string
latencyMs: number
objectiveEventId: string
objectiveId: string
responseContentLength: string

Content length of the response body in bytes

status: "WEBHOOK_DELIVERY_STATUS_UNSPECIFIED" | "WEBHOOK_DELIVERY_STATUS_PENDING" | "WEBHOOK_DELIVERY_STATUS_COMPLETED" | 2 more
formatenum
One of the following:
"WEBHOOK_DELIVERY_STATUS_UNSPECIFIED"
"WEBHOOK_DELIVERY_STATUS_PENDING"
"WEBHOOK_DELIVERY_STATUS_COMPLETED"
"WEBHOOK_DELIVERY_STATUS_FAILED"
"WEBHOOK_DELIVERY_STATUS_DISABLED"
webhookId: string
webhookUrl: string

Webhook delivery details

errorMessage?: string
responseHeaders?: Record<string, string>

Response headers received from the webhook endpoint

metadata: OperationMetadata { id, accountId, createdAt, 4 more }

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

id: string

Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

accountId: string

Account this operation belongs to for multi-tenant isolation (prefixed ULID)

createdAt: string

Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying

formatdate-time
profileId: string

ID of the actor (user or service account) that created this operation

workspaceId: string

Workspace this operation belongs to for organizational grouping (prefixed ULID)

externalId?: string

External ID for the operation (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

WebhookDeliveryData { agentId, attemptCount, eventType, 11 more }
agentId: string

Related resources

attemptCount: number
eventType: "OBJECTIVE_EVENT_TYPE_UNSPECIFIED" | "OBJECTIVE_EVENT_TYPE_USER_MESSAGE" | "OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED" | 9 more

The type of objective event that triggered this webhook delivery

formatenum
One of the following:
"OBJECTIVE_EVENT_TYPE_UNSPECIFIED"
"OBJECTIVE_EVENT_TYPE_USER_MESSAGE"
"OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED"
"OBJECTIVE_EVENT_TYPE_TOOL_APPROVED"
"OBJECTIVE_EVENT_TYPE_TOOL_DENIED"
"OBJECTIVE_EVENT_TYPE_TOOL_CALLED"
"OBJECTIVE_EVENT_TYPE_SUB_OBJECTIVE_CREATED"
"OBJECTIVE_EVENT_TYPE_ERROR"
"OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE"
"OBJECTIVE_EVENT_TYPE_TOOL_RESULT"
"OBJECTIVE_EVENT_TYPE_TOOL_ERROR"
"OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED"
httpStatusCode: number

Response details (no response_body to avoid storing large payloads)

formatint32
lastAttemptAt: string
latencyMs: number
objectiveEventId: string
objectiveId: string
responseContentLength: string

Content length of the response body in bytes

status: "WEBHOOK_DELIVERY_STATUS_UNSPECIFIED" | "WEBHOOK_DELIVERY_STATUS_PENDING" | "WEBHOOK_DELIVERY_STATUS_COMPLETED" | 2 more
formatenum
One of the following:
"WEBHOOK_DELIVERY_STATUS_UNSPECIFIED"
"WEBHOOK_DELIVERY_STATUS_PENDING"
"WEBHOOK_DELIVERY_STATUS_COMPLETED"
"WEBHOOK_DELIVERY_STATUS_FAILED"
"WEBHOOK_DELIVERY_STATUS_DISABLED"
webhookId: string
webhookUrl: string

Webhook delivery details

errorMessage?: string
responseHeaders?: Record<string, string>

Response headers received from the webhook endpoint