> ## 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. # List objective events > The full, immutable transcript of an objective: every message, tool call, and result, with the bodies the stream leaves out. Everything an objective did is an event. This endpoint is the durable record of them, in order, with nothing withheld. [Streaming](/docs/api-reference/objectiveeventstreamsservice/stream-objective-events) is how you watch an objective work. This is how you read what it did. ```typescript TypeScript theme={null} const events = await client.objectives.listEvents(objectiveId, { workspaceId }); for await (const event of events) { console.log(event.data?.type, event.contextWindowId); } // userMessage objwin_01KX18CRRNDHTFAHGA079765D9 // assistantMessage objwin_01KX18CRRNDHTFAHGA079765D9 // toolCalled objwin_01KX18CRRNDHTFAHGA079765D9 ``` ```go Go theme={null} events := client.Objectives.ListEventsAutoPaging(ctx, objectiveID, cadenya.ObjectiveListEventsParams{WorkspaceID: cadenya.String(workspaceID)}) for events.Next() { event := events.Current() fmt.Println(event.Data.Type, event.ContextWindowID) } // userMessage objwin_01KX18CRRNDHTFAHGA079765D9 // assistantMessage objwin_01KX18CRRNDHTFAHGA079765D9 // toolCalled objwin_01KX18CRRNDHTFAHGA079765D9 ``` ```ruby Ruby theme={null} events = cadenya.objectives.list_events(objective_id, workspace_id: workspace_id) events.auto_paging_each do |event| puts [event.data&.type, event.context_window_id].join(" ") end # userMessage objwin_01KX18CRRNDHTFAHGA079765D9 # assistantMessage objwin_01KX18CRRNDHTFAHGA079765D9 # toolCalled objwin_01KX18CRRNDHTFAHGA079765D9 ``` ```bash cURL theme={null} curl "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives/${OBJECTIVE_ID}/events" \ -H "Authorization: Bearer ${CADENYA_API_KEY}" ``` Events come back **oldest first**, which is what you want when rendering a transcript. Pass `sortOrder: 'desc'` for newest first. ## This is where tool result bodies live The stream strips `toolResult` and `toolError` down to a bare `toolCallId`, because a tool returning a megabyte of JSON would otherwise be pushed through every open connection. Here, the full body is attached. ```typescript theme={null} // From the stream: { "type": "toolResult", "toolResult": { "toolCallId": "toolcall_01KX19F3FMY79A8TNFNP6C9VRR" } } // The same event, from this endpoint: { "type": "toolResult", "toolResult": { "toolCallId": "toolcall_01KX19F3FMY79A8TNFNP6C9VRR", "result": { "content": [{ "type": "text", "text": { "text": "{\"options\":[...]}" } }] } } } ``` So the pattern for a live UI is: stream to render the timeline as it happens, then read events (or [Get a tool call](/docs/api-reference/objectiveservice/get-an-objective-tool-call-by-id)) when a user expands a result. ## Every event names its context window `contextWindowId` sits on each event, not inside `data`. On an objective that has [compacted](/docs/api-reference/objectiveservice/list-objective-context-windows), events before and after the compaction carry different window IDs, so you can group a transcript by window and show where the summary took over. ```typescript theme={null} const byWindow = new Map(); const events = await client.objectives.listEvents(objectiveId, { workspaceId }); for await (const event of events) { const id = event.contextWindowId ?? 'unknown'; byWindow.set(id, (byWindow.get(id) ?? 0) + 1); } console.log([...byWindow.entries()]); // [ [ 'objwin_01KX1G66RMB7ZKCN1543KY2G05', 6 ] ] ``` An objective that never filled its window reports a single ID, as above. One that compacted twice reports three, and the `contextWindowCompacted` events mark the boundaries. ## No event-type filter The endpoint takes `limit`, `cursor`, `sortOrder`, and `includeInfo`. There is no way to ask the server for only the `toolCalled` events, so filter on the client: ```typescript theme={null} const events = await client.objectives.listEvents(objectiveId, { workspaceId }); for await (const event of events) { if (event.data?.type !== 'toolApprovalRequested') continue; console.log(event.data.toolApprovalRequested.toolCallId); } ``` `limit` is a page size, not a cap. The SDK iterator pages transparently, so `limit: 10` fetches ten per request and still yields every event. Read `page.items` for exactly one page. `includeInfo: true` adds `info.createdBy`, the profile that caused the event. It costs more of your rate limit and tells you nothing about the agent's work, so skip it on a transcript render. ## The seventeen event types `data` is a discriminated union: `type` names the variant, and the payload sits under a key with the same name. `{ "type": "toolCalled", "toolCalled": {...} }`. | `type` | The variant | | ------------------------ | ------------------------------- | | `userMessage` | A turn from you | | `assistantMessage` | The agent's reply | | `toolCalled` | A tool invocation | | `toolResult` | What the tool returned | | `toolError` | The tool failed | | `toolApprovalRequested` | A call parked pending approval | | `toolApproved` | Someone approved it | | `toolDenied` | Someone denied it | | `memoryRead` | Defined, not observed firing | | `contextWindowCompacted` | Compaction ran | | `subAgentSpawned` | A sub-objective started | | `subAgentUpdated` | A sub-objective changed status | | `notice` | Informational | | `finalized` | Terminal: output produced | | `cancelled` | Terminal: a caller cancelled it | | `timedOut` | Terminal: inactivity timeout | | `error` | Terminal: it failed | `finalized.output` carries the objective's structured result, when its agent has an [`outputDefinition`](/docs/api-reference/agentservice/create-a-new-agent). Reading it from the event saves you a fetch. ## Events or diagnostics Both describe an objective after the fact, and they answer different questions. | Question | Endpoint | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | What did the agent do, in order? | This one | | What arguments did a tool get, and was it approved? | [List tool calls](/docs/api-reference/objectiveservice/list-objective-tool-calls) | | What did a tool return? | This one, or [Get a tool call](/docs/api-reference/objectiveservice/get-an-objective-tool-call-by-id) | | Where is the context window going? | [Diagnostics](/docs/api-reference/objectiveservice/get-objective-context-diagnostics), while the objective is live | | What did the run cost? | [Context windows](/docs/api-reference/objectiveservice/list-objective-context-windows) | ## Related The same events, live, with result bodies stripped. The same events, delivered to you, with retries. What `contextWindowId` refers to, and what each window cost. Where the first `userMessage` comes from. ## OpenAPI ````yaml get /v1/workspaces/{workspaceId}/objectives/{objectiveId}/events 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: get: tags: - ObjectiveService - Objectives summary: List objective events description: Lists all events for an objective operationId: ObjectiveService_ListObjectiveEvents parameters: - name: workspaceId in: path required: true schema: type: string example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q - name: objectiveId in: path description: Objective ID for filtering required: true schema: example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV type: string - name: limit in: query description: Maximum number of results to return schema: type: integer format: int32 - name: cursor in: query description: Pagination cursor from previous response schema: type: string - name: sortOrder in: query description: Sort order for results (asc or desc by creation time) schema: type: string - name: includeInfo in: query description: When set to true you may use more of your alloted API rate-limit schema: type: boolean - name: windowId in: query description: Optional context window ID to filter events by schema: type: string - name: sinceEventId in: query description: Optional string to fetch events since an ID schema: type: string - name: labels in: query description: |- Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics). schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListObjectiveEventsResponse' 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 }); // Automatically fetches more pages as needed. for await (const objectiveEvent of client.objectives.listEvents('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 ) page = client.objectives.list_events( objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV", workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q", ) page = page.items[0] print(page.data) - 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\tpage, err := client.Objectives.ListEvents(\n\t\tcontext.TODO(),\n\t\t\"obj_01HXKD2E5NQM3T9AYWCFQAZGFV\",\n\t\tcadenya.ObjectiveListEventsParams{\n\t\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n" - lang: Ruby source: |- require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") page = cadenya.objectives.list_events( "obj_01HXKD2E5NQM3T9AYWCFQAZGFV", workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q" ) puts(page) - lang: CLI source: |- cadenya objectives list-events \ --api-key 'My API Key' \ --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \ --objective-id obj_01HXKD2E5NQM3T9AYWCFQAZGFV components: schemas: ListObjectiveEventsResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/ObjectiveEvent' pagination: $ref: '#/components/schemas/Page' 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). 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 Page: type: object properties: nextCursor: type: string description: >- Page carries cursor-based pagination state. There is no total: the cursor walks the result set without ever counting it, and a count would cost a second query on every list. 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. 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' 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 ````