Skip to content
cadenya
Get started
API Reference
Overview

API Reference

Libraries

TypeScript
0.82.0
npm install @cadenya/cadenya
Read Docs
Go
0.24.0
go get -u 'github.com/cadenya/cadenya-go@v0.24.0'
Read Docs
Ruby
0.2.0
gem "cadenya"
Read Docs
CLI tool
0.18.0
brew install cadenya/tools/cadenya
Read Docs

API Overview

Account

Manage the authenticated account. Accounts are the top-level organizational unit and contain one or more workspaces.

Retrieves the current account for the token accessing the API
GET/v1/account
Rotates the webhook signing key for the account
POST/v1/account/rotate_webhook_signing_key

Agents

Manage AI agents within a workspace. Agents define AI behavior and tool access.

List agents
GET/v1/workspaces/{workspaceId}/agents
Create a new agent
POST/v1/workspaces/{workspaceId}/agents
Get an agent by ID
GET/v1/workspaces/{workspaceId}/agents/{id}
Delete an agent
DELETE/v1/workspaces/{workspaceId}/agents/{id}
Update an agent
PATCH/v1/workspaces/{workspaceId}/agents/{id}

AgentsFeedback

Manage AI agents within a workspace. Agents define AI behavior and tool access.

List feedback for an agent
GET/v1/workspaces/{workspaceId}/agents/{agentId}/feedback

AgentsWebhook Deliveries

Manage AI agents within a workspace. Agents define AI behavior and tool access.

List webhook deliveries
GET/v1/workspaces/{workspaceId}/agents/{agentId}/webhook_deliveries

AgentsVariations

Manage variations of an agent and their tool, sub-agent, and memory layer assignments.

List variations
GET/v1/workspaces/{workspaceId}/agents/{agentId}/variations
Create a new variation
POST/v1/workspaces/{workspaceId}/agents/{agentId}/variations
Get a variation by ID
GET/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}
Delete a variation
DELETE/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}
Update a variation
PATCH/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}
Add an assignment to a variation
POST/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/assignments
Remove an assignment from a variation
DELETE/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/assignments/{id}
Attach a memory layer to a variation
POST/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments
Update a variation's memory layer assignment
PATCH/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments/{id}
Remove a memory layer assignment from a variation
DELETE/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments/{id}

AgentsSchedules

Manage recurring schedules attached to agents. Schedules trigger objectives on a cadence defined by AgentScheduleSpec.Schedule.

List schedules
GET/v1/workspaces/{workspaceId}/agents/{agentId}/schedules
Create a new schedule
POST/v1/workspaces/{workspaceId}/agents/{agentId}/schedules
Get a schedule by ID
GET/v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}
Delete a schedule
DELETE/v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}
Update a schedule
PATCH/v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}

Objectives

List objectives
GET/v1/workspaces/{workspaceId}/objectives
Create a new objective
POST/v1/workspaces/{workspaceId}/objectives
Get an objective by ID
GET/v1/workspaces/{workspaceId}/objectives/{id}
List objective events
GET/v1/workspaces/{workspaceId}/objectives/{objectiveId}/events
Continue an objective
POST/v1/workspaces/{workspaceId}/objectives/{objectiveId}/continue
Cancel an objective
POST/v1/workspaces/{workspaceId}/objectives/{objectiveId}/cancel
Compact an objective
POST/v1/workspaces/{workspaceId}/objectives/{objectiveId}/compact
List objective context windows
GET/v1/workspaces/{workspaceId}/objectives/{objectiveId}/context_windows

ObjectivesTools

List objective tools
GET/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tools

ObjectivesTool Calls

List objective tool calls
GET/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls
Approve a tool call
PUT/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls/{toolCallId}/approve
Deny a tool call
PUT/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls/{toolCallId}/deny

ObjectivesTasks

List objective tasks
GET/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tasks
Get an objective task by ID
GET/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tasks/{id}

ObjectivesFeedback

Submit feedback for an objective
POST/v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback
List feedback for an objective
GET/v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback

Memory Layers

Manage memory layers and their entries. Layers are named containers that can be composed into an objective’s memory stack; entries are the keyed values within a layer. System-managed layers (e.g., episodic layers created by the runtime) cannot be mutated through this API.

List memory layers
GET/v1/workspaces/{workspaceId}/memory_layers
Create a new memory layer
POST/v1/workspaces/{workspaceId}/memory_layers
Get a memory layer by ID
GET/v1/workspaces/{workspaceId}/memory_layers/{id}
Update a memory layer
PATCH/v1/workspaces/{workspaceId}/memory_layers/{id}
Delete a memory layer
DELETE/v1/workspaces/{workspaceId}/memory_layers/{id}

Memory LayersEntries

Manage memory layers and their entries. Layers are named containers that can be composed into an objective’s memory stack; entries are the keyed values within a layer. System-managed layers (e.g., episodic layers created by the runtime) cannot be mutated through this API.

List memory entries
GET/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries
Create a new memory entry
POST/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries
Get a memory entry by ID
GET/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries/{id}
Update a memory entry
PATCH/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries/{id}
Delete a memory entry
DELETE/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries/{id}

Uploads

Issue short-lived presigned URLs for direct client-to-object-storage uploads. Created uploads can be referenced by id when creating or updating resources that accept binary content (e.g., MemoryEntry).

Create an upload
POST/v1/workspaces/{workspaceId}/uploads
Get an upload by ID
GET/v1/workspaces/{workspaceId}/uploads/{id}

Models

Manage LLM models available to a workspace. Models represent provider and family pairs (e.g., “anthropic/claude-sonnet-4.6”). Workspaces are seeded with the supported models and you can enable or disable each one.

List models
GET/v1/workspaces/{workspaceId}/models
Get a model by ID
GET/v1/workspaces/{workspaceId}/models/{id}
Set model status
PUT/v1/workspaces/{workspaceId}/models/{id}/status
Search for tools or tool sets
GET/v1/workspaces/{workspaceId}/search/tools_or_tool_sets

Tool Sets

Manage tool sets and the tools they contain. Tool sets group related tools, and tools define specific capabilities available to agents.

When a tool set is managed, only API key actors can modify its tools; human (profile) actors cannot.

List tool sets
GET/v1/workspaces/{workspaceId}/tool_sets
Create a new tool set
POST/v1/workspaces/{workspaceId}/tool_sets
Get a tool set by ID
GET/v1/workspaces/{workspaceId}/tool_sets/{id}
Update a tool set
PUT/v1/workspaces/{workspaceId}/tool_sets/{id}
Delete a tool set
DELETE/v1/workspaces/{workspaceId}/tool_sets/{id}
Get consumed OpenAPI spec
GET/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/openapi_spec
List tool set events
GET/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/events

Tool SetsTools

Manage tool sets and the tools they contain. Tool sets group related tools, and tools define specific capabilities available to agents.

When a tool set is managed, only API key actors can modify its tools; human (profile) actors cannot.

List tools
GET/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/tools
Create a new tool
POST/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/tools
Get a tool by ID
GET/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/tools/{id}
Update a tool
PUT/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/tools/{id}
Delete a tool
DELETE/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/tools/{id}

API Keys

Issue, rotate, and revoke API keys for the account, and grant or revoke each key’s access to individual workspaces.

List API keys
GET/v1/account/api_keys
Create a new API key
POST/v1/account/api_keys
Get an API key by ID
GET/v1/account/api_keys/{id}
Delete an API key
DELETE/v1/account/api_keys/{id}
Update an API key
PATCH/v1/account/api_keys/{id}
Rotate an API key
PUT/v1/account/api_keys/{id}/rotate

API KeysAccess

Issue, rotate, and revoke API keys for the account, and grant or revoke each key’s access to individual workspaces.

Grant an API key access to a workspace
POST/v1/account/api_keys/{id}/workspaces
Revoke an API key's access to a workspace
DELETE/v1/account/api_keys/{id}/workspaces/{workspaceId}
List the workspaces an API key has access to
GET/v1/account/api_keys/{id}/workspaces

Workspace Secrets

List workspace secrets
GET/v1/workspaces/{workspaceId}/workspace_secrets
Create a new workspace secret
POST/v1/workspaces/{workspaceId}/workspace_secrets
Get a workspace secret by ID
GET/v1/workspaces/{workspaceId}/workspace_secrets/{id}
Delete a workspace secret
DELETE/v1/workspaces/{workspaceId}/workspace_secrets/{id}
Update a workspace secret
PATCH/v1/workspaces/{workspaceId}/workspace_secrets/{id}

Workspaces

Manage workspaces within an account. Workspaces provide organizational grouping and isolation for resources such as agents, tools, and API keys.

This is the workspace-scoped, end-user surface. Administrative operations (create / archive workspaces, manage members) live in WorkspaceAdminService under /v1/account/workspaces and require the admin role.

List workspaces
GET/v1/workspaces
Get the current workspace
GET/v1/workspaces/current

Workspace Admin

Administer workspaces across the account: create and archive workspaces and manage their membership. These operations are account-scoped and require the admin role (a token whose profile holds the WorkOS admin role); they live under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces tree so an admin can manage any workspace in the account, including ones they are not themselves a member of.

List all workspaces in the account
GET/v1/account/workspaces
Create a workspace
POST/v1/account/workspaces
Get a workspace by ID
GET/v1/account/workspaces/{workspaceId}
Update a workspace
PATCH/v1/account/workspaces/{workspaceId}
Archive a workspace
DELETE/v1/account/workspaces/{workspaceId}

Workspace AdminMembers

Administer workspaces across the account: create and archive workspaces and manage their membership. These operations are account-scoped and require the admin role (a token whose profile holds the WorkOS admin role); they live under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces tree so an admin can manage any workspace in the account, including ones they are not themselves a member of.

List workspace members
GET/v1/account/workspaces/{workspaceId}/members
Add a member to a workspace
POST/v1/account/workspaces/{workspaceId}/members
Remove a member from a workspace
DELETE/v1/account/workspaces/{workspaceId}/members/{profileId}

Workspace AdminProfiles

Administer workspaces across the account: create and archive workspaces and manage their membership. These operations are account-scoped and require the admin role (a token whose profile holds the WorkOS admin role); they live under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces tree so an admin can manage any workspace in the account, including ones they are not themselves a member of.

Search account profiles
GET/v1/account/profiles

Webhooks

Unwrap
Function
Unsafe Unwrap
Function

Bulk Workspace Resources

Apply a declarative bundle of workspace resources — tool sets, memory layers, agents, variations, assignments, and schedules — in a single asynchronous operation.

Apply a workspace resource bundle
POST/v1/workspaces/{workspaceId}/bulk_workspace_applies
Get a bulk workspace apply operation
GET/v1/workspaces/{workspaceId}/bulk_workspace_applies/{id}
List bulk workspace apply operations
GET/v1/workspaces/{workspaceId}/bulk_workspace_applies

Bulk Workspace ResourcesResults

Apply a declarative bundle of workspace resources — tool sets, memory layers, agents, variations, assignments, and schedules — in a single asynchronous operation.

List per-resource results for a bulk workspace apply
GET/v1/workspaces/{workspaceId}/bulk_workspace_applies/{bulkWorkspaceApplyId}/results