> ## Documentation Index > Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create an objective and stream its events > Creates an objective and streams its events over server-sent events (SSE) on the same connection, so a single request both starts the work and shows it happening. The request body is identical to Create objective, except that `metadata.externalId` is REQUIRED (it is this endpoint's idempotency key) and the stream-only `includeDeltas` flag is accepted. Repeating the request with an externalId that already exists in the workspace does not start a second objective — it attaches to the existing one and streams, resuming from `Last-Event-ID` when the header is present and from the current moment when it is not. (Create objective instead rejects a duplicate externalId with AlreadyExists.) That makes the endpoint safe to retry, so an SDK's automatic SSE reconnect resumes the objective rather than launching another. Each message is tagged by `type`: the first is always `objective`, carrying the objective and its ID, and every message after it is an `event` identical to what Stream objective events yields — including transient hb_ heartbeats, and dlt_ text deltas when `includeDeltas` is set. ## OpenAPI ````yaml https://openapi.cadenya.com/api-spec.yml post /v1/workspaces/{workspaceId}/objectives:stream openapi: 3.1.0 info: title: Cadenya API description: API for the Cadenya Agent Runtime platform. version: '1.0' servers: - url: https://api.cadenya.com description: Production server security: - bearerAuth: [] tags: - name: AIProviderKeyService - name: APIKeyService description: |- Issue, rotate, disable, and revoke the account's API keys. Keys belong to the account and reach the workspaces they are assigned to, or every workspace when all_workspaces is set. Creating or changing an all-workspaces key also requires the api_keys:admin scope, and a caller may only assign workspaces it can access itself and operate on keys whose scopes it holds. - name: AccountService description: >- Manage the authenticated account. Accounts are the top-level organizational unit and contain one or more workspaces. - name: AgentPoolService description: Manage shared agent pools and their lifecycle within a workspace. - name: AgentScheduleService description: >- Manage recurring schedules attached to agents. Schedules trigger objectives on a cadence defined by AgentScheduleSpec.Schedule. - name: AgentService description: >- Manage AI agents within a workspace. Agents define AI behavior and tool access. - name: AgentVariationService description: >- Manage variations of an agent and their tool, sub-agent, agent pool, and memory layer assignments. - name: MemoryService description: >- Manage memory layers and their entries. Layers are named containers that can be composed into an objective's memory cascade; entries are the keyed values within a layer. System-managed layers (e.g., episodic layers created by the runtime) cannot be mutated through this API. - name: ModelService description: |- Manage LLM models available to a workspace. Models represent provider and family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded with the supported models and you can enable or disable each one. On customer-provided AI provider keys you can also override prices and, where the provider has no catalog, define models yourself. - name: ObjectiveEventStreamsService - name: ObjectiveService - name: ProfilesService description: |- Operations on profiles, the account-level principals (users, API keys, system) that authenticate against the API. - name: SearchService - name: TenantService description: >- Read and erase tenants and the subjects under them. Tenants and subjects are created by assertion — on objective creation or widget session mint — never directly, so this service has no create or update: it exists to enumerate what assertions have produced, and to destroy it on request. - name: ToolService description: >- Manage tool sets and the tools they contain. Tool sets group related tools, and tools define specific capabilities available to agents. When a tool set is managed, only API key actors can modify its tools; human (profile) actors cannot. - name: TrustedEndpointService description: |- Manage the account's trusted endpoints: the hosts its tool sets may send requests to. The list applies to every workspace in the account. - name: UploadService description: |- Issue short-lived presigned URLs for direct client-to-object-storage uploads. Created uploads can be referenced by id when creating or updating resources that accept binary content (e.g., MemoryEntry). - name: WidgetService description: |- Manage embeddable chat widgets. A widget binds an agent to a globally unique hostname with a per-widget origin allowlist; browsers reach it with session tokens minted via WidgetSessionService. - name: WidgetSessionService description: >- Mint and manage widget sessions. Session creation is server-to-server only: the customer's backend authenticates its visitor, asserts tenant/subject context, attaches any per-visitor secrets, and receives a short-lived bearer token the browser uses against the widget host. - name: WorkspaceAdminService description: >- Administer workspaces across the account: create and archive workspaces and manage their membership. These operations are account-scoped and require the admin role (a token whose profile holds the WorkOS admin role); they live under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces tree so an admin can manage any workspace in the account, including ones they are not themselves a member of. - name: WorkspaceSecretService - name: WorkspaceService description: |- Manage workspaces within an account. Workspaces provide organizational grouping and isolation for resources such as agents, tools, and API keys. This is the workspace-scoped, end-user surface. Administrative operations (create / archive workspaces, manage members) live in WorkspaceAdminService under /v1/account/workspaces and require the admin role. paths: /v1/workspaces/{workspaceId}/objectives:stream: post: tags: - ObjectiveEventStreamsService - Objectives summary: Create an objective and stream its events description: >- Creates an objective and streams its events over server-sent events (SSE) on the same connection, so a single request both starts the work and shows it happening. The request body is identical to Create objective, except that `metadata.externalId` is REQUIRED (it is this endpoint's idempotency key) and the stream-only `includeDeltas` flag is accepted. Repeating the request with an externalId that already exists in the workspace does not start a second objective — it attaches to the existing one and streams, resuming from `Last-Event-ID` when the header is present and from the current moment when it is not. (Create objective instead rejects a duplicate externalId with AlreadyExists.) That makes the endpoint safe to retry, so an SDK's automatic SSE reconnect resumes the objective rather than launching another. Each message is tagged by `type`: the first is always `objective`, carrying the objective and its ID, and every message after it is an `event` identical to what Stream objective events yields — including transient hb_ heartbeats, and dlt_ text deltas when `includeDeltas` is set. operationId: ObjectiveEventStreamsService_CreateAndStreamObjective parameters: - name: workspaceId in: path required: true schema: type: string example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAndStreamObjectiveRequest' required: true responses: '200': description: A stream of Server-Sent Events content: text/event-stream: schema: $ref: '#/components/schemas/CreateAndStreamObjectiveResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' x-codeSamples: - lang: typescript label: TypeScript source: >- import Cadenya from '@cadenya/cadenya'; const client = new Cadenya(); const stream = await client.objectives.createAndStream({ agentId: "sample", metadata: {"externalId":"sample"} }); try { for await (const event of stream) { console.log(event); } } finally { await stream.close(); } - lang: go label: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\tcadenya \"go.cadenya.com/cadenya-go\"\n)\n\nfunc main() {\n\tclient, err := cadenya.NewClient()\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tctx := context.Background()\n\tparams := &cadenya.ObjectiveCreateAndStreamParams{\n\t\tAgentID: \"sample\",\n\t\tMetadata: &cadenya.CreateAndStreamObjectiveRequest_Metadata{ExternalID: \"sample\"},\n\t}\n\tstream, err := client.Objectives().CreateAndStream(ctx, params)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer stream.Close()\n\tfor stream.Next() {\n\t\tfmt.Println(stream.Current())\n\t}\n\tif err := stream.Err(); err != nil {\n\t\tlog.Fatal(err)\n\t}\n}" - lang: python label: Python source: |- from cadenya import Cadenya with Cadenya() as client: with client.objectives.create_and_stream(agent_id="sample", metadata={"external_id": "sample"}) as stream: for event in stream: print(event) - lang: ruby label: Ruby source: >- require "cadenya" client = Cadenya::Client.new stream = client.objectives.create_and_stream(agent_id: "sample", metadata: {"external_id" => "sample"}) stream.each { |event| puts event.inspect } - lang: bash label: CLI source: |- cadenya objectives create-and-stream \ --agent-id sample \ --external-id sample - lang: shell label: curl source: |- curl --request POST \ --url 'https://api.cadenya.com/v1/workspaces/workspace_123/objectives:stream' \ --header "Authorization: Bearer ${CADENYA_API_KEY}" \ --header 'Content-Type: application/json' \ --data '{"agentId":"sample","metadata":{"externalId":"sample"}}' components: schemas: CreateAndStreamObjectiveRequest: required: - agentId - workspaceId - metadata type: object properties: workspaceId: readOnly: true example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q type: string agentId: example: agent_01HXKD2E5NQM3T9AYWCFMGWT9Y type: string variationId: example: agentvar_01HXKD2E5NQM3T9AYWCF32BSPP type: string description: >- Optional explicit variation selection. Overrides the agent's variation_selection_mode. metadata: allOf: - $ref: '#/components/schemas/CreateAndStreamObjectiveRequest_Metadata' description: >- Required here, though Create objective leaves it optional: the external ID inside it is the idempotency key that makes a retry of this request resume the objective instead of starting another. systemPromptData: type: object additionalProperties: true description: >- 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: type: string description: >- 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: type: array items: $ref: '#/components/schemas/CreateObjectiveRequest_Secret' description: >- Secrets that can be used in the headers for tool calls using the secret interpolation format. memoryCascade: type: array items: $ref: '#/components/schemas/MemoryReference' description: |- 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. firstUserMessageData: type: object additionalProperties: true description: >- 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: allOf: - $ref: '#/components/schemas/ObjectiveEpisodicConfig' description: >- If the agent variation that is selected has episodic memory enabled, then this key is used to create/update a memory layer specific to the episodic memory. The layer may have a TTL configured by the variation. tenant: allOf: - $ref: '#/components/schemas/TenantAssertion' description: >- Optional tenant assertion — the customer's org/company identifier for the end user this objective serves. Upserts the tenant record in the workspace and associates the objective with it. subject: allOf: - $ref: '#/components/schemas/SubjectAssertion' description: >- Optional subject assertion — the person within the tenant this objective serves. Requires `tenant`; a subject asserted without a tenant is rejected with InvalidArgument. pinnedParameters: type: object additionalProperties: type: string description: >- Parameters forced onto this objective's tool calls. A pinned parameter is removed from the tool schema the LLM sees, and its value is always overwritten server-side with the pinned value — the model cannot choose a different value for it. By default a pinned key applies to every tool with a top-level parameter of the same name; a tool set's overlays (ToolSetSpec.overlays) can bind pinned keys to nested paths, differently named parameters, or a subset of tools. clientTools: allOf: - $ref: '#/components/schemas/ClientTools' description: |- Tools the caller defines and executes for this objective. Each definition is upserted into the agent's client tools tool set, and only the definitions listed here are loaded into this objective, always in its context window. A client tool replaces a variation tool with the same function name. includeDeltas: type: boolean description: >- Also stream transient assistantMessageDelta and reasoningDelta events: text fragments as the model generates them, ahead of the durable assistantMessage and reasoning events. Off by default. Applies only to the stream, so Create objective has no equivalent field. description: |- The request body for creating an objective and streaming its events. Accepts everything Create objective accepts, and additionally requires `metadata.externalId`, which is the idempotency key for the stream, and accepts the stream-only `includeDeltas` flag. CreateAndStreamObjectiveResponse: oneOf: - $ref: '#/components/schemas/CreateAndStreamObjectiveResponse_Objective' - $ref: '#/components/schemas/CreateAndStreamObjectiveResponse_Event' discriminator: propertyName: type mapping: objective: '#/components/schemas/CreateAndStreamObjectiveResponse_Objective' event: '#/components/schemas/CreateAndStreamObjectiveResponse_Event' description: |- One message on the create-and-stream feed. The first message is always the `objective` variant, sent as soon as the objective exists; every message after it is an `event`. Status: type: object properties: code: type: integer description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. format: int32 message: type: string description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. details: type: array items: anyOf: - $ref: '#/components/schemas/WidgetSessionErrorInfo' - $ref: '#/components/schemas/GoogleProtobufAny' description: >- A list of messages that carry the error details. There is a common set of message types for APIs to use. description: >- 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](https://github.com/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](https://cloud.google.com/apis/design/errors). CreateAndStreamObjectiveRequest_Metadata: required: - externalId type: object properties: labels: type: object additionalProperties: type: string description: |- 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: type: string description: |- External ID for the objective (e.g., a workflow ID from an external system), and this request's idempotency key. Required here, though Create objective leaves it optional. Reusing a value that already exists in the workspace attaches to that objective and streams it rather than creating another; Create objective instead rejects a duplicate with AlreadyExists. description: |- Objective metadata, with an external ID that is required here because it is the request's idempotency key: repeating a request that carries an external ID already in use attaches to that objective instead of starting a second one. CreateObjectiveRequest_Secret: type: object properties: name: type: string value: type: string MemoryReference: required: - memoryLayerId type: object properties: memoryLayerId: example: memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH type: string memoryEntryId: example: mementry_01HXKD2E5NQM3T9AYWCF5E52Z0 type: string description: >- 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. description: |- MemoryReference identifies a memory layer or a specific entry within one, for composition into a memory cascade. Used on objectives (where entry pinning is permitted). memory_layer_id accepts both the canonical form (memlyr_…) and the external-id form (external_id:my-custom-id). The same applies to memory_entry_id when set. ObjectiveEpisodicConfig: required: - key - memoryLayerId type: object properties: key: type: string description: >- The caller-supplied episodic key. Objectives created with the same key (for the same agent, tenant and subject) share one episodic memory layer. Empty on a response when the agent's always_include_subject_memories let the objective rely on its subject instead of a key. memoryLayerId: readOnly: true example: memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH type: string description: |- The episodic memory layer resolved (created or reused) for this objective's key, or for its subject when no key was given. The agent's store_memory writes go here. Populated by the system at objective creation. includedMemoryLayerIds: readOnly: true type: array items: type: string description: >- Layers loaded because the agent has always_include_subject_memories on and the objective asserted a subject: the subject's layers, then its tenant's layers that have no subject, in resolution order and excluding memory_layer_id. They sit after Objective.memory_cascade and before the variation's layers in effective_memory_cascade. Snapshotted at creation, and capped at 25 layers. description: Episodic is used to configure the episodic memory for the objective TenantAssertion: required: - id type: object properties: id: example: acme-corp type: string description: >- The tenant identifier in the customer's namespace (e.g. "acme-corp"). Stored as the tenant record's external_id; stable across requests. name: example: Acme Corp type: string description: >- Optional human-readable name for the tenant. Updates the tenant record's name on every assertion that provides it. description: >- 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. SubjectAssertion: required: - id type: object properties: id: example: customer-user-42 type: string description: >- 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: example: Jane Doe type: string description: |- Optional human-readable name for the subject. Updates the subject record's name on every assertion that provides it. description: >- 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. ClientTools: required: - definitions type: object properties: definitions: maxItems: 64 type: array items: $ref: '#/components/schemas/ClientToolDefinition' description: The tool definitions. Names must be unique within the list. description: |- The tools a caller defines and executes for one objective, and the settings that apply to them. CreateAndStreamObjectiveResponse_Objective: type: object required: - type - objective properties: type: type: string enum: - objective objective: allOf: - $ref: '#/components/schemas/Objective' description: >- The objective. Sent exactly once, as the first message. On a repeated request that attached to an existing objective, this is that objective rather than a newly created one. CreateAndStreamObjectiveResponse_Event: type: object required: - type - event properties: type: type: string enum: - event event: allOf: - $ref: '#/components/schemas/ObjectiveEvent' description: >- An objective event, identical to the payloads Stream objective events yields — including transient hb_ heartbeats, and dlt_ text deltas when includeDeltas is set. WidgetSessionErrorInfo: type: object description: >- google.rpc.ErrorInfo detail for widget lifecycle failures. Match both domain and reason; ignore unknown reasons rather than renewing automatically. required: - '@type' - domain - reason properties: '@type': type: string enum: - type.googleapis.com/google.rpc.ErrorInfo domain: type: string enum: - api.cadenya.com reason: $ref: '#/components/schemas/WidgetSessionErrorReason' metadata: type: object additionalProperties: type: string description: Optional non-sensitive context. Never contains tokens or secrets. GoogleProtobufAny: type: object properties: '@type': type: string description: The type of the serialized message. additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. ClientToolDefinition: required: - name type: object properties: name: example: getWeather type: string description: |- The function name the model calls, also the name callers match calls on. Letters, digits, "_" and "-", at most 64 characters, neither starting nor ending with "_". A client tool takes precedence over a tool from the agent variation with the same function name; names reserved by Cadenya-provided tools are rejected. description: type: string description: What the tool does, shown to the model. parameters: type: object additionalProperties: true description: >- JSON Schema for the tool's arguments. Omitted means the tool takes no arguments. requiresApproval: type: boolean description: >- When true, each call waits for ApproveToolCall before it is handed to the caller to execute. description: >- A tool defined by the caller when an objective is created and executed by the caller. Cadenya stores it as a bare tool in the agent's client tools tool set and hands each call back over the event stream (a ToolCalled event with the call waiting for content); the caller reports the result with SetToolCallContent. Only the client tools sent with a create request are loaded into that objective. Objective: required: - metadata - configSnapshot - state - systemPrompt - firstUserMessage - stateMessage - parentObjectiveId - secrets - memoryCascade - pinnedParameters type: object properties: metadata: $ref: '#/components/schemas/OperationMetadata' configSnapshot: readOnly: true allOf: - $ref: '#/components/schemas/ObjectiveConfigSnapshot' description: >- The snapshot of the agent and the variation selected (either explicitly or by sampling) will be set here. Cadenya stores the point-in-time snapshot of the configuration used to start an objective and maintains it throughout the entire lifecycle so that changes to agents and variations in the middle of a cycle don't impact the objective itself state: readOnly: true enum: - OBJECTIVE_STATE_UNSPECIFIED - OBJECTIVE_STATE_PENDING - OBJECTIVE_STATE_RUNNING - OBJECTIVE_STATE_WAITING - OBJECTIVE_STATE_FAILED - OBJECTIVE_STATE_CANCELLED - OBJECTIVE_STATE_FINALIZED - OBJECTIVE_STATE_TIMED_OUT - OBJECTIVE_STATE_INTERRUPTING type: string description: The current lifecycle state of the objective. format: enum stateMessage: readOnly: true type: string description: >- Optional human-readable detail about the current state (e.g. a failure reason). info: readOnly: true allOf: - $ref: '#/components/schemas/ObjectiveInfo' description: Read-only aggregated info about this objective's execution systemPrompt: readOnly: true type: string description: >- system_prompt is read-only, derived from the selected variation's prompt firstUserMessage: type: string description: >- 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: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: >- A parent objective means the objective was spawned off using a separate agent to complete an objective secrets: type: array items: $ref: '#/components/schemas/Objective_Secret' description: >- Secrets that can be used in the headers for tool calls using the secret interpolation format. systemPromptData: readOnly: true type: object additionalProperties: true description: Arbitrary data rendered into the variation's system_prompt_template memoryCascade: type: array items: $ref: '#/components/schemas/MemoryReference' description: |- 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. output: readOnly: true type: object additionalProperties: true description: >- 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 OBJECTIVE_STATE_FINALIZED firstUserMessageData: readOnly: true type: object additionalProperties: true description: >- Arbitrary data rendered into the variation's first_user_message_template episodicMemory: allOf: - $ref: '#/components/schemas/ObjectiveEpisodicConfig' description: >- If the agent variation that is selected has episodic memory enabled, then this key is used to create/update a memory layer specific to the episodic memory. The layer may have a TTL configured by the variation. pinnedParameters: readOnly: true type: object additionalProperties: type: string description: |- Parameters forced onto this objective's tool calls, as provided at creation. See CreateObjectiveRequest.pinned_parameters for semantics. description: >- 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. ObjectiveEvent: required: - metadata - data - contextWindowId type: object properties: metadata: allOf: - $ref: '#/components/schemas/OperationMetadata' description: |- Durable events use objevt_ IDs, the only IDs accepted as reconnect cursors. Live-only heartbeats use hb_ IDs and live-only text deltas use dlt_ IDs; neither has an SSE id: field. data: $ref: '#/components/schemas/ObjectiveEventData' contextWindowId: example: objwin_01HXKD2E5NQM3T9AYWCFN7BSTR type: string info: $ref: '#/components/schemas/ObjectiveEventInfo' duration: readOnly: true pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: |- Elapsed time of the work this event records, when it is known at write time (e.g. assistant message generation, tool execution for result/error events). Unset means the event is instantaneous or the duration is not measurable. Serialized as a canonical duration string (e.g. "4.1s"). Always set together with started_at. startedAt: readOnly: true type: string description: |- When the work this event records began. Set together with duration, so the work interval is [started_at, started_at + duration]. The event's created_at remains the time the event was persisted. format: date-time sequence: readOnly: true type: integer description: |- The event's commit-ordered position in its objective, starting at 1. Sequences are per objective and gapless. History and stream backlogs return events in sequence order. Unset on live-only heartbeats. format: int32 WidgetSessionErrorReason: type: string description: >- TOKEN_EXPIRED identifies access-token expiry beyond the 60-second clock-skew tolerance. That token cannot renew; use already-installed newer credentials or require explicit app reauthentication. SESSION_* reasons are terminal. Never infer renewability from HTTP status alone. enum: - TOKEN_EXPIRED - SESSION_REVOKED - SESSION_EXPIRED - SESSION_EXHAUSTED OperationMetadata: required: - id - accountId - workspaceId - profileId - createdAt - labels - externalId type: object properties: id: readOnly: true type: string description: >- Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...") accountId: readOnly: true example: account_01HXKD2E5NQM3T9AYWCFTJHJVF type: string description: >- Account this operation belongs to for multi-tenant isolation (prefixed ULID) workspaceId: readOnly: true example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q type: string description: >- Workspace this operation belongs to for organizational grouping (prefixed ULID) labels: type: object additionalProperties: type: string description: |- 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: readOnly: true type: string description: |- Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying format: date-time externalId: type: string description: >- External ID for the operation (e.g., a workflow ID from an external system) profileId: readOnly: true example: profile_01HXKD2E5NQM3T9AYWCFS0AP08 type: string description: >- ID of the actor (user or service account) that created this operation description: >- Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) ObjectiveConfigSnapshot: required: - agent - agentVariation type: object properties: agent: $ref: '#/components/schemas/Agent' agentVariation: $ref: '#/components/schemas/AgentVariation' agentSchedule: $ref: '#/components/schemas/AgentSchedule' description: >- ObjectiveConfigSnapshot is the point-in-time snapshot of the agent, variation, and (when applicable) schedule that an objective was started with. ObjectiveInfo: required: - totalEvents - totalToolCalls - totalInputTokens - totalOutputTokens - totalContextWindows - totalIterations - createdBy - effectiveMemoryCascade - agent - agentVariation - currentContextWindowId type: object properties: totalEvents: readOnly: true type: integer description: Total number of events generated during this objective's execution format: int32 totalToolCalls: readOnly: true type: integer description: Total number of tool calls made during execution format: int32 totalInputTokens: readOnly: true type: integer description: >- Total input tokens consumed across all LLM completions across all context windows format: int32 totalOutputTokens: readOnly: true type: integer description: >- Total output tokens generated across all LLM completions across all context windows format: int32 totalContextWindows: readOnly: true type: integer description: Total number of context windows that this objective has generated format: int32 totalIterations: readOnly: true type: integer format: int32 createdBy: $ref: '#/components/schemas/Profile' effectiveMemoryCascade: readOnly: true type: array items: $ref: '#/components/schemas/MemoryReference' description: |- The effective memory cascade at objective creation time: the episodic layer (when present), then Objective.memory_cascade, then the subject and tenant layers in episodic_memory.included_memory_layer_ids, 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. agent: readOnly: true allOf: - $ref: '#/components/schemas/ResourceMetadata' description: Agent details (not snapshotted). agentVariation: readOnly: true allOf: - $ref: '#/components/schemas/ResourceMetadata' description: Agent variation details (not snapshotted). currentContextWindowId: readOnly: true example: objwin_01HXKD2E5NQM3T9AYWCFN7BSTR type: string description: >- 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: readOnly: true allOf: - $ref: '#/components/schemas/TenantReference' description: >- The tenant this objective is associated with, when one was asserted at creation (directly or via a widget session). subject: readOnly: true allOf: - $ref: '#/components/schemas/SubjectReference' description: |- The subject (person within the tenant) this objective is associated with, when one was asserted at creation. widget: readOnly: true allOf: - $ref: '#/components/schemas/BareMetadata' description: |- The widget this objective's conversation ran through, when it was created via a widget session. description: >- ObjectiveInfo provides read-only aggregated statistics about an objective's execution Objective_Secret: required: - name type: object properties: name: type: string ObjectiveEventData: oneOf: - $ref: '#/components/schemas/ObjectiveEventData_UserMessage' - $ref: '#/components/schemas/ObjectiveEventData_ToolApprovalRequested' - $ref: '#/components/schemas/ObjectiveEventData_ToolApproved' - $ref: '#/components/schemas/ObjectiveEventData_ToolDenied' - $ref: '#/components/schemas/ObjectiveEventData_ToolCalled' - $ref: '#/components/schemas/ObjectiveEventData_Error' - $ref: '#/components/schemas/ObjectiveEventData_AssistantMessage' - $ref: '#/components/schemas/ObjectiveEventData_ToolResult' - $ref: '#/components/schemas/ObjectiveEventData_ToolError' - $ref: '#/components/schemas/ObjectiveEventData_ContextWindowCompacted' - $ref: '#/components/schemas/ObjectiveEventData_MemoryRead' - $ref: '#/components/schemas/ObjectiveEventData_Cancelled' - $ref: '#/components/schemas/ObjectiveEventData_SubAgentSpawned' - $ref: '#/components/schemas/ObjectiveEventData_SubAgentUpdated' - $ref: '#/components/schemas/ObjectiveEventData_Finalized' - $ref: '#/components/schemas/ObjectiveEventData_Notice' - $ref: '#/components/schemas/ObjectiveEventData_TimedOut' - $ref: '#/components/schemas/ObjectiveEventData_Reasoning' - $ref: '#/components/schemas/ObjectiveEventData_StateChanged' - $ref: '#/components/schemas/ObjectiveEventData_Heartbeat' - $ref: '#/components/schemas/ObjectiveEventData_Interrupted' - $ref: '#/components/schemas/ObjectiveEventData_AssistantMessageDelta' - $ref: '#/components/schemas/ObjectiveEventData_ReasoningDelta' discriminator: propertyName: type mapping: userMessage: '#/components/schemas/ObjectiveEventData_UserMessage' toolApprovalRequested: '#/components/schemas/ObjectiveEventData_ToolApprovalRequested' toolApproved: '#/components/schemas/ObjectiveEventData_ToolApproved' toolDenied: '#/components/schemas/ObjectiveEventData_ToolDenied' toolCalled: '#/components/schemas/ObjectiveEventData_ToolCalled' error: '#/components/schemas/ObjectiveEventData_Error' assistantMessage: '#/components/schemas/ObjectiveEventData_AssistantMessage' toolResult: '#/components/schemas/ObjectiveEventData_ToolResult' toolError: '#/components/schemas/ObjectiveEventData_ToolError' contextWindowCompacted: '#/components/schemas/ObjectiveEventData_ContextWindowCompacted' memoryRead: '#/components/schemas/ObjectiveEventData_MemoryRead' cancelled: '#/components/schemas/ObjectiveEventData_Cancelled' subAgentSpawned: '#/components/schemas/ObjectiveEventData_SubAgentSpawned' subAgentUpdated: '#/components/schemas/ObjectiveEventData_SubAgentUpdated' finalized: '#/components/schemas/ObjectiveEventData_Finalized' notice: '#/components/schemas/ObjectiveEventData_Notice' timedOut: '#/components/schemas/ObjectiveEventData_TimedOut' reasoning: '#/components/schemas/ObjectiveEventData_Reasoning' stateChanged: '#/components/schemas/ObjectiveEventData_StateChanged' heartbeat: '#/components/schemas/ObjectiveEventData_Heartbeat' interrupted: '#/components/schemas/ObjectiveEventData_Interrupted' assistantMessageDelta: '#/components/schemas/ObjectiveEventData_AssistantMessageDelta' reasoningDelta: '#/components/schemas/ObjectiveEventData_ReasoningDelta' ObjectiveEventInfo: required: - createdBy type: object properties: objective: $ref: '#/components/schemas/OperationMetadata' createdBy: $ref: '#/components/schemas/Profile' Agent: required: - metadata - spec - state - info type: object properties: metadata: allOf: - $ref: '#/components/schemas/ResourceMetadata' description: Resource metadata spec: allOf: - $ref: '#/components/schemas/AgentSpec' description: Agent specification info: readOnly: true allOf: - $ref: '#/components/schemas/AgentInfo' description: Agent information state: readOnly: true enum: - STATE_UNSPECIFIED - STATE_DRAFT - STATE_PUBLISHED - STATE_ARCHIVED type: string description: >- 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. format: enum description: Agent resource AgentVariation: required: - metadata - spec - info type: object properties: metadata: allOf: - $ref: '#/components/schemas/ResourceMetadata' description: Resource metadata spec: allOf: - $ref: '#/components/schemas/AgentVariationSpec' description: Variation specification info: readOnly: true allOf: - $ref: '#/components/schemas/AgentVariationInfo' description: Read-only summary information description: AgentVariation resource AgentSchedule: required: - metadata - spec - state - info type: object properties: metadata: $ref: '#/components/schemas/ResourceMetadata' spec: $ref: '#/components/schemas/AgentScheduleSpec' info: $ref: '#/components/schemas/AgentScheduleInfo' state: readOnly: true enum: - STATE_UNSPECIFIED - STATE_ACTIVE - STATE_PAUSED - STATE_ARCHIVED type: string description: >- 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. format: enum description: |- AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence. Profile: required: - metadata - spec type: object properties: metadata: $ref: '#/components/schemas/AccountResourceMetadata' spec: $ref: '#/components/schemas/ProfileSpec' description: |- 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. ResourceMetadata: required: - id - accountId - workspaceId - name - profileId - createdAt - externalId - labels type: object properties: id: readOnly: true type: string description: >- Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") accountId: readOnly: true example: account_01HXKD2E5NQM3T9AYWCFTJHJVF type: string description: >- Account this resource belongs to for multi-tenant isolation (prefixed ULID) workspaceId: readOnly: true example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q type: string description: >- Workspace this resource belongs to for organizational grouping (prefixed ULID) name: type: string description: >- Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly externalId: type: string description: >- External ID for the resource (e.g., a workflow ID from an external system) labels: type: object additionalProperties: type: string description: |- 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: readOnly: true example: profile_01HXKD2E5NQM3T9AYWCFS0AP08 type: string description: ID of the actor (user or service account) that created this resource createdAt: readOnly: true type: string description: Timestamp when this resource was created format: date-time updatedAt: readOnly: true type: string description: Timestamp when this resource was last updated format: date-time description: >- Standard metadata for persistent, named resources (e.g., agents, tools, prompts) TenantReference: required: - id - externalId type: object properties: id: readOnly: true example: tenant_01HXKD2E5NQM3T9AYWCF133E3Q type: string description: Cadenya's canonical tenant id. externalId: readOnly: true example: acme-corp type: string description: The tenant identifier in the customer's namespace, as asserted. name: readOnly: true example: Acme Corp type: string description: Human-readable name of the tenant, when one has been asserted. description: >- TenantReference is the read-only echo of a resource's tenant association, carrying both Cadenya's canonical id and the customer's own key. SubjectReference: required: - id - externalId type: object properties: id: readOnly: true example: subj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: Cadenya's canonical subject id. externalId: readOnly: true example: customer-user-42 type: string description: >- The subject identifier in the customer's namespace, as asserted. Unique within the subject's tenant. name: readOnly: true example: Jane Doe type: string description: Human-readable name of the subject, when one has been asserted. description: >- SubjectReference is the read-only echo of a resource's subject association, carrying both Cadenya's canonical id and the customer's own key. BareMetadata: required: - id type: object properties: id: readOnly: true type: string name: readOnly: true type: string description: >- 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. description: |- 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 assignment metadata inside agent variation info 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. ObjectiveEventData_UserMessage: type: object required: - type - userMessage properties: type: type: string enum: - userMessage userMessage: $ref: '#/components/schemas/UserMessage' ObjectiveEventData_ToolApprovalRequested: type: object required: - type - toolApprovalRequested properties: type: type: string enum: - toolApprovalRequested toolApprovalRequested: $ref: '#/components/schemas/ToolApprovalRequested' ObjectiveEventData_ToolApproved: type: object required: - type - toolApproved properties: type: type: string enum: - toolApproved toolApproved: $ref: '#/components/schemas/ToolApproved' ObjectiveEventData_ToolDenied: type: object required: - type - toolDenied properties: type: type: string enum: - toolDenied toolDenied: $ref: '#/components/schemas/ToolDenied' ObjectiveEventData_ToolCalled: type: object required: - type - toolCalled properties: type: type: string enum: - toolCalled toolCalled: $ref: '#/components/schemas/ToolCalled' ObjectiveEventData_Error: type: object required: - type - error properties: type: type: string enum: - error error: $ref: '#/components/schemas/ObjectiveError' ObjectiveEventData_AssistantMessage: type: object required: - type - assistantMessage properties: type: type: string enum: - assistantMessage assistantMessage: $ref: '#/components/schemas/AssistantMessage' ObjectiveEventData_ToolResult: type: object required: - type - toolResult properties: type: type: string enum: - toolResult toolResult: $ref: '#/components/schemas/ToolResult' ObjectiveEventData_ToolError: type: object required: - type - toolError properties: type: type: string enum: - toolError toolError: $ref: '#/components/schemas/ToolError' ObjectiveEventData_ContextWindowCompacted: type: object required: - type - contextWindowCompacted properties: type: type: string enum: - contextWindowCompacted contextWindowCompacted: $ref: '#/components/schemas/ContextWindowCompacted' ObjectiveEventData_MemoryRead: type: object required: - type - memoryRead properties: type: type: string enum: - memoryRead memoryRead: $ref: '#/components/schemas/MemoryRead' ObjectiveEventData_Cancelled: type: object required: - type - cancelled properties: type: type: string enum: - cancelled cancelled: $ref: '#/components/schemas/ObjectiveCancelled' ObjectiveEventData_SubAgentSpawned: type: object required: - type - subAgentSpawned properties: type: type: string enum: - subAgentSpawned subAgentSpawned: $ref: '#/components/schemas/SubAgentSpawned' ObjectiveEventData_SubAgentUpdated: type: object required: - type - subAgentUpdated properties: type: type: string enum: - subAgentUpdated subAgentUpdated: $ref: '#/components/schemas/SubAgentUpdated' ObjectiveEventData_Finalized: type: object required: - type - finalized properties: type: type: string enum: - finalized finalized: $ref: '#/components/schemas/ObjectiveFinalized' ObjectiveEventData_Notice: type: object required: - type - notice properties: type: type: string enum: - notice notice: $ref: '#/components/schemas/Notice' ObjectiveEventData_TimedOut: type: object required: - type - timedOut properties: type: type: string enum: - timedOut timedOut: $ref: '#/components/schemas/ObjectiveTimedOut' ObjectiveEventData_Reasoning: type: object required: - type - reasoning properties: type: type: string enum: - reasoning reasoning: $ref: '#/components/schemas/Reasoning' ObjectiveEventData_StateChanged: type: object required: - type - stateChanged properties: type: type: string enum: - stateChanged stateChanged: $ref: '#/components/schemas/ObjectiveStateChanged' ObjectiveEventData_Heartbeat: type: object required: - type - heartbeat properties: type: type: string enum: - heartbeat heartbeat: $ref: '#/components/schemas/ObjectiveHeartbeat' ObjectiveEventData_Interrupted: type: object required: - type - interrupted properties: type: type: string enum: - interrupted interrupted: $ref: '#/components/schemas/ObjectiveInterrupted' ObjectiveEventData_AssistantMessageDelta: type: object required: - type - assistantMessageDelta properties: type: type: string enum: - assistantMessageDelta assistantMessageDelta: $ref: '#/components/schemas/AssistantMessageDelta' ObjectiveEventData_ReasoningDelta: type: object required: - type - reasoningDelta properties: type: type: string enum: - reasoningDelta reasoningDelta: $ref: '#/components/schemas/ReasoningDelta' AgentSpec: type: object properties: description: type: string description: Description of the agent's purpose webhookEventsUrl: type: string description: >- The URL that Cadenya will send events for any objective assigned to the agent. variationSelectionMode: enum: - VARIATION_SELECTION_MODE_UNSPECIFIED - VARIATION_SELECTION_MODE_RANDOM - VARIATION_SELECTION_MODE_WEIGHTED type: string description: >- Controls how variations are automatically selected when creating objectives Defaults to WEIGHTED when unspecified format: enum systemPromptDataSchema: type: object additionalProperties: true description: >- 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: type: object additionalProperties: true description: |- 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: type: boolean description: |- Enable episodic memory for objectives created for this agent. When true, objective creation requires an episodic_memory key (unless always_include_subject_memories covers it) and the system finds or creates a memory layer for that (agent, tenant, subject, key), letting the agent store and retrieve memories across objectives that share them. Memory is agent-level so all variations of the agent share the same layers. episodicMemoryTtl: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: integer description: |- 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. alwaysIncludeSubjectMemories: type: boolean description: |- Always load the asserted subject's memories. Requires enable_episodic_memory. When an objective asserts a subject: * Every memory layer scoped to that subject loads into the cascade, followed by the tenant's layers that have no subject (tenant-wide defaults). They rank below the objective's own memory_cascade references and above the variation's layers. * The episodic_memory key becomes optional. Without one, the agent stores memories in a system-managed episodic layer for (agent, tenant, subject), so it remembers the person across objectives with no key from the caller. With one, the keyed layer receives writes and the subject's other layers, including that keyless one, still load beneath it. description: Agent specification (user-provided configuration) AgentInfo: required: - variationCount type: object properties: variationCount: readOnly: true type: integer format: int32 createdBy: $ref: '#/components/schemas/Profile' description: >- AgentInfo contains simple information about an agent for display or quick reference AgentVariationSpec: type: object properties: systemPromptTemplate: type: string description: >- Liquid template for the system prompt of objectives using this variation. Rendered with CreateObjectiveRequest.system_prompt_data into Objective.system_prompt. progressiveDiscovery: allOf: - $ref: '#/components/schemas/AgentVariationSpec_ProgressiveDiscovery' description: >- ProgressiveDiscovery is an optional config that, when set, will load a Cadenya provided tool that can search for tools in the assigned tool sets or tools. Note: Sub-agents and agent pools are always loaded as tools regardless of this value. constraints: allOf: - $ref: '#/components/schemas/AgentVariationSpec_Constraints' description: Execution constraints description: type: string description: >- Human-readable description of what this variation does or when it should be used modelConfig: allOf: - $ref: '#/components/schemas/AgentVariationSpec_ModelConfig' description: Model configuration for this variation compactionConfig: allOf: - $ref: '#/components/schemas/AgentVariationSpec_CompactionConfig' description: >- Compaction configuration for managing context window limits during long-running objectives. When not set, the system uses a default summarization strategy at 75% context window usage. firstUserMessageTemplate: type: string description: >- 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. assignments: type: array items: $ref: '#/components/schemas/VariationAssignment' description: >- Complete set of assigned tools, tool sets, sub-agents, and agent pools. Order has no meaning. Duplicate (target kind, canonical target ID) pairs are collapsed. On create, omitted or empty means no assignments. On update, selecting spec.assignments in update_mask replaces the entire set; empty clears it. memoryLayerAssignments: maxItems: 10 type: array items: $ref: '#/components/schemas/VariationMemoryLayerAssignment' description: >- Complete baseline memory cascade, returned in ascending position. At most 10 whole layers; system-managed layers cannot be assigned. Duplicate layer IDs (after alias resolution) or positions are InvalidArgument. Validate the final cascade, so swapping two positions in one update is supported. On create, omitted or empty means no layers. On update, selecting spec.memory_layer_assignments replaces the entire list; empty clears it. description: |- AgentVariationSpec defines the complete operational configuration for a variation, including assignments. Reads always populate both assignment lists, even when include_info is false. Create and update validate and persist the configuration atomically: any invalid target or cascade rejects the entire request. Targets must belong to the variation's workspace and pass the same eligibility checks as the dedicated add methods. AgentVariationInfo: required: - toolCount - toolSetCount - subAgentCount - agentPoolCount - score - feedbackCount - memoryLayerCount - effectiveToolCount - assignmentMetadata type: object properties: toolCount: readOnly: true type: integer description: Number of individual tools assigned to this variation format: int32 toolSetCount: readOnly: true type: integer description: Number of tool sets assigned to this variation format: int32 subAgentCount: readOnly: true type: integer description: Number of sub-agents assigned to this variation format: int32 createdBy: $ref: '#/components/schemas/Profile' model: readOnly: true allOf: - $ref: '#/components/schemas/ResourceMetadata' description: Metadata for the model assigned to this variation score: type: number description: |- Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta). Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative. format: float feedbackCount: type: integer description: Total number of objective feedbacks received for this variation format: int32 memoryLayerCount: readOnly: true type: integer description: Count of memory layer assignments. format: int32 effectiveToolCount: readOnly: true type: integer description: |- Number of distinct callable tools available through this variation's assignments after normalization. Expands tool sets and deduplicates tools also assigned directly. Each sub-agent or pool contributes one callable tool; sub-agent assignments and pool members are not expanded. Counts the full normalized set, regardless of which tools progressive discovery has loaded. format: int32 assignmentMetadata: readOnly: true type: object additionalProperties: $ref: '#/components/schemas/BareMetadata' description: |- Current display metadata for targets explicitly referenced by spec.assignments and spec.memory_layer_assignments, keyed by canonical resource ID. Includes tools, tool sets, sub-agents, agent pools, and memory layers in one map; each value's id equals its key. Does not expand tools within assigned tool sets, assignments within sub-agents, or pool members. Populated whenever info is returned; empty when there are no assignments. Missing or inaccessible targets are omitted, and names may be absent. Clients use spec for assignment type/order and fall back to the ID when display metadata is unavailable. This map never accepts assignment writes. agentPoolCount: readOnly: true type: integer description: Number of agent pools assigned to this variation. format: int32 description: >- AgentVariationInfo provides read-only summary information about a variation AgentScheduleSpec: required: - schedule type: object properties: schedule: allOf: - $ref: '#/components/schemas/AgentScheduleSpec_Schedule' description: When to fire. Required. overlapPolicy: enum: - OVERLAP_POLICY_UNSPECIFIED - OVERLAP_POLICY_ALLOW - OVERLAP_POLICY_SKIP type: string description: >- What to do when the previous run is still in flight. Defaults to SKIP. format: enum firstUserMessage: type: string description: >- 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: example: agentvar_01HXKD2E5NQM3T9AYWCF32BSPP type: string description: >- Optional explicit variation. When unset, the agent's variation_selection_mode chooses per fire. systemPromptData: type: object description: >- 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. x-cadenyaapi-any: true firstUserMessageData: type: object description: >- 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. x-cadenyaapi-any: true description: AgentScheduleSpec is the user-provided configuration for a schedule. AgentScheduleInfo: required: - totalFires type: object properties: nextFireAt: readOnly: true type: string description: >- 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. format: date-time lastFireAt: readOnly: true type: string description: When the schedule last fired (regardless of objective outcome). format: date-time lastObjectiveId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: ID of the most recent objective the schedule created. lastSkippedAt: readOnly: true type: string description: >- When the schedule most recently skipped a fire (SKIP policy + prior in flight). format: date-time lastSkipReason: readOnly: true type: string description: >- Reason for the most recent skip (e.g. "previous objective still running"). totalFires: readOnly: true type: integer description: Lifetime count of objectives created by this schedule. format: int32 createdBy: $ref: '#/components/schemas/Profile' description: AgentScheduleInfo provides read-only runtime data about a schedule. AccountResourceMetadata: required: - id - accountId - name - profileId - externalId - labels type: object properties: id: readOnly: true type: string description: >- Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") accountId: readOnly: true example: account_01HXKD2E5NQM3T9AYWCFTJHJVF type: string description: >- Account this resource belongs to for multi-tenant isolation (prefixed ULID) name: type: string description: >- Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly externalId: type: string description: >- External ID for the resource (e.g., a workflow ID from an external system) labels: type: object additionalProperties: type: string description: |- 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: readOnly: true example: profile_01HXKD2E5NQM3T9AYWCFS0AP08 type: string createdAt: readOnly: true type: string format: date-time description: >- AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. ProfileSpec: required: - type - email - name type: object properties: email: type: string description: >- Email address of the profile. Required and unique within an account for user profiles. name: type: string description: Display name (e.g., "Bobby Tables"). type: enum: - PROFILE_TYPE_UNSPECIFIED - PROFILE_TYPE_USER - PROFILE_TYPE_API_KEY - PROFILE_TYPE_SYSTEM type: string description: >- Whether this profile represents a human user, an API key, or a system principal. format: enum description: Configuration for a profile. UserMessage: required: - content type: object properties: content: type: string ToolApprovalRequested: required: - toolCallId - llmToolName type: object properties: toolCallId: example: toolcall_01HXKD2E5NQM3T9AYWCFTANFGV type: string description: >- The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call. tool: allOf: - $ref: '#/components/schemas/CallableTool' description: The tool awaiting approval. llmToolName: type: string description: >- The name the model called the tool by, as it appears in the assistant message's toolCalls[].functionName. arguments: type: object additionalProperties: true description: The arguments the tool will be called with once approved. ToolApproved: required: - toolCallId - llmToolName type: object properties: toolCallId: example: toolcall_01HXKD2E5NQM3T9AYWCFTANFGV type: string description: >- The ID of the objective tool call record that was approved via the ApproveToolCall RPC. tool: allOf: - $ref: '#/components/schemas/CallableTool' description: The tool that was approved. llmToolName: type: string description: >- The name the model called the tool by, as it appears in the assistant message's toolCalls[].functionName. ToolDenied: required: - toolCallId - llmToolName - memo type: object properties: toolCallId: example: toolcall_01HXKD2E5NQM3T9AYWCFTANFGV type: string description: >- The ID of the objective tool call record that was denied via the DenyToolCall RPC. memo: type: string description: >- The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions. tool: allOf: - $ref: '#/components/schemas/CallableTool' description: The tool that was denied. llmToolName: type: string description: >- The name the model called the tool by, as it appears in the assistant message's toolCalls[].functionName. ToolCalled: required: - toolCallId - llmToolName type: object properties: toolCallId: example: toolcall_01HXKD2E5NQM3T9AYWCFTANFGV type: string description: The ID of the objective tool call record that was executed. tool: allOf: - $ref: '#/components/schemas/CallableTool' description: The tool that was called. config: allOf: - $ref: '#/components/schemas/ToolSpec_Config' description: |- The called tool's adapter configuration, including the bare adapter marker for bare tools. Lets a webhook consumer act on the call (e.g. detect a bare tool call and prepare to supply its content) without a round-trip to GetObjectiveToolCall. arguments: type: object additionalProperties: true description: The arguments passed to the tool. argumentsExposedInWidgets: readOnly: true type: boolean description: >- Whether the runtime authorized this call's arguments to be exposed in public widget events. This records the resolved policy at call time so consumers do not need to re-evaluate the tool set's current overlays. llmToolName: type: string description: >- The name the model called the tool by, as it appears in the assistant message's toolCalls[].functionName. It can differ from the tool's own name, which Cadenya sanitizes for the model. ObjectiveError: required: - type - message type: object properties: type: type: string message: type: string AssistantMessage: required: - toolCalls type: object properties: content: type: string toolCalls: type: array items: $ref: '#/components/schemas/AssistantToolCall' usage: readOnly: true allOf: - $ref: '#/components/schemas/TokenUsage' description: >- Token usage of the LLM completion that produced this message. Unset on messages recorded before usage was tracked per completion. model: readOnly: true allOf: - $ref: '#/components/schemas/ResourceMetadata' description: |- The model that produced this message, as resolved at call time. A variation's model can change while an objective runs, so the objective's config snapshot does not answer this on its own. completionId: readOnly: true type: string description: |- Identifies the LLM completion that produced this message. Streamed AssistantMessageDelta fragments carry the same value. Empty on messages recorded before completions were identified. ToolResult: required: - toolCallId - llmToolName - result type: object properties: toolCallId: example: toolcall_01HXKD2E5NQM3T9AYWCFTANFGV type: string result: allOf: - $ref: '#/components/schemas/ObjectiveToolCallResult' description: >- The content returned by the tool. Live streams carry it too, with media blocks as short-lived signed URLs, exactly as ListObjectiveEvents does. tool: allOf: - $ref: '#/components/schemas/CallableTool' description: The tool that returned the result. llmToolName: type: string description: >- The name the model called the tool by, as it appears in the assistant message's toolCalls[].functionName. ToolError: required: - toolCallId - llmToolName - message type: object properties: toolCallId: example: toolcall_01HXKD2E5NQM3T9AYWCFTANFGV type: string description: >- The ID of the objective tool call record that encountered an error during execution. message: type: string tool: allOf: - $ref: '#/components/schemas/CallableTool' description: The tool that failed. llmToolName: type: string description: >- The name the model called the tool by, as it appears in the assistant message's toolCalls[].functionName. ContextWindowCompacted: required: - strategies - messagesCompacted - newContextWindow type: object properties: newContextWindow: allOf: - $ref: '#/components/schemas/ObjectiveContextWindowData' description: The new context window created by this compaction strategies: type: array items: type: string description: The strategies that were applied during this compaction messagesCompacted: type: integer description: Number of messages that were compacted format: int32 summary: type: string description: The summary generated by the summarization strategy, if used. MemoryRead: required: - message - memoryLayerId - memoryEntryId type: object properties: message: type: string description: |- Human-readable description of the read, set by the runtime. For example: "Loaded skill", "Resolved context key". Not machine-parsed; intended for UI display alongside the other events in an objective's timeline. memoryLayerId: example: memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH type: string description: |- The layer the entry resolved to. The top-most layer that contained the key — other layers beneath it that also contained the key are shadowed and not referenced here. memoryEntryId: example: mementry_01HXKD2E5NQM3T9AYWCF5E52Z0 type: string description: The specific entry that was read. description: |- MemoryRead is emitted each time the agent resolves a key against the memory cascade and loads an entry. Lookups that miss (key not found in any layer) do not emit this event. ObjectiveCancelled: required: - message type: object properties: message: type: string description: >- Optional human-readable note recorded at cancel time. Today the workflow sets "Cancelled" but this field leaves room for richer reasons (e.g. "Cancelled by user", "Cancelled by schedule sweep", "Credit balance exhausted"). description: |- ObjectiveCancelled is the terminal event written when an objective is cancelled. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted. SubAgentSpawned: required: - task - agent - objective type: object properties: agent: $ref: '#/components/schemas/ResourceMetadata' objective: $ref: '#/components/schemas/OperationMetadata' task: type: string SubAgentUpdated: required: - status type: object properties: agent: $ref: '#/components/schemas/BareMetadata' objective: $ref: '#/components/schemas/BareMetadata' status: enum: - STATUS_UNSPECIFIED - STATUS_PENDING - STATUS_RUNNING - STATUS_COMPLETED - STATUS_FAILED - STATUS_CANCELLED - STATUS_WAITING - STATUS_TIMED_OUT type: string format: enum message: type: string ObjectiveFinalized: type: object properties: output: type: object description: |- If the objective was created with an output schema, and the agent successfully completed the objective, this field will contain the structured output of the objective. description: |- ObjectiveFinalized is the terminal event written when an objective is finalized. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted. Notice: required: - level - message - key type: object properties: level: enum: - LEVEL_UNSPECIFIED - LEVEL_INFO - LEVEL_WARN - LEVEL_INFO - LEVEL_WARN type: string format: enum message: type: string description: Human-readable description of what happened. key: type: string description: |- Stable machine-readable identifier for the notice kind (for example "tool_set_load_failed", "tool_archived"). Clients can switch on it or use it as an i18n key; the message is the English fallback. description: |- Notice is a non-terminal event emitted by the runtime when something noteworthy but non-fatal happens during an objective — for example a just-in-time tool set failing to load, or a previously loaded tool being dropped because it was archived. Notices carry no structured payload; they exist to make the objective timeline self-explanatory. ObjectiveTimedOut: required: - message type: object properties: message: type: string description: >- Human-readable note recorded at timeout time (e.g. "Timed out after 2h of inactivity"). description: |- ObjectiveTimedOut is the terminal event written when an objective is finalized by the inactivity sweep because it saw no activity (no user messages, no LLM calls) within its variation's inactivity timeout — or the system-wide 24 hour maximum when no timeout is configured. The objective produces no output. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted. Reasoning: required: - content type: object properties: content: type: string description: |- The reasoning text. May be a verbatim chain of thought or a provider-generated summary depending on the model. completionId: readOnly: true type: string description: |- Identifies the LLM completion that produced this reasoning. Streamed ReasoningDelta fragments carry the same value. Empty on reasoning recorded before completions were identified. description: >- Reasoning carries the human-readable reasoning text a model produced while working on an iteration — extended thinking (Anthropic, Gemini) or reasoning summaries (OpenAI). It is emitted alongside the assistant message from the same model response and is purely informational: the text shown here is never sent back to the model. ObjectiveStateChanged: required: - fromState - toState type: object properties: fromState: enum: - OBJECTIVE_STATE_UNSPECIFIED - OBJECTIVE_STATE_PENDING - OBJECTIVE_STATE_RUNNING - OBJECTIVE_STATE_WAITING - OBJECTIVE_STATE_FAILED - OBJECTIVE_STATE_CANCELLED - OBJECTIVE_STATE_FINALIZED - OBJECTIVE_STATE_TIMED_OUT - OBJECTIVE_STATE_INTERRUPTING - OBJECTIVE_STATE_UNSPECIFIED - OBJECTIVE_STATE_PENDING - OBJECTIVE_STATE_RUNNING - OBJECTIVE_STATE_WAITING - OBJECTIVE_STATE_FAILED - OBJECTIVE_STATE_CANCELLED - OBJECTIVE_STATE_FINALIZED - OBJECTIVE_STATE_TIMED_OUT type: string description: |- The state before this write. OBJECTIVE_STATE_UNSPECIFIED when the objective was just created. format: enum toState: enum: - OBJECTIVE_STATE_UNSPECIFIED - OBJECTIVE_STATE_PENDING - OBJECTIVE_STATE_RUNNING - OBJECTIVE_STATE_WAITING - OBJECTIVE_STATE_FAILED - OBJECTIVE_STATE_CANCELLED - OBJECTIVE_STATE_FINALIZED - OBJECTIVE_STATE_TIMED_OUT - OBJECTIVE_STATE_INTERRUPTING - OBJECTIVE_STATE_UNSPECIFIED - OBJECTIVE_STATE_PENDING - OBJECTIVE_STATE_RUNNING - OBJECTIVE_STATE_WAITING - OBJECTIVE_STATE_FAILED - OBJECTIVE_STATE_CANCELLED - OBJECTIVE_STATE_FINALIZED - OBJECTIVE_STATE_TIMED_OUT type: string description: The state after this write. format: enum message: type: string description: |- The status message recorded with the transition, if any (e.g. "Continued", or the error summary on a failure). description: >- ObjectiveStateChanged is written every time the objective's lifecycle state is set, including the initial move into OBJECTIVE_STATE_PENDING at creation. Terminal transitions also write their dedicated event (cancelled, timedOut, finalized, error) immediately before this one, so consumers that only care about the outcome can keep listening for those. ObjectiveHeartbeat: type: object properties: lastSequence: readOnly: true type: integer description: |- The objective's latest committed event sequence when the pulse was emitted. A stream that has not yet delivered this sequence is missing events and reads them from history. format: int32 description: |- ObjectiveHeartbeat reports recent execution liveness. It is transient: delivered only on live streams, never stored in event history or delivered to webhooks. Its hb_ event ID is not a reconnect cursor. Heartbeats do not change objective state or promise progress from the model. ObjectiveInterrupted: required: - message type: object properties: message: type: string description: >- ObjectiveInterrupted confirms that foreground execution stopped and the objective is waiting. AssistantMessageDelta: required: - completionId - text - afterSequence - offset type: object properties: completionId: type: string description: Identifies the LLM completion this fragment belongs to. text: type: string description: The text generated since the previous fragment for this completion. afterSequence: type: integer description: |- The objective's latest committed event sequence when the completion started. The fragment is delivered after the event with this sequence. format: int32 offset: type: integer description: >- Where this fragment starts within the completion's assistant text, in UTF-8 bytes. The first fragment of a completion has offset 0. format: int32 description: >- AssistantMessageDelta is a fragment of assistant text as the model generates it. It is transient: delivered only on live streams that opt in with includeDeltas, never stored in event history or delivered to webhooks, and its dlt_ event ID is not a reconnect cursor. A stream delivers a completion's fragments only when it can deliver all of them: it must receive the first fragment (offset 0), and once a fragment is missing it sends no more for that completion. A client that connects in the middle of a completion therefore sees no fragments for it and renders the durable AssistantMessage when it arrives. Fragments always arrive after the event whose sequence is after_sequence. Concatenate the fragments that share a completion_id in arrival order. The durable AssistantMessage that follows carries the same completion_id and is authoritative: replace the accumulated text with it. A retried completion gets a new completion_id, so drop fragments whose completion_id never receives a final message. ReasoningDelta: required: - completionId - text - afterSequence - offset type: object properties: completionId: type: string description: Identifies the LLM completion this fragment belongs to. text: type: string description: |- The reasoning text generated since the previous fragment for this completion. afterSequence: type: integer description: |- The objective's latest committed event sequence when the completion started. The fragment is delivered after the event with this sequence. format: int32 offset: type: integer description: >- Where this fragment starts within the completion's reasoning text, in UTF-8 bytes. The first fragment of a completion has offset 0. format: int32 description: >- ReasoningDelta is a fragment of reasoning text as the model generates it. It follows the same transient delivery rules as AssistantMessageDelta; the durable Reasoning event with the same completion_id is authoritative. AgentVariationSpec_ProgressiveDiscovery: type: object properties: maxTools: type: integer description: >- 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. format: int32 hints: type: array items: type: string description: >- 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. description: >- 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. AgentVariationSpec_Constraints: type: object properties: maxToolCalls: type: integer description: The maximum number of tool calls that can be made. 0 means no limit. format: int32 maxSubObjectives: type: integer description: >- The maximum number of sub-objectives that can be created. 0 means no limit. format: int32 inactivityTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: |- 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. SDKs represent this as a duration string, like AgentScheduleSpec.every, rather than an integer. AgentVariationSpec_ModelConfig: required: - modelId type: object properties: modelId: example: claude/opus-4.6 type: string description: >- The model identifier for the agent variation to use. Should be either the reference key (ai-provider.model-name) or the canonical model ID (e.g.: "model_ABC123") temperature: type: number description: |- Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness. Presence-tracked so a deliberate 0.0 (fully deterministic) is distinguishable from unset. format: float topP: type: number description: |- Nucleus sampling: only tokens comprising the top_p probability mass are considered. Requires the model's "topP" capability. format: float topK: type: integer description: |- Only sample from the top_k most likely tokens. Requires the model's "topK" capability. format: int32 stopSequences: type: array items: type: string description: |- Sequences that stop generation when produced. Empty means none. No count cap here — providers impose their own limits (surfaced as the "stopSequences" capability's `limit` on the model spec), and it is the caller's responsibility to stay within the selected model's limit. Requires the model's "stopSequences" capability. maxOutputTokens: type: integer description: |- Cap on output tokens per LLM call. Must not exceed the model's spec.max_output_tokens. Requires the model's "maxOutputTokens" capability. format: int32 reasoningEffort: enum: - REASONING_EFFORT_UNSPECIFIED - REASONING_EFFORT_NONE - REASONING_EFFORT_LOW - REASONING_EFFORT_MEDIUM - REASONING_EFFORT_HIGH type: string description: Reasoning effort. Requires the model's "reasoning" capability. format: enum cachingEnabled: type: boolean description: |- Prompt/token caching. Requires the model's "caching" capability. Presence-tracked tri-state: unset means the default — caching is ON whenever the model has the capability; false opts this variation out; true is an explicit opt-in (equivalent to unset). streamingEnabled: type: boolean description: |- Token streaming. Requires the model's "streaming" capability. Presence-tracked tri-state: unset means the default — completions stream whenever the model has the capability, so live streams that set includeDeltas receive text as it is generated; false opts this variation out (for example, for a provider credential that is not allowed to stream); true is an explicit opt-in (equivalent to unset). description: |- ModelConfig defines the model configuration for a variation. Every knob besides model_id is honored only when the assigned model's spec.capabilities lists the matching capability. AgentVariationSpec_CompactionConfig: type: object properties: triggerThreshold: type: number description: >- 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%) format: float summarization: allOf: - $ref: '#/components/schemas/CompactionConfig_SummarizationStrategy' description: >- Strategies — set one or more. When multiple are set, they execute in order: tool_result_clearing → summarization. When none are set, defaults to summarization with the system default prompt. toolResultClearing: $ref: '#/components/schemas/CompactionConfig_ToolResultClearingStrategy' description: >- CompactionConfig defines how context window compaction behaves for objectives using this variation. VariationAssignment: oneOf: - $ref: '#/components/schemas/VariationAssignment_ToolId' - $ref: '#/components/schemas/VariationAssignment_ToolSetId' - $ref: '#/components/schemas/VariationAssignment_SubAgentId' - $ref: '#/components/schemas/VariationAssignment_AgentPoolId' discriminator: propertyName: type mapping: toolId: '#/components/schemas/VariationAssignment_ToolId' toolSetId: '#/components/schemas/VariationAssignment_ToolSetId' subAgentId: '#/components/schemas/VariationAssignment_SubAgentId' agentPoolId: '#/components/schemas/VariationAssignment_AgentPoolId' description: >- A tool, tool set, sub-agent, or agent pool assigned to a variation, identified only by the target resource ID. The same shape is accepted in a spec and returned on reads. Assignment junction records are an internal implementation detail. VariationMemoryLayerAssignment: required: - memoryLayerId - position type: object properties: memoryLayerId: example: memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH minLength: 1 type: string description: |- Accepts the canonical memlyr_… ID or external_id: on input. Reads always return the canonical ID. position: type: integer description: >- Position is specificity: lower positions are consulted first; the highest position is the most general fallback. Gaps and zero are valid. Positions must be unique within a variation. Explicitly required in a full spec; only AddAgentVariationMemoryLayer can choose an append position for you. format: int32 description: >- A whole memory layer in a variation's baseline memory cascade. Identified by the memory layer ID; no assignment junction ID is exposed. Entry pinning remains an objective-level capability. AgentScheduleSpec_Schedule: type: object properties: calendars: type: array items: $ref: '#/components/schemas/Schedule_Calendar' description: Wall-clock rules. May be empty if `intervals` is non-empty. intervals: type: array items: $ref: '#/components/schemas/Schedule_Interval' description: Duration-based rules. May be empty if `calendars` is non-empty. timezone: type: string description: >- IANA tz name (e.g. "America/New_York"). Required. Applies to calendars; intervals fire on wall-clock cadence anchored in this zone. description: >- 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. CallableTool: oneOf: - $ref: '#/components/schemas/CallableTool_Tool' - $ref: '#/components/schemas/CallableTool_Agent' - $ref: '#/components/schemas/CallableTool_CadenyaProvidedTool' - $ref: '#/components/schemas/CallableTool_AgentPool' discriminator: propertyName: type mapping: tool: '#/components/schemas/CallableTool_Tool' agent: '#/components/schemas/CallableTool_Agent' cadenyaProvidedTool: '#/components/schemas/CallableTool_CadenyaProvidedTool' agentPool: '#/components/schemas/CallableTool_AgentPool' description: >- CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides). ToolSpec_Config: oneOf: - $ref: '#/components/schemas/ToolSpec_Config_Http' - $ref: '#/components/schemas/ToolSpec_Config_Mcp' - $ref: '#/components/schemas/ToolSpec_Config_Openapi' - $ref: '#/components/schemas/ToolSpec_Config_Bare' discriminator: propertyName: type mapping: http: '#/components/schemas/ToolSpec_Config_Http' mcp: '#/components/schemas/ToolSpec_Config_Mcp' openapi: '#/components/schemas/ToolSpec_Config_Openapi' bare: '#/components/schemas/ToolSpec_Config_Bare' description: |- 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. AssistantToolCall: required: - arguments - functionName type: object properties: tool: $ref: '#/components/schemas/CallableTool' arguments: type: string functionName: type: string toolCallId: readOnly: true example: toolcall_01HXKD2E5NQM3T9AYWCFTANFGV type: string description: >- The ID of the objective tool call record created for this call. Matches tool_call_id on the ToolCalled, ToolApprovalRequested, ToolResult and ToolError events that follow. Empty on assistant messages recorded before this field existed. TokenUsage: required: - inputTokens - outputTokens type: object properties: inputTokens: type: integer description: |- Total input tokens, including tokens read from or written to the provider's prompt cache. format: int32 cacheReadInputTokens: type: integer description: |- Input tokens served from the provider's prompt cache. Unset when the provider reported none or does not report them. format: int32 cacheWriteInputTokens: type: integer description: |- Input tokens written to the provider's prompt cache. Unset when the provider reported none or does not report them. format: int32 outputTokens: type: integer description: Total output tokens, including reasoning tokens. format: int32 reasoningOutputTokens: type: integer description: >- Output tokens spent on reasoning. Unset when the provider reported none or does not report them separately. format: int32 description: >- TokenUsage reports the tokens one LLM completion consumed, as the model's provider reported them. ObjectiveToolCallResult: required: - content type: object properties: content: readOnly: true type: array items: $ref: '#/components/schemas/ObjectiveToolCallResult_ContentBlock' description: |- The result content as recorded — which is what the model was shown. When a tool set overlay transformed the result (ToolOverlay result_actions), this is the transformed content; the adapter's raw response is kept in the tool call's debug log, not here. description: |- ObjectiveToolCallResult is the content a tool returned after execution. Tools can return multiple content blocks, and blocks can be multi-modal (text, image, audio). Media blocks are stored by Cadenya and served as short-lived signed URLs rather than inline bytes. ObjectiveContextWindowData: required: - objectiveId - sequence - promptTokens - completionTokens - previousWindowContinueInstructions type: object properties: objectiveId: readOnly: true example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string description: The objective's ID that this window belongs to sequence: readOnly: true type: integer description: >- sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order to calculate how many context windows an objective has. format: int32 promptTokens: readOnly: true type: integer description: >- A calculated value for how many prompt tokens (input tokens) have been used in this context window format: int32 completionTokens: readOnly: true type: integer description: >- A calculated value for how many completion tokens (output tokens) have been used in this context window format: int32 previousWindowContinueInstructions: type: string description: >- The instructions for this window to continue from a previous window's chat history. CompactionConfig_SummarizationStrategy: type: object properties: instructions: type: string description: |- Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." description: >- SummarizationStrategy configures LLM-powered summarization of older conversation turns. CompactionConfig_ToolResultClearingStrategy: type: object properties: preserveRecentResults: type: integer description: |- 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 format: int32 description: >- ToolResultClearingStrategy configures clearing of older tool result content. VariationAssignment_ToolId: type: object required: - type - toolId properties: type: type: string enum: - toolId toolId: minLength: 1 type: string description: Canonical tool ID. additionalProperties: false VariationAssignment_ToolSetId: type: object required: - type - toolSetId properties: type: type: string enum: - toolSetId toolSetId: minLength: 1 type: string description: Canonical tool set ID. additionalProperties: false VariationAssignment_SubAgentId: type: object required: - type - subAgentId properties: type: type: string enum: - subAgentId subAgentId: minLength: 1 type: string description: Canonical sub-agent ID. additionalProperties: false VariationAssignment_AgentPoolId: type: object required: - type - agentPoolId properties: type: type: string enum: - agentPoolId agentPoolId: minLength: 1 type: string description: >- Canonical agent pool ID. Attaches the pool as a single callable target. additionalProperties: false Schedule_Calendar: type: object properties: second: type: array items: $ref: '#/components/schemas/Schedule_Range' minute: type: array items: $ref: '#/components/schemas/Schedule_Range' hour: type: array items: $ref: '#/components/schemas/Schedule_Range' dayOfMonth: type: array items: $ref: '#/components/schemas/Schedule_Range' month: type: array items: $ref: '#/components/schemas/Schedule_Range' dayOfWeek: type: array items: $ref: '#/components/schemas/Schedule_Range' comment: type: string description: |- Calendar is a wall-clock rule. Empty field-list semantics: - second/minute/hour: empty means [{start: 0}] (top of the unit) - day_of_month/month/day_of_week: empty means "any value" Fire times = cartesian product across all fields. Schedule_Interval: type: object properties: every: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string offset: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: Phase shift within `every`. Must be < `every` (enforced at runtime). description: |- Interval is a duration-based rule. Fires every `every` from a stable anchor (workspace epoch), optionally phase-shifted by `offset`. CallableTool_Tool: type: object required: - type - tool properties: type: type: string enum: - tool tool: $ref: '#/components/schemas/ResourceMetadata' clientTool: readOnly: true type: boolean description: >- Whether the tool is a client tool: one the caller defined when creating the objective and executes itself, reporting each result with SetToolCallContent. CallableTool_Agent: type: object required: - type - agent properties: type: type: string enum: - agent agent: $ref: '#/components/schemas/ResourceMetadata' clientTool: readOnly: true type: boolean description: >- Whether the tool is a client tool: one the caller defined when creating the objective and executes itself, reporting each result with SetToolCallContent. CallableTool_CadenyaProvidedTool: type: object required: - type - cadenyaProvidedTool properties: type: type: string enum: - cadenyaProvidedTool cadenyaProvidedTool: $ref: '#/components/schemas/ResourceMetadata' clientTool: readOnly: true type: boolean description: >- Whether the tool is a client tool: one the caller defined when creating the objective and executes itself, reporting each result with SetToolCallContent. CallableTool_AgentPool: type: object required: - type - agentPool properties: type: type: string enum: - agentPool agentPool: allOf: - $ref: '#/components/schemas/ResourceMetadata' description: Agent pool responsible for routing this call to a member agent. clientTool: readOnly: true type: boolean description: >- Whether the tool is a client tool: one the caller defined when creating the objective and executes itself, reporting each result with SetToolCallContent. ToolSpec_Config_Http: type: object required: - type - http properties: type: type: string enum: - http http: $ref: '#/components/schemas/Config_HTTP' ToolSpec_Config_Mcp: type: object required: - type - mcp properties: type: type: string enum: - mcp mcp: $ref: '#/components/schemas/Config_MCP' ToolSpec_Config_Openapi: type: object required: - type - openapi properties: type: type: string enum: - openapi openapi: $ref: '#/components/schemas/Config_OpenAPI' ToolSpec_Config_Bare: type: object required: - type - bare properties: type: type: string enum: - bare bare: $ref: '#/components/schemas/Config_Bare' ObjectiveToolCallResult_ContentBlock: oneOf: - $ref: '#/components/schemas/ObjectiveToolCallResult_ContentBlock_Text' - $ref: '#/components/schemas/ObjectiveToolCallResult_ContentBlock_Image' - $ref: '#/components/schemas/ObjectiveToolCallResult_ContentBlock_Audio' discriminator: propertyName: type mapping: text: '#/components/schemas/ObjectiveToolCallResult_ContentBlock_Text' image: '#/components/schemas/ObjectiveToolCallResult_ContentBlock_Image' audio: '#/components/schemas/ObjectiveToolCallResult_ContentBlock_Audio' description: |- ContentBlock is a single block of tool result content. Exactly one of the variants is set. Schedule_Range: type: object properties: start: type: integer format: int32 end: type: integer format: int32 step: type: integer format: int32 description: |- Inclusive numeric range with optional step. {start: 9} → 9 {start: 9, end: 17} → 9..17 {start: 0, end: 59, step: 15} → 0,15,30,45 `end` defaults to `start`; `step` defaults to 1. Config_HTTP: required: - requestMethod type: object properties: requestMethod: enum: - HTTP_METHOD_UNSPECIFIED - GET - POST - PUT - PATCH - DELETE type: string format: enum path: type: string query: type: string headers: type: object additionalProperties: type: string requestBodyTemplate: type: string description: These are only used when the request method is a POST, PUT, or PATCH requestBodyContentType: type: string Config_MCP: type: object properties: annotations: allOf: - $ref: '#/components/schemas/MCP_Annotations' description: Tool behavior annotations from the MCP server, captured during sync. Config_OpenAPI: type: object properties: path: type: string method: type: string serverUrl: readOnly: true type: string description: >- The server URL this operation's requests are sent to when the tool set has no base_url, resolved from the spec on every sync: the operation's servers, else its path's, else the spec's top-level servers (the entry named by the tool set's server_name, else the first), with server variables set to their defaults and a relative URL resolved against the spec URL. A spec without servers resolves to the spec URL's origin. Empty when it cannot be resolved, such as a relative server in an uploaded spec. Set by sync. Config_Bare: type: object properties: alwaysSetResult: type: string description: |- When set, the tool call's result is recorded immediately as this fixed text instead of parking the call to wait for externally supplied content. The tool_called event is still emitted. Useful for tools whose dispatch is the intent (e.g. a frontend renders a component from the call parameters) but whose LLM turn still needs tool-result content. description: |- Marks the tool as bare: it has no execution adapter of its own and relies on the parent tool set being a Bare tool set. Present so a webhook consumer can tell a tool is bare from the tool data alone, without cross-referencing the tool set. ObjectiveToolCallResult_ContentBlock_Text: type: object required: - type - text properties: type: type: string enum: - text text: $ref: '#/components/schemas/ObjectiveToolCallResult_TextBlock' ObjectiveToolCallResult_ContentBlock_Image: type: object required: - type - image properties: type: type: string enum: - image image: $ref: '#/components/schemas/ObjectiveToolCallResult_ImageBlock' ObjectiveToolCallResult_ContentBlock_Audio: type: object required: - type - audio properties: type: type: string enum: - audio audio: $ref: '#/components/schemas/ObjectiveToolCallResult_AudioBlock' MCP_Annotations: type: object properties: title: type: string description: A human-readable title for the tool. readOnlyHint: type: boolean description: If true, the tool does not modify its environment. destructiveHint: type: boolean description: >- If true, the tool may perform destructive updates to its environment. Only meaningful when read_only_hint is false. idempotentHint: type: boolean description: |- If true, calling the tool repeatedly with the same arguments has no additional effect. Only meaningful when read_only_hint is false. openWorldHint: type: boolean description: |- If true, the tool may interact with an "open world" of external entities (e.g. web search); if false, its domain is closed. description: |- Behavior hints synced from the MCP server's tool definition (ToolAnnotations in the MCP specification). All hints are advisory: servers are not required to send them, and clients should not rely on them for security decisions. Absent hints keep the MCP spec defaults (destructiveHint and openWorldHint default to true; readOnlyHint and idempotentHint default to false). ObjectiveToolCallResult_TextBlock: required: - text type: object properties: text: readOnly: true type: string sizeBytes: readOnly: true type: string description: >- Size of the stored text in bytes. Filled by the server at record time; zero on results recorded before this field existed. ObjectiveToolCallResult_ImageBlock: required: - url - mimeType - sizeBytes - expiresAt type: object properties: url: readOnly: true type: string description: Short-lived signed URL to download the stored image. mimeType: readOnly: true type: string description: IANA media type of the stored image, e.g. image/png. sizeBytes: readOnly: true type: string description: Size of the stored image in bytes. expiresAt: readOnly: true type: string description: When the signed URL expires. format: date-time ObjectiveToolCallResult_AudioBlock: required: - url - mimeType - sizeBytes - expiresAt type: object properties: url: readOnly: true type: string description: Short-lived signed URL to download the stored audio. mimeType: readOnly: true type: string description: IANA media type of the stored audio, e.g. audio/wav. sizeBytes: readOnly: true type: string description: Size of the stored audio in bytes. expiresAt: readOnly: true type: string description: When the signed URL expires. format: date-time securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.