TRtracecat
agent-sessions

Create Session

Create a new agent session associated with an entity.

post/workspaces/{workspace_id}/agent/sessions

Request

  • Base URL
    https://platform.tracecat.com/api
  • Auth
    • API key in cookie fastapiusersauth
    • or HTTP bearer

Path parameters

workspace_idstring uuid required

Request body

idstring uuid nullable

Session ID. If not provided, service generates one.

spawned_by_session_idstring uuid nullable

Session that spawned this fresh child

titlestring

Human-readable title for the session

created_bystring uuid nullable

User who created 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_idstring uuid required

ID of the associated entity

toolsstring[] nullable

Extra tools added to this session alongside entity defaults

mcp_integrationsstring[] nullable

MCP integration IDs attached to this session

agent_preset_idstring uuid nullable

Agent preset used for this session (if any)

agent_preset_version_idstring uuid nullable

Pinned preset version used for this session. If null, the session follows the preset's current version.

backend_idstring

Opaque agent backend identifier

harness_typestring nullable

Execution harness; defaults to the selected backend's harness

Response

Successful Response

idstring uuid required
workspace_idstring uuid required
titlestring required
created_bystring uuid nullable required
is_readonlyboolean

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_idstring uuid required
channel_contextobject nullable required
toolsstring[] nullable required
mcp_integrationsstring[] nullable required
agent_preset_idstring uuid nullable required
agent_preset_version_idstring uuid nullable required
backend_idstring
harness_typestring nullable required
last_errorstring nullable
last_stream_idstring nullable
parent_session_idstring uuid nullable
spawned_by_session_idstring uuid nullable
forked_from_session_idstring uuid nullable
created_atstring date-time required
updated_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.