ai-provider.set-default

Atomically promotes one AIProviderConfig to be the organization's default AI provider, demoting any previously-default config in the same transaction

Atomically promote an AIProviderConfig to be the org default.

States: PENDING (initial, auto_advance="execute") → COMPLETED (terminal, success=True) PENDING (catch-all) → FAILED (terminal, success=False)

The operation is idempotent: if the target is already the default, the workflow completes with changed=False and no DB mutations.

The unique partial index (organization_id, is_default WHERE is_default) requires that we clear the previous default before setting the new one; we use session.flush() between the two UPDATE statements.

Overview

Property	Value
Workflow type	Atomic
Library	App-connection
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	UUID of the organization that owns the AI provider configs
ai_provider_config_uuid	uuid	Yes	—	UUID of the AIProviderConfig to promote as default
actor	string	No	—	Authenticated caller initiating the operation

Output Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	UUID of the organization that owns the AI provider configs
ai_provider_config_uuid	uuid	Yes	—	UUID of the AIProviderConfig to promote as default
actor	string	No	—	Authenticated caller initiating the operation
previous_default_uuid	uuid	No	—	UUID of the AIProviderConfig that was demoted, or null if none existed
changed	boolean	No	—	False when target was already the default (idempotent); true when a flip occurred
completed_at	string	No	—	ISO-8601 timestamp of completion
failure_reason	string	No	—	Human-readable failure reason (controlled vocabulary)
failure_type	string	No	—	Failure category (error code)
failed_action	string	No	—	Action method that raised
failed_at_state	string	No	—	State the workflow was in when it failed
failed_at	string	No	—	ISO-8601 timestamp of failure
error	string	No	—	Engine-stamped exception message
error_type	string	No	—	Engine-stamped exception class name
failed_layer	string	No	—	Engine-stamped layer index (DAG path)
failed_step	string	No	—	Engine-stamped step name (DAG path)

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	Set-default request received; executing atomic flip
completed	No	Yes	Yes	—	Default AI provider updated (or confirmed unchanged)
failed	No	Yes	No	—	Set-default operation failed

State Diagram

Transitions

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

Business Errors

Code	Message Template
AI_PROVIDER_CONFIG_NOT_FOUND	AIProviderConfig {config_uuid} not found for this organization
AI_PROVIDER_CONFIG_DISABLED	AIProviderConfig {config_uuid} is disabled and cannot be set as default

API Usage

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

{
  "workflow_type": "ai-provider.set-default",
  "initial_data": {
    "organization_uuid": "value",
    "ai_provider_config_uuid": "value"
  }
}