--- title: "Create a new objective" method: POST path: "/v1/workspaces/{workspaceId}/objectives" tags: ["ObjectiveService", "Objectives"] --- # Create a new objective `POST /v1/workspaces/{workspaceId}/objectives` Creates a new objective in the workspace ## Path parameters - `workspaceId` string, required ## Request body - CreateObjectiveRequest - `workspaceId` string, required - `agentId` string, required - `variationId` string — Optional explicit variation selection. Overrides the agent's variation_selection_mode. - `metadata` CreateOperationMetadata — CreateOperationMetadata contains the user-provided fields for creating an operation. Read-only fields (id, account_id, workspace_id, created_at, profile_id) are excluded since they are set by the server. - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `externalId` string — External ID for the operation (e.g., a workflow ID from an external system) - `systemPromptData` object, required — Arbitrary data rendered into the selected variation's system_prompt_template (liquid) to produce the objective's system prompt. If the agent has a system_prompt_data_schema, this must satisfy it. - `firstUserMessage` string — Optional explicit first user message for the LLM chat history. When not set, the selected variation's first_user_message_template is rendered with first_user_message_data instead. If neither this field nor a first_user_message_template is present, the request is rejected with InvalidArgument. - `secrets` CreateObjectiveRequestSecret[] — Secrets that can be used in the headers for tool calls using the secret interpolation format. - `name` string - `value` string - `memoryCascade` MemoryReference[] — Memory layers/entries layered over the baseline cascade inherited from the selected variation — element-level rules over inherited styles, in CSS terms. Array order is resolution order: EARLIER elements are more specific and are consulted first. Entries pinned via memory_entry_id behave as single-entry layers at their position. System-managed layers (e.g., episodic) cannot be referenced here; they attach themselves automatically based on the episodic key. Size cap: the TOTAL effective cascade (this field + the variation's memory layer assignments) must not exceed 10 entries. A request that would produce a larger cascade is rejected with InvalidArgument. - `memoryLayerId` string, required - `memoryEntryId` string — When set, inserts only this entry from memory_layer_id into the cascade — behaves as a single-entry layer (only this key resolves at this position). The entry must belong to memory_layer_id; mismatches are rejected with InvalidArgument. - `firstUserMessageData` object — Arbitrary data rendered into the selected variation's first_user_message_template (liquid) to produce the first user message. Separate from `system_prompt_data`, which renders the system prompt template. - `episodicMemory` ObjectiveEpisodicConfig — Episodic is used to configure the episodic memory for the objective - `key` string, required — The caller-supplied episodic key. Objectives created with the same key (for the same agent) share one episodic memory layer. - `memoryLayerId` string — The episodic memory layer resolved (created or reused) for this objective's key. Populated by the system at objective creation. - `tenant` TenantAssertion — TenantAssertion identifies a tenant in the customer's own namespace — their org, company, or team identifier for an end user. Asserting a tenant upserts the tenant record in the workspace (keyed on `id` as the tenant's external_id) and associates the created resource with it. - `id` string, required — The tenant identifier in the customer's namespace (e.g. "acme-corp"). Stored as the tenant record's external_id; stable across requests. - `name` string — Optional human-readable name for the tenant. Updates the tenant record's name on every assertion that provides it. - `subject` SubjectAssertion — SubjectAssertion identifies a person within a tenant in the customer's own namespace — typically their user id. Asserting a subject upserts the subject record under the asserted tenant and associates the created resource with it. A subject assertion is only valid alongside a tenant assertion: subject identifiers are scoped to their tenant. - `id` string, required — The subject identifier in the customer's namespace (e.g. their user id). Stored as the subject record's external_id; unique within the tenant. - `name` string — Optional human-readable name for the subject. Updates the subject record's name on every assertion that provides it. - `pinnedParameters` object — Parameters forced onto this objective's tool calls. A pinned parameter is an overlay on a tool's JSON schema: the parameter is removed from what the LLM sees, and its value is always overwritten server-side with the pinned value — the model cannot choose a different value for it. ## Response `200` OK - Objective — Objective is the data for an objective. It contains the snapshotted fields for the selected agent and variation. Secrets are returned only with their names, and the output definition is copied from the agent's configuration. - `metadata` OperationMetadata, required — Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `id` string, required — Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...") - `accountId` string, required — Account this operation belongs to for multi-tenant isolation (prefixed ULID) - `workspaceId` string, required — Workspace this operation belongs to for organizational grouping (prefixed ULID) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `createdAt` string, date-time, required — Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying - `externalId` string — External ID for the operation (e.g., a workflow ID from an external system) - `profileId` string, required — ID of the actor (user or service account) that created this operation - `configSnapshot` ObjectiveConfigSnapshot, required — ObjectiveConfigSnapshot is the point-in-time snapshot of the agent, variation, and (when applicable) schedule that an objective was started with. - `agent` Agent — Agent resource - `metadata` ResourceMetadata, required — Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID) - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} - `profileId` string, required — ID of the actor (user or service account) that created this resource - `createdAt` string, date-time, required — Timestamp when this resource was created - `updatedAt` string, date-time — Timestamp when this resource was last updated - `spec` AgentSpec, required — Agent specification (user-provided configuration) - `description` string — Description of the agent's purpose - `webhookEventsUrl` string — The URL that Cadenya will send events for any objective assigned to the agent. - `variationSelectionMode` 'VARIATION_SELECTION_MODE_UNSPECIFIED' | 'VARIATION_SELECTION_MODE_RANDOM' | 'VARIATION_SELECTION_MODE_WEIGHTED', enum, required — Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified - `systemPromptDataSchema` object — SystemPromptDataSchema enforces the shape of system_prompt_data when objectives are created. This is valuable when using liquid formatting in agent variation system prompt templates. The schema is also used when the agent is attached as a sub-agent, as it becomes the tool's input parameter schema. If omitted, the sub-agent schema will be loaded with a simple "prompt" free text string as its schema. - `outputDefinition` object — Optional output definition for objectives created for this agent. When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here. Use this option when you want structured data to be created by your objectives. - `enableEpisodicMemory` boolean — Enable episodic memory for objectives created for this agent. When true, objective creation requires an episodic_memory key and the system finds or creates a memory layer for that (agent, key) pair, letting the agent store and retrieve memories across objectives that share the key. Memory is agent-level so all variations of the agent share the same layers. - `episodicMemoryTtl` integer — How long episodic memories should be retained. Each new objective slides the layer's expiry forward by this duration, and stored entries expire this long after they are written. If not set, episodic memories are retained indefinitely. - `info` AgentInfo — AgentInfo contains simple information about an agent for display or quick reference - `variationCount` integer - `createdBy` Profile — A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata` AccountResourceMetadata, required — AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} - `profileId` string, required - `createdAt` string, date-time - `spec` ProfileSpec, required — Configuration for a profile. - `email` string — Email address of the profile. Required and unique within an account for user profiles. - `name` string — Display name (e.g., "Bobby Tables"). - `type` 'PROFILE_TYPE_UNSPECIFIED' | 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM', enum, required — Whether this profile represents a human user, an API key, or a system principal. - `state` 'STATE_UNSPECIFIED' | 'STATE_DRAFT' | 'STATE_PUBLISHED' | 'STATE_ARCHIVED', enum, required — The current lifecycle state of the agent. Output only. Agents are created in STATE_DRAFT; use the :publish, :unpublish, :archive, and :unarchive actions to transition between states. - `agentVariation` AgentVariation — AgentVariation resource - `metadata` ResourceMetadata, required — Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID) - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} - `profileId` string, required — ID of the actor (user or service account) that created this resource - `createdAt` string, date-time, required — Timestamp when this resource was created - `updatedAt` string, date-time — Timestamp when this resource was last updated - `spec` AgentVariationSpec, required — AgentVariationSpec defines the operational configuration for a variation - `systemPromptTemplate` string — Liquid template for the system prompt of objectives using this variation. Rendered with CreateObjectiveRequest.system_prompt_data into Objective.system_prompt. - `progressiveDiscovery` AgentVariationSpecProgressiveDiscovery — 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. - `maxTools` integer — The most tool names tool_search will load in a single call. Requesting more than this returns an error telling the model to retry in smaller batches -- it is a per-call batch limit, not a ceiling on how many tools an objective may end up with. - `hints` string[] — Free-text guidance appended to the discoverable-tools appendix in the system prompt. Hints steer the model's choice of tool names; they do not filter or rank anything, because tool_search matches names exactly rather than searching. - `constraints` AgentVariationSpecConstraints - `maxToolCalls` integer — The maximum number of tool calls that can be made. 0 means no limit. - `maxSubObjectives` integer — The maximum number of sub-objectives that can be created. 0 means no limit. - `inactivityTimeout` string — How long an objective may sit with no activity (no user messages, no LLM calls) before it is finalized as timed out. Between 1 minute and 24 hours, expressed as a duration string in seconds (e.g. "7200s"). When not set, objectives are still swept at the system-wide 24 hour maximum — every objective eventually reaches a terminal state. Note: no gnostic integer hint here on purpose. The Envoy gRPC-JSON transcoder only accepts the canonical protobuf JSON form for Durations — a "s" string — so the SDKs must type this as a string (like AgentScheduleSpec.every), not an integer. - `description` string — Human-readable description of what this variation does or when it should be used - `modelConfig` AgentVariationSpecModelConfig — ModelConfig defines the model configuration for a variation - `modelId` string — The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `temperature` number, float — Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `compactionConfig` AgentVariationSpecCompactionConfig — CompactionConfig defines how context window compaction behaves for objectives using this variation. - `triggerThreshold` number, float — Trigger threshold as a percentage of the model's context window (0.0 to 1.0). When input tokens reach this percentage of the model's limit, compaction triggers. Default: 0.75 (75%) - `summarization` CompactionConfigSummarizationStrategy — SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `instructions` string — Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `toolResultClearing` CompactionConfigToolResultClearingStrategy — ToolResultClearingStrategy configures clearing of older tool result content. - `preserveRecentResults` integer — Number of most recent tool call results to keep intact. Older tool results have their content replaced with "[result cleared]" while preserving the assistant tool call message (function name, arguments). Default: 2 - `firstUserMessageTemplate` string — Liquid template for the first user message of objectives using this variation. Rendered with CreateObjectiveRequest.first_user_message_data into Objective.first_user_message, the first user message in the LLM chat history. CreateObjectiveRequest.first_user_message, when set, overrides the rendered result. If neither this template nor first_user_message is present, objective creation is rejected with InvalidArgument. - `info` AgentVariationInfo — AgentVariationInfo provides read-only summary information about a variation - `toolCount` integer — Number of individual tools assigned to this variation - `toolSetCount` integer — Number of tool sets assigned to this variation - `subAgentCount` integer — Number of sub-agents assigned to this variation - `createdBy` Profile — A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata` AccountResourceMetadata, required — AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} - `profileId` string, required - `createdAt` string, date-time - `spec` ProfileSpec, required — Configuration for a profile. - `email` string — Email address of the profile. Required and unique within an account for user profiles. - `name` string — Display name (e.g., "Bobby Tables"). - `type` 'PROFILE_TYPE_UNSPECIFIED' | 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM', enum, required — Whether this profile represents a human user, an API key, or a system principal. - `model` ResourceMetadata — Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID) - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} - `profileId` string, required — ID of the actor (user or service account) that created this resource - `createdAt` string, date-time, required — Timestamp when this resource was created - `updatedAt` string, date-time — Timestamp when this resource was last updated - `score` number, float — Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta). Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative. - `feedbackCount` integer — Total number of objective feedbacks received for this variation - `assignments` VariationAssignment[] — 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. - union — 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`. - VariationAssignmentTool - … - VariationAssignmentToolSet - … - VariationAssignmentAgent - … - `memoryLayerAssignments` VariationMemoryLayerAssignment[] — Read-only list of memory layer assignments for this variation, returned in ascending `position` (most specific first — resolution order). Capped at 10 entries. - `id` string — Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer's id. - `memoryLayer` BareMetadata — 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. - `id` string - `name` string — Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `position` integer — Position in the variation's baseline cascade. Position is specificity, CSS-style: a LOWER position is more specific and is consulted first; the highest-position assignment is the most general fallback. 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. - `memoryLayerCount` integer — Count of memory layer assignments. - `agentSchedule` AgentSchedule — AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence. - `metadata` ResourceMetadata, required — Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID) - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} - `profileId` string, required — ID of the actor (user or service account) that created this resource - `createdAt` string, date-time, required — Timestamp when this resource was created - `updatedAt` string, date-time — Timestamp when this resource was last updated - `spec` AgentScheduleSpec, required — AgentScheduleSpec is the user-provided configuration for a schedule. - `schedule` AgentScheduleSpecSchedule, required — Schedule defines WHEN the schedule fires. Temporal-style structured form: a list of calendar rules (wall-clock) and/or interval rules (duration), OR'd together. At least one rule is required. - `calendars` ScheduleCalendar[] — Wall-clock rules. May be empty if `intervals` is non-empty. - `second` ScheduleRange[] - … - `minute` ScheduleRange[] - … - `hour` ScheduleRange[] - … - `dayOfMonth` ScheduleRange[] - … - `month` ScheduleRange[] - … - `dayOfWeek` ScheduleRange[] - … - `comment` string - `intervals` ScheduleInterval[] — Duration-based rules. May be empty if `calendars` is non-empty. - `every` string - `offset` string — Phase shift within `every`. Must be < `every` (enforced at runtime). - `timezone` string — IANA tz name (e.g. "America/New_York"). Required. Applies to calendars; intervals fire on wall-clock cadence anchored in this zone. - `overlapPolicy` 'OVERLAP_POLICY_UNSPECIFIED' | 'OVERLAP_POLICY_ALLOW' | 'OVERLAP_POLICY_SKIP', enum — What to do when the previous run is still in flight. Defaults to SKIP. - `firstUserMessage` string — Optional explicit first user message passed to CreateObjective on each fire. Becomes the first user message in the objective's chat history. When unset, the fired objective defers to the selected variation's first_user_message_template. - `variationId` string — Optional explicit variation. When unset, the agent's variation_selection_mode chooses per fire. - `systemPromptData` object — Optional data rendered into the variation's system_prompt_template when each fired objective is created. If the agent has a system_prompt_data_schema, this must satisfy it. - `firstUserMessageData` object — Optional data rendered into the variation's first_user_message_template when each fired objective is created. Separate from `system_prompt_data`, which renders the system prompt template. - `info` AgentScheduleInfo — AgentScheduleInfo provides read-only runtime data about a schedule. - `nextFireAt` string, date-time — When the schedule will next fire. Computed from the spec; absent when the schedule is STATE_PAUSED/STATE_ARCHIVED or has no future fire times. - `lastFireAt` string, date-time — When the schedule last fired (regardless of objective outcome). - `lastObjectiveId` string — ID of the most recent objective the schedule created. - `lastSkippedAt` string, date-time — When the schedule most recently skipped a fire (SKIP policy + prior in flight). - `lastSkipReason` string — Reason for the most recent skip (e.g. "previous objective still running"). - `totalFires` integer — Lifetime count of objectives created by this schedule. - `createdBy` Profile — A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata` AccountResourceMetadata, required — AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} - `profileId` string, required - `createdAt` string, date-time - `spec` ProfileSpec, required — Configuration for a profile. - `email` string — Email address of the profile. Required and unique within an account for user profiles. - `name` string — Display name (e.g., "Bobby Tables"). - `type` 'PROFILE_TYPE_UNSPECIFIED' | 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM', enum, required — Whether this profile represents a human user, an API key, or a system principal. - `state` 'STATE_UNSPECIFIED' | 'STATE_ACTIVE' | 'STATE_PAUSED' | 'STATE_ARCHIVED', enum, required — The current lifecycle state of the schedule. Output only. Schedules are created STATE_ACTIVE; use the :pause, :resume, and :archive actions to transition between states. - `state` 'STATE_UNSPECIFIED' | 'STATE_PENDING' | 'STATE_RUNNING' | 'STATE_WAITING' | 'STATE_FAILED' | 'STATE_CANCELLED' | 'STATE_FINALIZED' | 'STATE_TIMED_OUT', enum, required — The current lifecycle state of the objective. - `stateMessage` string — Optional human-readable detail about the current state (e.g. a failure reason). - `info` ObjectiveInfo — ObjectiveInfo provides read-only aggregated statistics about an objective's execution - `totalEvents` integer, required — Total number of events generated during this objective's execution - `totalToolCalls` integer, required — Total number of tool calls made during execution - `totalInputTokens` integer, required — Total input tokens consumed across all LLM completions across all context windows - `totalOutputTokens` integer, required — Total output tokens generated across all LLM completions across all context windows - `totalContextWindows` integer, required — Total number of context windows that this objective has generated - `totalIterations` integer, required - `createdBy` Profile, required — A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata` AccountResourceMetadata, required — AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} - `profileId` string, required - `createdAt` string, date-time - `spec` ProfileSpec, required — Configuration for a profile. - `email` string — Email address of the profile. Required and unique within an account for user profiles. - `name` string — Display name (e.g., "Bobby Tables"). - `type` 'PROFILE_TYPE_UNSPECIFIED' | 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM', enum, required — Whether this profile represents a human user, an API key, or a system principal. - `effectiveMemoryCascade` MemoryReference[], required — The effective memory cascade at objective creation time: the episodic layer (when present), then Objective.memory_cascade, then the variation's baseline layers by ascending position. Order is resolution order — index 0 is the most specific and is consulted first; the first layer containing a key wins. Returned on reads so clients can see exactly what the objective resolves against without re-joining variation state. - `memoryLayerId` string, required - `memoryEntryId` string — When set, inserts only this entry from memory_layer_id into the cascade — behaves as a single-entry layer (only this key resolves at this position). The entry must belong to memory_layer_id; mismatches are rejected with InvalidArgument. - `agent` ResourceMetadata, required — Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID) - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} - `profileId` string, required — ID of the actor (user or service account) that created this resource - `createdAt` string, date-time, required — Timestamp when this resource was created - `updatedAt` string, date-time — Timestamp when this resource was last updated - `agentVariation` ResourceMetadata, required — Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID) - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system) - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} - `profileId` string, required — ID of the actor (user or service account) that created this resource - `createdAt` string, date-time, required — Timestamp when this resource was created - `updatedAt` string, date-time — Timestamp when this resource was last updated - `currentContextWindowId` string, required — ID of the objective's current (most recent) context window. Hydrated on demand; empty when the objective has not yet produced a context window. - `tenant` TenantReference — TenantReference is the read-only echo of a resource's tenant association, carrying both Cadenya's canonical id and the customer's own key. - `id` string, required — Cadenya's canonical tenant id. - `externalId` string, required — The tenant identifier in the customer's namespace, as asserted. - `name` string — Human-readable name of the tenant, when one has been asserted. - `subject` SubjectReference — SubjectReference is the read-only echo of a resource's subject association, carrying both Cadenya's canonical id and the customer's own key. - `id` string, required — Cadenya's canonical subject id. - `externalId` string, required — The subject identifier in the customer's namespace, as asserted. Unique within the subject's tenant. - `name` string — Human-readable name of the subject, when one has been asserted. - `widget` BareMetadata — 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. - `id` string - `name` string — Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `systemPrompt` string, required — system_prompt is read-only, derived from the selected variation's prompt - `firstUserMessage` string, required — The first user message in the LLM chat history, either provided explicitly at creation or rendered from the variation's first_user_message_template. - `parentObjectiveId` string — A parent objective means the objective was spawned off using a separate agent to complete an objective - `secrets` ObjectiveSecret[] — Secrets that can be used in the headers for tool calls using the secret interpolation format. - `name` string - `systemPromptData` object — Arbitrary data rendered into the variation's system_prompt_template - `memoryCascade` MemoryReference[] — Memory layers/entries layered over the baseline cascade inherited from the selected variation — element-level rules over inherited styles, in CSS terms. Array order is resolution order: EARLIER elements are more specific and are consulted first. Entries pinned via memory_entry_id behave as single-entry layers at their position. System-managed layers (e.g., episodic) cannot be referenced here; they attach themselves automatically based on the episodic key. Size cap: the TOTAL effective cascade (this field + the variation's memory layer assignments) must not exceed 10 entries. A request that would produce a larger cascade is rejected with InvalidArgument. - `memoryLayerId` string, required - `memoryEntryId` string — When set, inserts only this entry from memory_layer_id into the cascade — behaves as a single-entry layer (only this key resolves at this position). The entry must belong to memory_layer_id; mismatches are rejected with InvalidArgument. - `output` object — The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred. This will only be set if the state of the objective is set to STATE_FINALIZED - `firstUserMessageData` object — Arbitrary data rendered into the variation's first_user_message_template - `episodicMemory` ObjectiveEpisodicConfig — Episodic is used to configure the episodic memory for the objective - `key` string, required — The caller-supplied episodic key. Objectives created with the same key (for the same agent) share one episodic memory layer. - `memoryLayerId` string — The episodic memory layer resolved (created or reused) for this objective's key. Populated by the system at objective creation. - `pinnedParameters` object — Parameters forced onto this objective's tool calls, as provided at creation. See CreateObjectiveRequest.pinned_parameters for semantics. ## Other responses - `default` — Default error response --- [API](https://skmtc.net/cadenya/apis/cadenya-api.md) · [All operations](https://skmtc.net/cadenya/apis/cadenya-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cadenya/cadenya-api/versions/ac1a7f084068/schema)