> ## 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. # Stream objective events > Watch an objective work in real time over server-sent events: every message, tool call, and approval request as it happens. An objective runs in the background. This endpoint is how you watch it: a server-sent event stream that pushes each event the moment it lands, so you can render a live transcript instead of polling. The endpoint takes no query parameters. Connect, and you get events from now forward. ## Read the stream The SDKs hand you an iterator and skip the transport bookkeeping. ```typescript TypeScript theme={null} const stream = await client.objectives.streamEvents(objective.metadata.id, { workspaceId }); events: for await (const event of stream) { const data = event.data; switch (data.type) { case 'assistantMessage': process.stdout.write(data.assistantMessage.content ?? ''); break; case 'toolCalled': { // CallableTool is a union. Its type field names the variant. const called = data.toolCalled.tool; const name = called?.type === 'tool' ? called.tool.name : // a tool from a tool set called?.type === 'agent' ? called.agent.name : // a sub-agent '(built-in)'; // get_memory, tool_search: name arrives blank console.log('calling', name, data.toolCalled.arguments); break; } case 'finalized': case 'cancelled': case 'timedOut': case 'error': break events; } } ``` ```go Go theme={null} stream := client.Objectives.StreamEventsStreaming(ctx, objectiveID, cadenya.ObjectiveStreamEventsParams{WorkspaceID: cadenya.String(workspaceID)}) defer stream.Close() for stream.Next() { event := stream.Current() switch data := event.Data.AsAny().(type) { case cadenya.ObjectiveEventDataAssistantMessage: fmt.Print(data.AssistantMessage.Content) case cadenya.ObjectiveEventDataToolCalled: fmt.Println("tool called", data.ToolCalled.ToolCallID) case cadenya.ObjectiveEventDataError: log.Fatal(data.Error.Message) case cadenya.ObjectiveEventDataFinalized, cadenya.ObjectiveEventDataCancelled, cadenya.ObjectiveEventDataTimedOut: return } } if err := stream.Err(); err != nil { log.Fatal(err) } ``` ```ruby Ruby theme={null} stream = cadenya.objectives.stream_events(objective.metadata.id, workspace_id: workspace_id) stream.each do |event| case event.data&.type when :assistantMessage print event.data.assistant_message&.content when :toolCalled # CallableTool is a union. Built-ins (get_memory, tool_search) arrive with a blank name. called = event.data.tool_called&.tool name = called&.tool&.name || called&.agent&.name || "(built-in)" puts "calling #{name} #{event.data.tool_called&.arguments}" when :finalized, :cancelled, :timedOut, :error break # break aborts the underlying request for you end end ``` ```bash cURL theme={null} curl -N "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives/${OBJECTIVE_ID}/events:stream" \ -H "Authorization: Bearer ${CADENYA_API_KEY}" \ -H "Accept: text/event-stream" # event: open # data: {"time":"2026-07-08T16:34:20Z"} # # id: objevt_01KX19974R5KKN6P0VFFXHQK3A # event: assistantMessage # data: {"metadata":{...},"data":{"type":"assistantMessage",...}} ``` In TypeScript, `ObjectiveEvent.data` is a discriminated union. Each `case` narrows `data` to the matching event interface, so the corresponding payload is available without a cast. **The stream never closes on its own.** Reaching `STATE_FINALIZED` does not end the connection. It stays open, emitting a `ping` every 15 seconds, until the load balancer severs it at 10 minutes. Break on the terminal event type, never on end-of-stream. A loop with no `break` holds a connection for ten minutes after the objective finishes, and a client that reconnects whenever the stream ends reconnects forever on a completed objective. ## What arrives on the wire Each event frame carries three SSE fields: `id` is the event's ULID, `event` is the event type (`assistantMessage`, `toolCalled`, ...), and `data` is the JSON [ObjectiveEvent](/docs/api-reference/objectiveservice/list-objective-events). Two control frames carry no `id` and are not objective events: * `open`, once, when the stream commits. Its arrival means the connection is live and the status code is settled. * `ping`, every 15 seconds, to keep intermediaries from closing an idle connection. The SDKs drop `open` and `ping` before they reach your loop. If you read the raw stream, skip them yourself: they do not parse as an `ObjectiveEvent`. ## Tool results are stripped This is the one surprise worth internalizing. On the stream, `toolResult` and `toolError` events carry **only** the `toolCallId`. The content is cleared, because a tool that returns a megabyte of JSON would otherwise push it through every open connection. ```json Streamed theme={null} { "type": "toolResult", "toolResult": { "toolCallId": "toolcall_01KX19F3FMY79A8TNFNP6C9VRR" } } ``` ```json Same event from listEvents theme={null} { "type": "toolResult", "toolResult": { "toolCallId": "toolcall_01KX19F3FMY79A8TNFNP6C9VRR", "result": { "content": [{ "type": "text", "text": { "text": "{\"options\":[...]}" } }] } } } ``` Every other event type passes through whole. When you need a result body, fetch the call by ID with [Get a tool call](/docs/api-reference/objectiveservice/get-an-objective-tool-call-by-id), which returns `result` at the top level, or read the event back from [List objective events](/docs/api-reference/objectiveservice/list-objective-events). ## Built-in tool calls arrive unnamed `toolCalled.tool` is a discriminated union: its `type` field reads `tool` for a tool from a tool set, `agent` for a [sub-agent](/docs/guides/delegate-to-sub-agents), or `cadenyaProvidedTool` for a built-in such as `get_memory` or `tool_search`, and the payload sits under the matching key. Switch on `type`, never reach through `tool.tool`. The built-in case carries an opaque `cpt_...` id and an **empty `name`**. `arguments` tells you what it did (`{"memoryKey": "policies/us/refunds"}`), and [Get a tool call](/docs/api-reference/objectiveservice/get-an-objective-tool-call-by-id) returns the same call with `callable.cadenyaProvidedTool.name` filled in. ## Resume where you left off Send the SSE `Last-Event-ID` header with the last event ULID you processed. Cadenya replays the gap from durable storage, then switches you to the live feed, deduplicating the overlap. Omit the header and you get events from now, with no replay of anything the objective already emitted. ```typescript TypeScript theme={null} let lastEventId: string | undefined; streaming: while (true) { const stream = await client.objectives.streamEvents(objectiveId, { workspaceId, }, { headers: lastEventId ? { 'Last-Event-ID': lastEventId } : undefined, }); for await (const event of stream) { lastEventId = event.metadata.id; // remember before you handle it if (isTerminal(event.data.type)) break streaming; handle(event); } // Fell out of the loop without a terminal event: the connection dropped. // Reconnect from lastEventId. Nothing is lost. } ``` ```bash cURL theme={null} curl -N "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives/${OBJECTIVE_ID}/events:stream" \ -H "Authorization: Bearer ${CADENYA_API_KEY}" \ -H "Accept: text/event-stream" \ -H "Last-Event-ID: objevt_01KX1993PV6MHJ10BS2VS01FM8" ``` Neither SDK reconnects for you, and neither tracks the last event ID. The loop above is the pattern to copy. A single connection lives at most 10 minutes by design, so any objective that runs longer **requires** this reconnect loop. An unusable `Last-Event-ID` fails before the stream commits, so it comes back as a real HTTP status rather than a mid-stream error. Once `open` arrives the status is committed, and any later failure ends the connection with no status to read. ## Every event type Eighteen types. `data` is a discriminated union: `type` names the variant, and the payload sits under a key with the same name. | `type` | Meaning | | ------------------------ | ------------------------------------------------------------------------------ | | `userMessage` | A turn from you, including the first one. | | `assistantMessage` | The agent said something. | | `reasoning` | A model exposed reasoning text or a provider-generated reasoning summary. | | `toolCalled` | The agent invoked a tool. | | `toolResult` | The tool returned. Stripped on the stream. | | `toolError` | The tool failed. Stripped on the stream. | | `toolApprovalRequested` | Work is parked pending [approval](/docs/guides/callbacks/approving-a-tool). | | `toolApproved` | Someone approved the call. | | `toolDenied` | Someone denied it. | | `memoryRead` | Defined, but not observed firing. A `get_memory` call arrives as `toolCalled`. | | `contextWindowCompacted` | The window filled and [compaction](/docs/guides/objectives#context-windows) ran. | | `subAgentSpawned` | The agent [delegated](/docs/guides/delegate-to-sub-agents) to a sub-objective. | | `subAgentUpdated` | A sub-objective changed status. | | `notice` | Informational. | | `finalized` | Terminal. The objective produced its output. | | `cancelled` | Terminal. A caller cancelled it. | | `timedOut` | Terminal. It hit the inactivity timeout. | | `error` | Terminal. It failed. | The four terminal types are the ones your loop must watch for. An objective that answers and waits for your next turn never emits a terminal event. It sits in `STATE_WAITING`, and the stream stays open. Break on the last `assistantMessage` when you are driving a conversation rather than waiting on an output. ## Streaming or webhooks Both carry the same events. They fail differently, and that is how you choose. **Stream** when a human is watching: a chat UI, a live transcript, a progress log. It is a live tail with no delivery guarantee beyond the `Last-Event-ID` resume path, and it needs a process holding a connection open. **[Webhook](/docs/guides/webhooks)** when a machine is reacting: kicking off a job, writing to a database, paging someone. Deliveries retry, and each one records its status, attempt count, and response, so you can audit what your endpoint received. Reach for both on the same objective when a person watches the work while a system records it. ## OpenAPI ````yaml get /v1/workspaces/{workspaceId}/objectives/{objectiveId}/events: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 a workspace's API keys. Every key belongs to exactly one workspace; the system-managed global account key is managed via GlobalAPIKeyService instead. - name: AccountService description: >- Manage the authenticated account. Accounts are the top-level organizational unit and contain one or more workspaces. - 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, and memory layer assignments. - name: GlobalAPIKeyService description: |- Manage the account's system-provisioned global API key. The global key is the only key that spans every workspace; it is created by the system and cannot be deleted, so the surface is retrieve, rotate, and the disable/enable kill switch. - 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. - 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: 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/{objectiveId}/events:stream: get: tags: - ObjectiveEventStreamsService - Objectives summary: Stream objective events description: >- Streams events for an objective in real-time using server-sent events (SSE) operationId: ObjectiveEventStreamsService_StreamObjectiveEvents parameters: - name: workspaceId in: path required: true schema: type: string example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q - name: objectiveId in: path required: true schema: example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string responses: '200': description: A stream of Server-Sent Events content: text/event-stream: schema: $ref: '#/components/schemas/ObjectiveEvent' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' x-codeSamples: - lang: JavaScript source: >- import Cadenya from '@cadenya/cadenya'; const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted }); const objectiveEvent = await client.objectives.streamEvents('obj_01HXKD2E5NQM3T9AYWCFQAZGFV', { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q', }); console.log(objectiveEvent.data); - lang: Python source: |- import os from cadenya import Cadenya client = Cadenya( api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted ) for objective in client.objectives.stream_events( objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV", workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q", ): print(objective) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"go.cadenya.com/cadenya-go\"\n\t\"go.cadenya.com/cadenya-go/option\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tstream := client.Objectives.StreamEventsStreaming(\n\t\tcontext.TODO(),\n\t\t\"obj_01HXKD2E5NQM3T9AYWCFQAZGFV\",\n\t\tcadenya.ObjectiveStreamEventsParams{\n\t\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t\t},\n\t)\n\tfor stream.Next() {\n\t\tfmt.Printf(\"%+v\\n\", stream.Current())\n\t}\n\terr := stream.Err()\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n" - lang: Ruby source: |- require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") objective_event = cadenya.objectives.stream_events( "obj_01HXKD2E5NQM3T9AYWCFQAZGFV", workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q" ) puts(objective_event) - lang: CLI source: |- cadenya objectives stream-events \ --api-key 'My API Key' \ --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \ --objective-id obj_01HXKD2E5NQM3T9AYWCFQAZGFV components: schemas: ObjectiveEvent: required: - metadata - data type: object properties: metadata: $ref: '#/components/schemas/OperationMetadata' 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 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: $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). OperationMetadata: required: - id - accountId - workspaceId - profileId - createdAt 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) 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' discriminator: propertyName: type mapping: userMessage: $ref: '#/components/schemas/ObjectiveEventData_UserMessage' toolApprovalRequested: $ref: '#/components/schemas/ObjectiveEventData_ToolApprovalRequested' toolApproved: $ref: '#/components/schemas/ObjectiveEventData_ToolApproved' toolDenied: $ref: '#/components/schemas/ObjectiveEventData_ToolDenied' toolCalled: $ref: '#/components/schemas/ObjectiveEventData_ToolCalled' error: $ref: '#/components/schemas/ObjectiveEventData_Error' assistantMessage: $ref: '#/components/schemas/ObjectiveEventData_AssistantMessage' toolResult: $ref: '#/components/schemas/ObjectiveEventData_ToolResult' toolError: $ref: '#/components/schemas/ObjectiveEventData_ToolError' contextWindowCompacted: $ref: '#/components/schemas/ObjectiveEventData_ContextWindowCompacted' memoryRead: $ref: '#/components/schemas/ObjectiveEventData_MemoryRead' cancelled: $ref: '#/components/schemas/ObjectiveEventData_Cancelled' subAgentSpawned: $ref: '#/components/schemas/ObjectiveEventData_SubAgentSpawned' subAgentUpdated: $ref: '#/components/schemas/ObjectiveEventData_SubAgentUpdated' finalized: $ref: '#/components/schemas/ObjectiveEventData_Finalized' notice: $ref: '#/components/schemas/ObjectiveEventData_Notice' timedOut: $ref: '#/components/schemas/ObjectiveEventData_TimedOut' ObjectiveEventInfo: type: object properties: objective: $ref: '#/components/schemas/OperationMetadata' createdBy: $ref: '#/components/schemas/Profile' 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. 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' 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. UserMessage: type: object properties: content: type: string ToolApprovalRequested: 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. ToolApproved: 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. ToolDenied: 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. ToolCalled: 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. ObjectiveError: type: object properties: type: type: string message: type: string AssistantMessage: type: object properties: content: type: string toolCalls: type: array items: $ref: '#/components/schemas/AssistantToolCall' ToolResult: required: - toolCallId - result type: object properties: toolCallId: example: toolcall_01HXKD2E5NQM3T9AYWCFTANFGV type: string result: allOf: - $ref: '#/components/schemas/ObjectiveToolCallResult' description: The content returned by the tool. ToolError: 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 ContextWindowCompacted: 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: 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: 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: type: object properties: agent: $ref: '#/components/schemas/ResourceMetadata' objective: $ref: '#/components/schemas/OperationMetadata' task: type: string SubAgentUpdated: 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 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: 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 diagnostic 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: 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. AccountResourceMetadata: required: - id - accountId - name - profileId 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 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. CallableTool: oneOf: - $ref: '#/components/schemas/CallableTool_Tool' - $ref: '#/components/schemas/CallableTool_Agent' - $ref: '#/components/schemas/CallableTool_CadenyaProvidedTool' discriminator: propertyName: type mapping: tool: $ref: '#/components/schemas/CallableTool_Tool' agent: $ref: '#/components/schemas/CallableTool_Agent' cadenyaProvidedTool: $ref: '#/components/schemas/CallableTool_CadenyaProvidedTool' 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: $ref: '#/components/schemas/ToolSpec_Config_Http' mcp: $ref: '#/components/schemas/ToolSpec_Config_Mcp' openapi: $ref: '#/components/schemas/ToolSpec_Config_Openapi' bare: $ref: '#/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: type: object properties: tool: $ref: '#/components/schemas/CallableTool' arguments: type: string functionName: type: string ObjectiveToolCallResult: required: - content type: object properties: content: readOnly: true type: array items: $ref: '#/components/schemas/ObjectiveToolCallResult_ContentBlock' 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: 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. ResourceMetadata: required: - id - accountId - workspaceId - name - profileId - createdAt 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) BareMetadata: 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 (e.g., objective tasks). 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 tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. CallableTool_Tool: type: object required: - type - tool properties: type: type: string enum: - tool tool: $ref: '#/components/schemas/ResourceMetadata' CallableTool_Agent: type: object required: - type - agent properties: type: type: string enum: - agent agent: $ref: '#/components/schemas/ResourceMetadata' CallableTool_CadenyaProvidedTool: type: object required: - type - cadenyaProvidedTool properties: type: type: string enum: - cadenyaProvidedTool cadenyaProvidedTool: $ref: '#/components/schemas/ResourceMetadata' 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: $ref: '#/components/schemas/ObjectiveToolCallResult_ContentBlock_Text' image: $ref: '#/components/schemas/ObjectiveToolCallResult_ContentBlock_Image' audio: $ref: '#/components/schemas/ObjectiveToolCallResult_ContentBlock_Audio' description: |- ContentBlock is a single block of tool result content. Exactly one of the variants is set. 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 Config_Bare: type: object properties: {} 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. x-stainless-empty-object: true 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 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 ````