Skip to main content
POST
/
workspaces
/
{workspace_id}
/
agent
/
sessions
Error
A valid request URL is required to generate request examples
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "title": "<string>",
  "created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "channel_context": {},
  "tools": [
    "<string>"
  ],
  "mcp_integrations": [
    "<string>"
  ],
  "agent_preset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_preset_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "harness_type": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "agents_binding": {
    "enabled": false,
    "subagents": [
      {
        "preset": "<string>",
        "preset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "preset_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "preset_version": 2,
        "name": "<string>",
        "description": "<string>",
        "max_turns": 2
      }
    ]
  },
  "last_error": "<string>",
  "last_stream_id": "<string>",
  "artifacts": [
    {
      "id": "<string>",
      "title": "<string>",
      "scope": {
        "agentId": "<string>",
        "agentType": "<string>",
        "parentToolCallId": "<string>"
      },
      "type": "case"
    }
  ],
  "parent_session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

​
fastapiusersauth
string
cookie
required

Path Parameters

​
workspace_id
string<uuid>
required

Body

application/json

Request schema for creating an agent session.

​
entity_type
enum<string>
required

Type of entity this session is associated with

Available options:
case,
agent_preset,
agent_preset_builder,
copilot,
workflow,
approval,
external_channel
​
entity_id
string<uuid>
required

ID of the associated entity

​
id
string<uuid> | null

Session ID. If not provided, service generates one.

​
title
string
default:New Chat

Human-readable title for the session

Required string length: 1 - 200
​
created_by
string<uuid> | null

User who created this session

​
tools
string[] | null

Extra tools added to this session alongside entity defaults

Maximum array length: 50
​
mcp_integrations
string[] | null

MCP integration IDs attached to this session

Maximum array length: 50
​
agent_preset_id
string<uuid> | null

Agent preset used for this session (if any)

​
agent_preset_version_id
string<uuid> | null

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

​
harness_type
enum<string>
default:claude_code

Agent harness type

Available options:
pydantic-ai,
claude_code

Response

Successful Response

Response schema for agent session.

​
id
string<uuid>
required
​
workspace_id
string<uuid>
required
​
title
string
required
​
created_by
string<uuid> | null
required
​
entity_type
enum<string>
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)
Available options:
case,
agent_preset,
agent_preset_builder,
copilot,
workflow,
approval,
external_channel
​
entity_id
string<uuid>
required
​
channel_context
Channel Context · object | null
required
​
tools
string[] | null
required
​
mcp_integrations
string[] | null
required
​
agent_preset_id
string<uuid> | null
required
​
agent_preset_version_id
string<uuid> | null
required
​
harness_type
string | null
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
agents_binding
ResolvedAgentsConfig · object | null

Persisted agents toggle with immutable resolved child refs.

​
last_error
string | null
​
last_stream_id
string | null
​
artifacts
(CaseArtifact · object | WorkflowArtifact · object | RunArtifact · object | TableArtifact · object | AgentArtifact · object | AlertArtifact · object | IntegrationArtifact · object | SecretArtifact · object | GenericArtifact · object)[]

Case artifact shown in artifact-capable chat surfaces.

​
parent_session_id
string<uuid> | null