Skip to main content
POST
Error

Authorizations

X-API-Key
string
header
required

Headers

customer
string
required

Workspace identifier

Body

application/json
project_id
string
required
ai_model
string | null

Model to answer this chat with, instead of the project's.

branch_id
string | null
messages
object[]

The opening turn. Each message is { "role": "user", "content": "…" }; given, the agent starts answering as soon as the chat exists. Omitted, the chat is created idle and POST /ai/agents/{id}/messages starts it.

title
string
trigger_info
object

The caller's own labels for the chat, kept on it as sent. api_key_id is always the calling key, whatever the body says.

visibility
enum<string>
default:private
Available options:
private,
shared
wait
boolean
default:false

Hold the request open until the opening turn has finished and return the complete transcript. Off, the response comes back as soon as the chat exists with status: "streaming"; poll GET /ai/trigger/runs or GET /ai/agents/{id} for the outcome, exactly as for an automation run.

Response

201 - application/json
ai_model
string | null
required
archived
boolean
required
branch_id
string | null
required
config_id
string | null
required
context_usage
object | null
required
created_at
string<date-time>
required
created_by
string
required
error
string | null
required
error_details
string | null
required
id
string
required
last_user_message_at
string<date-time>
required
messages
object[]
required
parent_agent_id
string | null
required
plan_headline
string | null
required
plan_items
object[]
required
project_id
string | null
required
root_agent_id
string | null
required
shared_with
string[]
required
spawn_depth
number
required
spawn_tool_call_id
string | null
required
status
string
required
title
string | null
required
trigger_info
object | null
required
trigger_type
enum<string> | null
required
Available options:
branch,
endpoint,
import,
schedule,
slack,
github,
gitlab,
onshape,
webhook,
assistant,
entity_edit,
manual,
impact_analysis,
what_if_analysis,
subagent
updated_at
string<date-time>
required
visibility
string
required
branches
object[]
integration_grade
string | null
integration_response
string | null