--- title: "Update Session" method: PATCH path: "/workspaces/{workspace_id}/agent/sessions/{session_id}" tags: ["agent-sessions"] --- # Update Session `PATCH /workspaces/{workspace_id}/agent/sessions/{session_id}` ## Request - Base URL: `https://platform.tracecat.com/api` - URL: `https://platform.tracecat.com/api/workspaces/{workspace_id}/agent/sessions/{session_id}` - Auth: one of: - API key in cookie `fastapiusersauth` - HTTP bearer Update session properties. ## Path parameters - `session_id` string, uuid, required - `workspace_id` string, uuid, required ## Request body - AgentSessionUpdate: Request schema for updating an agent session. - `title` string, nullable: Session title - `tools` string[], nullable: Extra tools added to this session alongside entity defaults - `mcp_integrations` string[], nullable: MCP integration IDs attached to this session - `agent_preset_id` string, uuid, nullable: Agent preset to use for this session - `agent_preset_version_id` string, uuid, nullable: Pinned preset version to use for this session. Set null to follow the preset's current version. - `backend_id` string, nullable: Immutable agent backend identifier - `harness_type` string, nullable: Immutable execution harness ## Response `200` Successful Response - AgentSessionRead: Response schema for agent session. - `id` string, uuid, required - `workspace_id` string, uuid, required - `title` string, required - `created_by` string, uuid, nullable, required - `is_readonly` boolean: Whether the requesting actor can modify this session - `entity_type` 'case' | 'agent_preset' | 'agent_preset_builder' | 'copilot' | 'workflow' | 'approval' | 'external_channel', required: The type of entity associated with an agent session. Determines the context and behavior of the session: - CASE: Chat attached to a Case entity for investigation - AGENT_PRESET: Live chat testing a preset configuration - AGENT_PRESET_BUILDER: Builder chat for editing/configuring a preset - WORKSPACE_CHAT: Workspace-level chat assistant (wire value: copilot) - WORKFLOW: Workflow-initiated agent run (from action) - APPROVAL: Inbox approval continuation (hidden from main chat list) - EXTERNAL_CHANNEL: External channel session (e.g. Slack thread) - `entity_id` string, uuid, required - `channel_context` object, nullable, required - `tools` string[], nullable, required - `mcp_integrations` string[], nullable, required - `agent_preset_id` string, uuid, nullable, required - `agent_preset_version_id` string, uuid, nullable, required - `agents_binding` ResolvedAgentsConfig: Persisted immutable resolved child refs. - `enabled` boolean - `subagents` ResolvedAttachedSubagentRef[] - `preset` string, required - `preset_version` integer, nullable - `name` string, nullable - `description` string, nullable - `max_turns` integer, nullable - `preset_id` string, uuid, required - `preset_version_id` string, uuid, required - `backend_id` string - `capabilities` AgentSessionCapabilities: Optional controls the session's backend supports. - `steering` boolean: Whether a running turn accepts steering messages - `withdrawing` boolean: Whether a running turn can take back pending user messages - `listing_pending` boolean: Whether the session can list messages the model has not read - `harness_type` string, nullable, required - `last_error` string, nullable - `last_stream_id` string, nullable - `artifacts` Artifact[] - union - CaseArtifact: Case artifact shown in artifact-capable chat surfaces. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'case' - `severity` 'unknown' | 'informational' | 'low' | 'medium' | 'high' | 'critical' | 'fatal' | 'other', required: Case severity values aligned with OCSF severity values. Values: UNKNOWN (0): The event/finding severity is unknown INFORMATIONAL (1): Informational message. No action required LOW (2): The user decides if action is needed MEDIUM (3): Action is required but the situation is not serious at this time HIGH (4): Action is required immediately CRITICAL (5): Action is required immediately and the scope is broad FATAL (6): An error occurred but it is too late to take remedial action OTHER (99): The event/finding severity is not mapped - `status` 'unknown' | 'new' | 'in_progress' | 'on_hold' | 'resolved' | 'closed' | 'other', required: Case status values aligned with OCSF Incident Finding status. - WorkflowArtifact: Workflow artifact shown in artifact-capable chat surfaces. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'workflow' - `color` string, required - `isPublished` boolean, nullable - RunArtifact: Workflow run artifact shown in artifact-capable chat surfaces. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'run' - `workflowId` string, required - `status` 'running' | 'success' | 'failed' | 'cancelled', required - `startedAt` string, date-time, required - TableArtifact: Table artifact shown in artifact-capable chat surfaces. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'table' - `rowCount` integer, nullable - AgentArtifact: Agent preset artifact shown in artifact-capable chat surfaces. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'agent' - FormArtifact: Workflow form artifact. Lets a surface refresh a form the chat edited. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'form' - `status` 'online' | 'offline', nullable - AlertArtifact: Alert artifact stub. Extend when alert surfaces are wired. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'alert' - IntegrationArtifact: Integration artifact stub. Extend when integration surfaces are wired. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'integration' - SecretArtifact: Secret artifact stub. Extend when secret surfaces are wired. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'secret' - GenericArtifact: Escape hatch for surfaced objects without a dedicated panel view. - `id` string, required - `title` string, required - `scope` ArtifactScope: Attribution scope for artifact data parts. - `agentId` string, nullable - `agentType` string, nullable - `parentToolCallId` string, nullable - `type` 'generic' - `data` object, nullable - `parent_session_id` string, uuid, nullable - `spawned_by_session_id` string, uuid, nullable - `forked_from_session_id` string, uuid, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/tracecat/apis/tracecat-api.md) - [All operations](https://skmtc.dev/tracecat/apis/tracecat-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tracecat/apis/tracecat-api/revisions/2efdda25045f?raw)