ai.chat

Send a chat completion via the org's AI CloudConnection (provider-agnostic)

Provider-agnostic LLM chat completion via a user CloudConnection or AIProviderConfig.

Inputs:

connection_uuid: UUID of an AI-provider CloudConnection (optional; at least one of connection_uuid / ai_provider_config_uuid must be present, OR the org must have a default config) (OPENAI / ANTHROPIC / BEDROCK / AZURE_OPENAI / GOOGLE_AI / GROK / OLLAMA)
ai_provider_config_uuid: UUID of an AIProviderConfig row (optional). When supplied without connection_uuid, the workflow calls data.ai-provider.get to resolve connection_uuid, default_model, and model_config. When neither this nor connection_uuid is present, data.ai-provider.get-default is called for the org. Precedence: explicit connection_uuid > ai_provider_config_uuid > org default.
messages: List of {role, content} dicts (required)
model: Override the connection's default model (optional; provider prefix is auto-added if missing). Wins over config.default_model when both are present.
system_prompt: Optional system instruction prepended as a system message
temperature: Sampling temperature 0.0-2.0 (optional). Wins over model_config.temperature when both are present.
max_tokens: Max tokens to generate (optional). Wins over model_config.max_tokens when both are present.

Outputs (terminal state_data):

Failure reasons (controlled vocabulary on FAILED state):

connection_not_found
not_an_ai_connection
connection_not_active
missing_credentials
upstream_auth_failed
upstream_rate_limited
upstream_error
litellm_unavailable
validation_failed
no_ai_provider_configured (new) — neither uuid given and org has no default
ai_provider_config_not_found (new) — explicit ai_provider_config_uuid not resolved

Overview

Field	Type	Required	Default	Description
`connection_uuid`	uuid	No	—	UUID of an AI-type CloudConnection in the caller's org. Highest priority: when present, ai_provider_config_uuid and the org-default lookup are skipped entirely.
`ai_provider_config_uuid`	uuid	No	—	UUID of an AIProviderConfig row. When supplied (and connection_uuid is absent), the workflow calls data.ai-provider.get to resolve connection_uuid, default_model, and model_config. When neither this nor connection_uuid is present, data.ai-provider.get-default is used for the org. Explicit model/temperature/max_tokens always override the resolved config values.
`messages`	json	Yes	—	List of {role, content} message objects
`model`	string	No	—	Model override; provider prefix auto-added if missing. Takes precedence over config.default_model.
`system_prompt`	string	No	—	Optional system instruction
`temperature`	json	No	—	Sampling temperature 0.0-2.0. Wins over model_config.temperature from the resolved config.
`max_tokens`	integer	No	—	Max tokens to generate. Wins over model_config.max_tokens from the resolved config.

Field	Type	Required	Default	Description
`response_text`	string	No	—	—
`role`	string	No	—	—
`model_used`	string	No	—	—
`finish_reason`	string	No	—	—
`input_tokens`	integer	No	—	—
`output_tokens`	integer	No	—	—
`provider`	string	No	—	—
`failure_reason`	string	No	—	—
`failure_type`	string	No	—	—
`failed_action`	string	No	—	—
`failed_at_state`	string	No	—	—
`error`	string	No	—	—
`error_type`	string	No	—	—
`failed_layer`	string	No	—	—
`failed_step`	string	No	—	—

State	Initial	Terminal	Success	Auto-advance	Description
`pending`	Yes	No	—	`execute`	—
`completed`	No	Yes	Yes	—	—
`failed`	No	Yes	No	—	—

From	Action	To	Description
`pending`	`execute`	`completed`	—
`*` (any state)	`fail`	`failed`	—

bash

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "ai.chat",
  "initial_data": {
    "messages": "value"
  }
}