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
Get a bulk workspace apply operation
List bulk workspace apply operations
ModelsExpand Collapse
type AgentEntry struct{…}
Spec AgentSpec
Agent specification (user-provided configuration)
VariationSelectionMode AgentSpecVariationSelectionMode
Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
InputDataSchema map[string, unknown]Optional
InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as 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 map[string, unknown]Optional
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.
Schedules under this agent, keyed by external_id.
Spec AgentScheduleSpec
AgentScheduleSpec is the user-provided configuration for a schedule.
InitialMessage string
The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.
Schedule AgentScheduleSpecSchedule
Data unknownOptional
Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.
OverlapPolicy AgentScheduleSpecOverlapPolicyOptional
What to do when the previous run is still in flight. Defaults to SKIP.
Status AgentScheduleSpecStatusOptional
Lifecycle. Defaults to ACTIVE on create when unspecified.
Variations under this agent, keyed by external_id.
Spec AgentVariationSpec
AgentVariationSpec defines the operational configuration for a variation
Description stringOptional
Human-readable description of what this variation does or when it should be used
EnableEpisodicMemory boolOptional
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
EpisodicMemoryTtl int64Optional
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
RerankThreshold float64Optional
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
type AgentScheduleEntry struct{…}
Spec AgentScheduleSpec
AgentScheduleSpec is the user-provided configuration for a schedule.
InitialMessage string
The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.
Schedule AgentScheduleSpecSchedule
Data unknownOptional
Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.
OverlapPolicy AgentScheduleSpecOverlapPolicyOptional
What to do when the previous run is still in flight. Defaults to SKIP.
Status AgentScheduleSpecStatusOptional
Lifecycle. Defaults to ACTIVE on create when unspecified.
type AgentVariationEntry struct{…}
Spec AgentVariationSpec
AgentVariationSpec defines the operational configuration for a variation
Description stringOptional
Human-readable description of what this variation does or when it should be used
EnableEpisodicMemory boolOptional
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
EpisodicMemoryTtl int64Optional
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
RerankThreshold float64Optional
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
type BulkWorkspaceApply struct{…}
The operation resource produced by a call to
BulkWorkspaceResources.Apply. It carries the input bundle in data,
the lifecycle state in status, and aggregate counts in info.
BundleKey string
Required. Bundle ownership key. Resources created or updated by an
Apply have their metadata.bundle_key set to this value. On
subsequent applies with the same bundle_key, resources currently
bearing this bundle_key but absent from the spec are soft-deleted.
Agents to upsert, keyed by external_id.
Spec AgentSpec
Agent specification (user-provided configuration)
VariationSelectionMode AgentSpecVariationSelectionMode
Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
InputDataSchema map[string, unknown]Optional
InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as 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 map[string, unknown]Optional
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.
Schedules under this agent, keyed by external_id.
Spec AgentScheduleSpec
AgentScheduleSpec is the user-provided configuration for a schedule.
InitialMessage string
The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.
Schedule AgentScheduleSpecSchedule
Data unknownOptional
Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.
OverlapPolicy AgentScheduleSpecOverlapPolicyOptional
What to do when the previous run is still in flight. Defaults to SKIP.
Status AgentScheduleSpecStatusOptional
Lifecycle. Defaults to ACTIVE on create when unspecified.
Variations under this agent, keyed by external_id.
Spec AgentVariationSpec
AgentVariationSpec defines the operational configuration for a variation
Description stringOptional
Human-readable description of what this variation does or when it should be used
EnableEpisodicMemory boolOptional
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
EpisodicMemoryTtl int64Optional
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
RerankThreshold float64Optional
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
AutomaticallyPublishAgents boolOptional
When true, every agent created or updated by this Apply has its status forced to AGENT_STATUS_PUBLISHED, regardless of the status declared in the agent’s AgentSpec. Useful when the bundle represents a production configuration and you want all of its agents live without setting status: AGENT_STATUS_PUBLISHED on each entry.
Default false: each agent’s AgentSpec.status controls (which is AGENT_STATUS_DRAFT on create when unspecified).
Memory layers to upsert, keyed by external_id.
Spec MemoryLayerSpec
Description stringOptional
Human-readable description of the layer’s purpose. Encouraged for user-created layers; system-managed layers may have a generated description.
ExpiresAt TimeOptional
For layers with a finite lifetime (e.g., episodic), the time at which the layer becomes eligible for cleanup. Set by the system; unset for persistent layers.
SystemManaged boolOptional
Server-set. True for layers managed by the system (e.g., episodic layers created automatically when an objective uses an episodic_key). System-managed layers cannot be assigned to objective stacks via the API and cannot be mutated by clients — their lifecycle is controlled entirely by the runtime.
SourceURL stringOptional
Optional URL pointing to the source of this apply (GitHub PR, Jenkins build, GitLab pipeline, etc.). Surfaced in the dashboard so users can jump from an apply back to the change that produced it. Free-form HTTPS URI; not interpreted by the server.
Tool sets to upsert, keyed by external_id.
Spec ToolSetSpec
Approval filters that will automatically set the approval requirement on tools synced from an external source
BaseURL stringOptional
Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.
Headers map[string, string]Optional
Headers sent when fetching the spec from a URL and when dispatching tool calls.
ServerName stringOptional
Name of the server entry in the spec’s servers array (OpenAPI 3.2 server.name field). Used to select which server URL to dispatch to when base_url is not set. If unset, the first server is used. Ignored when base_url is set.
Approval filters that will automatically set the approval requirement on tools synced from an external source
Tools in this tool set, keyed by external_id.
Spec ToolSpec
Config ToolSpecConfig
Config defines the adapter to use for the tool. This is used to determine how the tool is called. For example, if the tool is an HTTP tool, the adapter will be Http. If the tool is an inline tool, the adapter will be Inline.
Metadata OperationMetadata
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
Status BulkWorkspaceApplyStatus
State BulkWorkspaceApplyStatusState
PreflightError BulkWorkspaceApplyStatusPreflightErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
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
Spec ProfileSpec
type BulkWorkspaceApplyData struct{…}
BundleKey string
Required. Bundle ownership key. Resources created or updated by an
Apply have their metadata.bundle_key set to this value. On
subsequent applies with the same bundle_key, resources currently
bearing this bundle_key but absent from the spec are soft-deleted.
Agents to upsert, keyed by external_id.
Spec AgentSpec
Agent specification (user-provided configuration)
VariationSelectionMode AgentSpecVariationSelectionMode
Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
InputDataSchema map[string, unknown]Optional
InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as 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 map[string, unknown]Optional
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.
Schedules under this agent, keyed by external_id.
Spec AgentScheduleSpec
AgentScheduleSpec is the user-provided configuration for a schedule.
InitialMessage string
The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.
Schedule AgentScheduleSpecSchedule
Data unknownOptional
Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.
OverlapPolicy AgentScheduleSpecOverlapPolicyOptional
What to do when the previous run is still in flight. Defaults to SKIP.
Status AgentScheduleSpecStatusOptional
Lifecycle. Defaults to ACTIVE on create when unspecified.
Variations under this agent, keyed by external_id.
Spec AgentVariationSpec
AgentVariationSpec defines the operational configuration for a variation
Description stringOptional
Human-readable description of what this variation does or when it should be used
EnableEpisodicMemory boolOptional
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
EpisodicMemoryTtl int64Optional
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
RerankThreshold float64Optional
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
AutomaticallyPublishAgents boolOptional
When true, every agent created or updated by this Apply has its status forced to AGENT_STATUS_PUBLISHED, regardless of the status declared in the agent’s AgentSpec. Useful when the bundle represents a production configuration and you want all of its agents live without setting status: AGENT_STATUS_PUBLISHED on each entry.
Default false: each agent’s AgentSpec.status controls (which is AGENT_STATUS_DRAFT on create when unspecified).
Memory layers to upsert, keyed by external_id.
Spec MemoryLayerSpec
Description stringOptional
Human-readable description of the layer’s purpose. Encouraged for user-created layers; system-managed layers may have a generated description.
ExpiresAt TimeOptional
For layers with a finite lifetime (e.g., episodic), the time at which the layer becomes eligible for cleanup. Set by the system; unset for persistent layers.
SystemManaged boolOptional
Server-set. True for layers managed by the system (e.g., episodic layers created automatically when an objective uses an episodic_key). System-managed layers cannot be assigned to objective stacks via the API and cannot be mutated by clients — their lifecycle is controlled entirely by the runtime.
SourceURL stringOptional
Optional URL pointing to the source of this apply (GitHub PR, Jenkins build, GitLab pipeline, etc.). Surfaced in the dashboard so users can jump from an apply back to the change that produced it. Free-form HTTPS URI; not interpreted by the server.
Tool sets to upsert, keyed by external_id.
Spec ToolSetSpec
Approval filters that will automatically set the approval requirement on tools synced from an external source
BaseURL stringOptional
Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.
Headers map[string, string]Optional
Headers sent when fetching the spec from a URL and when dispatching tool calls.
ServerName stringOptional
Name of the server entry in the spec’s servers array (OpenAPI 3.2 server.name field). Used to select which server URL to dispatch to when base_url is not set. If unset, the first server is used. Ignored when base_url is set.
Approval filters that will automatically set the approval requirement on tools synced from an external source
Tools in this tool set, keyed by external_id.
Spec ToolSpec
Config ToolSpecConfig
Config defines the adapter to use for the tool. This is used to determine how the tool is called. For example, if the tool is an HTTP tool, the adapter will be Http. If the tool is an inline tool, the adapter will be Inline.
type BulkWorkspaceApplyInfo struct{…}
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
Spec ProfileSpec
type BulkWorkspaceApplyStatus struct{…}
State BulkWorkspaceApplyStatusState
PreflightError BulkWorkspaceApplyStatusPreflightErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
type MemoryLayerEntry struct{…}
Spec MemoryLayerSpec
Description stringOptional
Human-readable description of the layer’s purpose. Encouraged for user-created layers; system-managed layers may have a generated description.
ExpiresAt TimeOptional
For layers with a finite lifetime (e.g., episodic), the time at which the layer becomes eligible for cleanup. Set by the system; unset for persistent layers.
SystemManaged boolOptional
Server-set. True for layers managed by the system (e.g., episodic layers created automatically when an objective uses an episodic_key). System-managed layers cannot be assigned to objective stacks via the API and cannot be mutated by clients — their lifecycle is controlled entirely by the runtime.
type ToolEntry struct{…}
Spec ToolSpec
Config ToolSpecConfig
Config defines the adapter to use for the tool. This is used to determine how the tool is called. For example, if the tool is an HTTP tool, the adapter will be Http. If the tool is an inline tool, the adapter will be Inline.
type ToolSetEntry struct{…}
Spec ToolSetSpec
Approval filters that will automatically set the approval requirement on tools synced from an external source
BaseURL stringOptional
Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.
Headers map[string, string]Optional
Headers sent when fetching the spec from a URL and when dispatching tool calls.
ServerName stringOptional
Name of the server entry in the spec’s servers array (OpenAPI 3.2 server.name field). Used to select which server URL to dispatch to when base_url is not set. If unset, the first server is used. Ignored when base_url is set.
Approval filters that will automatically set the approval requirement on tools synced from an external source
Tools in this tool set, keyed by external_id.
Spec ToolSpec
Config ToolSpecConfig
Config defines the adapter to use for the tool. This is used to determine how the tool is called. For example, if the tool is an HTTP tool, the adapter will be Http. If the tool is an inline tool, the adapter will be Inline.
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
ModelsExpand Collapse
type BulkWorkspaceApplyResult struct{…}
One row of the per-resource result list for a BulkWorkspaceApply. Each row is itself an operation that can be paginated, sorted by created_at, and addressed individually.
Outcome for a single resource within a bulk apply. The type field is
the discriminator string naming the populated outcome oneof variant
(e.g., “toolSet”, “memoryEntry”). Every outcome shell carries an
action enum and either a resulting resource snapshot (for
ACTION_CREATED, ACTION_UPDATED, ACTION_UNCHANGED, ACTION_DELETED) or a
google.rpc.Status (for ACTION_FAILED).
Action BulkWorkspaceApplyResultDataAgentOutcomeActionOptional
Error BulkWorkspaceApplyResultDataAgentOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
Agent resource
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentSpec
Agent specification (user-provided configuration)
VariationSelectionMode AgentSpecVariationSelectionMode
Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
InputDataSchema map[string, unknown]Optional
InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as 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 map[string, unknown]Optional
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.
AgentInfo contains simple information about an agent for display or quick reference
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
Spec ProfileSpec
Action BulkWorkspaceApplyResultDataAgentScheduleOutcomeActionOptional
Error BulkWorkspaceApplyResultDataAgentScheduleOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentScheduleSpec
AgentScheduleSpec is the user-provided configuration for a schedule.
InitialMessage string
The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.
Schedule AgentScheduleSpecSchedule
Data unknownOptional
Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.
OverlapPolicy AgentScheduleSpecOverlapPolicyOptional
What to do when the previous run is still in flight. Defaults to SKIP.
Status AgentScheduleSpecStatusOptional
Lifecycle. Defaults to ACTIVE on create when unspecified.
AgentScheduleInfo provides read-only runtime data about a schedule.
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
Spec ProfileSpec
LastFireAt TimeOptional
When the schedule last fired (regardless of objective outcome).
LastSkippedAt TimeOptional
When the schedule most recently skipped a fire (SKIP policy + prior in flight).
LastSkipReason stringOptional
Reason for the most recent skip (e.g. “previous objective still running”).
Action BulkWorkspaceApplyResultDataAgentVariationOutcomeActionOptional
Error BulkWorkspaceApplyResultDataAgentVariationOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
AgentVariation resource
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentVariationSpec
AgentVariationSpec defines the operational configuration for a variation
Description stringOptional
Human-readable description of what this variation does or when it should be used
EnableEpisodicMemory boolOptional
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
EpisodicMemoryTtl int64Optional
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
RerankThreshold float64Optional
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
AgentVariationInfo provides read-only summary information about a variation
All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation’s full assignment list without calling the add/remove endpoints just to enumerate.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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
Spec ProfileSpec
FeedbackCount int64Optional
Total number of objective feedbacks received for this variation
Read-only list of memory layer assignments for this variation,
returned in ascending position (bottom → top). Capped at 10 entries.
ID stringOptional
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Position int64Optional
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Action BulkWorkspaceApplyResultDataMemoryEntryOutcomeActionOptional
Error BulkWorkspaceApplyResultDataMemoryEntryOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
MemoryEntry is a single keyed value within a MemoryLayer. Entries are addressed by their key, which follows the S3 object key safe-character convention (see MemoryEntrySpec.key for the full rule). Keys are unique within a single layer; the same key may appear in multiple layers, in which case the LIFO stack-walk determines which one wins for a given objective.
MemoryEntry is the summary shape, returned by ListMemoryEntries. It does not carry the entry body — callers that need the body must fetch the entry individually via GetMemoryEntry, which returns a MemoryEntryDetail.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec MemoryEntrySpec
MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views.
Key string
The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ’, (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., “skills/postmortem/write”), but lookups are flat — the key is a single opaque string, not a path.
Additional rules enforced by the service:
- May not begin or end with /
- May not contain consecutive slashes (//)
- May not begin with reserved prefixes (cadenya/, system/)
- Case-sensitive
- Unique within the parent layer
For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry’s content.
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
Spec ProfileSpec
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Action BulkWorkspaceApplyResultDataMemoryLayerOutcomeActionOptional
Error BulkWorkspaceApplyResultDataMemoryLayerOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
MemoryLayer is a named container of memory entries that can be composed into an objective’s memory stack. Layers are workspace-scoped resources. The layer type controls how its entries participate in the agent loop — see MemoryLayerType for details.
See “Memory stack composition” above for how layers compose at lookup time.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec MemoryLayerSpec
Description stringOptional
Human-readable description of the layer’s purpose. Encouraged for user-created layers; system-managed layers may have a generated description.
ExpiresAt TimeOptional
For layers with a finite lifetime (e.g., episodic), the time at which the layer becomes eligible for cleanup. Set by the system; unset for persistent layers.
SystemManaged boolOptional
Server-set. True for layers managed by the system (e.g., episodic layers created automatically when an objective uses an episodic_key). System-managed layers cannot be assigned to objective stacks via the API and cannot be mutated by clients — their lifecycle is controlled entirely by the runtime.
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
Spec ProfileSpec
Action BulkWorkspaceApplyResultDataToolOutcomeActionOptional
Error BulkWorkspaceApplyResultDataToolOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec ToolSpec
Config ToolSpecConfig
Config defines the adapter to use for the tool. This is used to determine how the tool is called. For example, if the tool is an HTTP tool, the adapter will be Http. If the tool is an inline tool, the adapter will be Inline.
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
Spec ProfileSpec
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Action BulkWorkspaceApplyResultDataToolSetOutcomeActionOptional
Error BulkWorkspaceApplyResultDataToolSetOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec ToolSetSpec
Approval filters that will automatically set the approval requirement on tools synced from an external source
BaseURL stringOptional
Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.
Headers map[string, string]Optional
Headers sent when fetching the spec from a URL and when dispatching tool calls.
ServerName stringOptional
Name of the server entry in the spec’s servers array (OpenAPI 3.2 server.name field). Used to select which server URL to dispatch to when base_url is not set. If unset, the first server is used. Ignored when base_url is set.
Approval filters that will automatically set the approval requirement on tools synced from an external source
Tool set information
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
Spec ProfileSpec
Action BulkWorkspaceApplyResultDataVariationAssignmentOutcomeActionOptional
Error BulkWorkspaceApplyResultDataVariationAssignmentOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
A read-only reference to a single tool, tool set, or sub-agent attached to
a variation. Read the full set of assignments via AgentVariationInfo.assignments;
mutations go through the dedicated add/remove assignment endpoints.
The id identifies the assignment itself (not the referenced resource) and
is the handle used to remove the assignment. It is returned by the add
endpoint and present on every entry in AgentVariationInfo.assignments.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Action BulkWorkspaceApplyResultDataVariationMemoryLayerOutcomeActionOptional
Error BulkWorkspaceApplyResultDataVariationMemoryLayerOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a given position in the variation’s baseline memory stack. A variation has at most one assignment per memory_layer_id.
Variations only support whole-layer attachments — entry pinning is an objective-level capability.
ID stringOptional
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Position int64Optional
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
Metadata OperationMetadata
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
type BulkWorkspaceApplyResultData struct{…}
Outcome for a single resource within a bulk apply. The type field is
the discriminator string naming the populated outcome oneof variant
(e.g., “toolSet”, “memoryEntry”). Every outcome shell carries an
action enum and either a resulting resource snapshot (for
ACTION_CREATED, ACTION_UPDATED, ACTION_UNCHANGED, ACTION_DELETED) or a
google.rpc.Status (for ACTION_FAILED).
Action BulkWorkspaceApplyResultDataAgentOutcomeActionOptional
Error BulkWorkspaceApplyResultDataAgentOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
Agent resource
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentSpec
Agent specification (user-provided configuration)
VariationSelectionMode AgentSpecVariationSelectionMode
Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
InputDataSchema map[string, unknown]Optional
InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as 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 map[string, unknown]Optional
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.
AgentInfo contains simple information about an agent for display or quick reference
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
Spec ProfileSpec
Action BulkWorkspaceApplyResultDataAgentScheduleOutcomeActionOptional
Error BulkWorkspaceApplyResultDataAgentScheduleOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentScheduleSpec
AgentScheduleSpec is the user-provided configuration for a schedule.
InitialMessage string
The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.
Schedule AgentScheduleSpecSchedule
Data unknownOptional
Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.
OverlapPolicy AgentScheduleSpecOverlapPolicyOptional
What to do when the previous run is still in flight. Defaults to SKIP.
Status AgentScheduleSpecStatusOptional
Lifecycle. Defaults to ACTIVE on create when unspecified.
AgentScheduleInfo provides read-only runtime data about a schedule.
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
Spec ProfileSpec
LastFireAt TimeOptional
When the schedule last fired (regardless of objective outcome).
LastSkippedAt TimeOptional
When the schedule most recently skipped a fire (SKIP policy + prior in flight).
LastSkipReason stringOptional
Reason for the most recent skip (e.g. “previous objective still running”).
Action BulkWorkspaceApplyResultDataAgentVariationOutcomeActionOptional
Error BulkWorkspaceApplyResultDataAgentVariationOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
AgentVariation resource
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentVariationSpec
AgentVariationSpec defines the operational configuration for a variation
Description stringOptional
Human-readable description of what this variation does or when it should be used
EnableEpisodicMemory boolOptional
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
EpisodicMemoryTtl int64Optional
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
RerankThreshold float64Optional
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
AgentVariationInfo provides read-only summary information about a variation
All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation’s full assignment list without calling the add/remove endpoints just to enumerate.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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
Spec ProfileSpec
FeedbackCount int64Optional
Total number of objective feedbacks received for this variation
Read-only list of memory layer assignments for this variation,
returned in ascending position (bottom → top). Capped at 10 entries.
ID stringOptional
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Position int64Optional
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Action BulkWorkspaceApplyResultDataMemoryEntryOutcomeActionOptional
Error BulkWorkspaceApplyResultDataMemoryEntryOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
MemoryEntry is a single keyed value within a MemoryLayer. Entries are addressed by their key, which follows the S3 object key safe-character convention (see MemoryEntrySpec.key for the full rule). Keys are unique within a single layer; the same key may appear in multiple layers, in which case the LIFO stack-walk determines which one wins for a given objective.
MemoryEntry is the summary shape, returned by ListMemoryEntries. It does not carry the entry body — callers that need the body must fetch the entry individually via GetMemoryEntry, which returns a MemoryEntryDetail.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec MemoryEntrySpec
MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views.
Key string
The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ’, (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., “skills/postmortem/write”), but lookups are flat — the key is a single opaque string, not a path.
Additional rules enforced by the service:
- May not begin or end with /
- May not contain consecutive slashes (//)
- May not begin with reserved prefixes (cadenya/, system/)
- Case-sensitive
- Unique within the parent layer
For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry’s content.
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
Spec ProfileSpec
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Action BulkWorkspaceApplyResultDataMemoryLayerOutcomeActionOptional
Error BulkWorkspaceApplyResultDataMemoryLayerOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
MemoryLayer is a named container of memory entries that can be composed into an objective’s memory stack. Layers are workspace-scoped resources. The layer type controls how its entries participate in the agent loop — see MemoryLayerType for details.
See “Memory stack composition” above for how layers compose at lookup time.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec MemoryLayerSpec
Description stringOptional
Human-readable description of the layer’s purpose. Encouraged for user-created layers; system-managed layers may have a generated description.
ExpiresAt TimeOptional
For layers with a finite lifetime (e.g., episodic), the time at which the layer becomes eligible for cleanup. Set by the system; unset for persistent layers.
SystemManaged boolOptional
Server-set. True for layers managed by the system (e.g., episodic layers created automatically when an objective uses an episodic_key). System-managed layers cannot be assigned to objective stacks via the API and cannot be mutated by clients — their lifecycle is controlled entirely by the runtime.
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
Spec ProfileSpec
Action BulkWorkspaceApplyResultDataToolOutcomeActionOptional
Error BulkWorkspaceApplyResultDataToolOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec ToolSpec
Config ToolSpecConfig
Config defines the adapter to use for the tool. This is used to determine how the tool is called. For example, if the tool is an HTTP tool, the adapter will be Http. If the tool is an inline tool, the adapter will be Inline.
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
Spec ProfileSpec
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Action BulkWorkspaceApplyResultDataToolSetOutcomeActionOptional
Error BulkWorkspaceApplyResultDataToolSetOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec ToolSetSpec
Approval filters that will automatically set the approval requirement on tools synced from an external source
BaseURL stringOptional
Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.
Headers map[string, string]Optional
Headers sent when fetching the spec from a URL and when dispatching tool calls.
ServerName stringOptional
Name of the server entry in the spec’s servers array (OpenAPI 3.2 server.name field). Used to select which server URL to dispatch to when base_url is not set. If unset, the first server is used. Ignored when base_url is set.
Approval filters that will automatically set the approval requirement on tools synced from an external source
Tool set information
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
Spec ProfileSpec
Action BulkWorkspaceApplyResultDataVariationAssignmentOutcomeActionOptional
Error BulkWorkspaceApplyResultDataVariationAssignmentOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
A read-only reference to a single tool, tool set, or sub-agent attached to
a variation. Read the full set of assignments via AgentVariationInfo.assignments;
mutations go through the dedicated add/remove assignment endpoints.
The id identifies the assignment itself (not the referenced resource) and
is the handle used to remove the assignment. It is returned by the add
endpoint and present on every entry in AgentVariationInfo.assignments.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Action BulkWorkspaceApplyResultDataVariationMemoryLayerOutcomeActionOptional
Error BulkWorkspaceApplyResultDataVariationMemoryLayerOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a given position in the variation’s baseline memory stack. A variation has at most one assignment per memory_layer_id.
Variations only support whole-layer attachments — entry pinning is an objective-level capability.
ID stringOptional
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Position int64Optional
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
type BulkWorkspaceApplyResultDataAgentOutcome struct{…}
Action BulkWorkspaceApplyResultDataAgentOutcomeActionOptional
Error BulkWorkspaceApplyResultDataAgentOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
Agent resource
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentSpec
Agent specification (user-provided configuration)
VariationSelectionMode AgentSpecVariationSelectionMode
Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
InputDataSchema map[string, unknown]Optional
InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as 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 map[string, unknown]Optional
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.
AgentInfo contains simple information about an agent for display or quick reference
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
Spec ProfileSpec
type BulkWorkspaceApplyResultDataAgentScheduleOutcome struct{…}
Action BulkWorkspaceApplyResultDataAgentScheduleOutcomeActionOptional
Error BulkWorkspaceApplyResultDataAgentScheduleOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentScheduleSpec
AgentScheduleSpec is the user-provided configuration for a schedule.
InitialMessage string
The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.
Schedule AgentScheduleSpecSchedule
Data unknownOptional
Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.
OverlapPolicy AgentScheduleSpecOverlapPolicyOptional
What to do when the previous run is still in flight. Defaults to SKIP.
Status AgentScheduleSpecStatusOptional
Lifecycle. Defaults to ACTIVE on create when unspecified.
AgentScheduleInfo provides read-only runtime data about a schedule.
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
Spec ProfileSpec
LastFireAt TimeOptional
When the schedule last fired (regardless of objective outcome).
LastSkippedAt TimeOptional
When the schedule most recently skipped a fire (SKIP policy + prior in flight).
LastSkipReason stringOptional
Reason for the most recent skip (e.g. “previous objective still running”).
type BulkWorkspaceApplyResultDataAgentVariationOutcome struct{…}
Action BulkWorkspaceApplyResultDataAgentVariationOutcomeActionOptional
Error BulkWorkspaceApplyResultDataAgentVariationOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
AgentVariation resource
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentVariationSpec
AgentVariationSpec defines the operational configuration for a variation
Description stringOptional
Human-readable description of what this variation does or when it should be used
EnableEpisodicMemory boolOptional
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
EpisodicMemoryTtl int64Optional
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
RerankThreshold float64Optional
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
AgentVariationInfo provides read-only summary information about a variation
All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation’s full assignment list without calling the add/remove endpoints just to enumerate.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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
Spec ProfileSpec
FeedbackCount int64Optional
Total number of objective feedbacks received for this variation
Read-only list of memory layer assignments for this variation,
returned in ascending position (bottom → top). Capped at 10 entries.
ID stringOptional
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Position int64Optional
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
type BulkWorkspaceApplyResultDataMemoryEntryOutcome struct{…}
Action BulkWorkspaceApplyResultDataMemoryEntryOutcomeActionOptional
Error BulkWorkspaceApplyResultDataMemoryEntryOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
MemoryEntry is a single keyed value within a MemoryLayer. Entries are addressed by their key, which follows the S3 object key safe-character convention (see MemoryEntrySpec.key for the full rule). Keys are unique within a single layer; the same key may appear in multiple layers, in which case the LIFO stack-walk determines which one wins for a given objective.
MemoryEntry is the summary shape, returned by ListMemoryEntries. It does not carry the entry body — callers that need the body must fetch the entry individually via GetMemoryEntry, which returns a MemoryEntryDetail.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec MemoryEntrySpec
MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views.
Key string
The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ’, (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., “skills/postmortem/write”), but lookups are flat — the key is a single opaque string, not a path.
Additional rules enforced by the service:
- May not begin or end with /
- May not contain consecutive slashes (//)
- May not begin with reserved prefixes (cadenya/, system/)
- Case-sensitive
- Unique within the parent layer
For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry’s content.
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
Spec ProfileSpec
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
type BulkWorkspaceApplyResultDataMemoryLayerOutcome struct{…}
Action BulkWorkspaceApplyResultDataMemoryLayerOutcomeActionOptional
Error BulkWorkspaceApplyResultDataMemoryLayerOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
MemoryLayer is a named container of memory entries that can be composed into an objective’s memory stack. Layers are workspace-scoped resources. The layer type controls how its entries participate in the agent loop — see MemoryLayerType for details.
See “Memory stack composition” above for how layers compose at lookup time.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec MemoryLayerSpec
Description stringOptional
Human-readable description of the layer’s purpose. Encouraged for user-created layers; system-managed layers may have a generated description.
ExpiresAt TimeOptional
For layers with a finite lifetime (e.g., episodic), the time at which the layer becomes eligible for cleanup. Set by the system; unset for persistent layers.
SystemManaged boolOptional
Server-set. True for layers managed by the system (e.g., episodic layers created automatically when an objective uses an episodic_key). System-managed layers cannot be assigned to objective stacks via the API and cannot be mutated by clients — their lifecycle is controlled entirely by the runtime.
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
Spec ProfileSpec
type BulkWorkspaceApplyResultDataToolOutcome struct{…}
Action BulkWorkspaceApplyResultDataToolOutcomeActionOptional
Error BulkWorkspaceApplyResultDataToolOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec ToolSpec
Config ToolSpecConfig
Config defines the adapter to use for the tool. This is used to determine how the tool is called. For example, if the tool is an HTTP tool, the adapter will be Http. If the tool is an inline tool, the adapter will be Inline.
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
Spec ProfileSpec
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
type BulkWorkspaceApplyResultDataToolSetOutcome struct{…}
Action BulkWorkspaceApplyResultDataToolSetOutcomeActionOptional
Error BulkWorkspaceApplyResultDataToolSetOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec ToolSetSpec
Approval filters that will automatically set the approval requirement on tools synced from an external source
BaseURL stringOptional
Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.
Headers map[string, string]Optional
Headers sent when fetching the spec from a URL and when dispatching tool calls.
ServerName stringOptional
Name of the server entry in the spec’s servers array (OpenAPI 3.2 server.name field). Used to select which server URL to dispatch to when base_url is not set. If unset, the first server is used. Ignored when base_url is set.
Approval filters that will automatically set the approval requirement on tools synced from an external source
Tool set information
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
Spec ProfileSpec
type BulkWorkspaceApplyResultDataVariationAssignmentOutcome struct{…}
Action BulkWorkspaceApplyResultDataVariationAssignmentOutcomeActionOptional
Error BulkWorkspaceApplyResultDataVariationAssignmentOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
A read-only reference to a single tool, tool set, or sub-agent attached to
a variation. Read the full set of assignments via AgentVariationInfo.assignments;
mutations go through the dedicated add/remove assignment endpoints.
The id identifies the assignment itself (not the referenced resource) and
is the handle used to remove the assignment. It is returned by the add
endpoint and present on every entry in AgentVariationInfo.assignments.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
type BulkWorkspaceApplyResultDataVariationMemoryLayerOutcome struct{…}
Action BulkWorkspaceApplyResultDataVariationMemoryLayerOutcomeActionOptional
Error BulkWorkspaceApplyResultDataVariationMemoryLayerOutcomeErrorOptional
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a given position in the variation’s baseline memory stack. A variation has at most one assignment per memory_layer_id.
Variations only support whole-layer attachments — entry pinning is an objective-level capability.
ID stringOptional
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Position int64Optional
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.