AI integration

AI steps in a logic block call a provider — Anthropic, OpenAI, Gemini, or any OpenAI-compatible API. Provider configuration resolves bottom-up through three tiers, so the platform sets defaults, the org decides which providers are allowed, and each workspace supplies its own keys.

The three tiers

• Org catalog — the set of providers that exist for this org (name, protocol and the list of models workspaces may pick from), curated by the org admin or developer from a platform-seeded starting set. No keys.
• Org allowlist — an enable/disable gate per provider, set by the org admin or developer. A tenant can only *save a key* for an allowlisted provider — the gate is enforced at save time, not on every call, so a provider removed from the allowlist later doesn't break a workspace that already has a key saved for it.
• Workspace (tenant) — the actual API key and default model, stored as a settings record.

A workspace provider record

Each provider is a settings record with group = aiprovider. Tenants save these through your app's settings UI using the standard settings entity endpoints — the active flag enables/disables a provider without deleting its key.

{
  "group": "aiprovider",
  "name": "openai",
  "active": true,
  "value": {
    "api_key": "sk-...",
    "default_model": "gpt-4o-mini",
    "protocol": "openai"
  }
}

The value shape is the same for every provider:

• `api_key` (required) — the provider key.
• `default_model` — the workspace's default model for this provider, used when a step or agent selects none. Required to use the provider: nothing is substituted if it is missing.
• `protocol` (required) — the wire adapter: openai, anthropic, or gemini.
• `base_url` — an OpenAI-compatible endpoint override (Grok, DeepSeek, Mistral, …).

Model settings (org)

An org admin can describe the models a provider offers under Org Settings → AI Providers → Model settings, so a new vendor's quirks never need a platform change. Each entry names a model, or a family with * at the start or end (o3*, *-thinking), and can say:

• What it is for — text, image, speech or transcription. Left on Auto, it is guessed from the name.
• Which settings it accepts — each with a name, a type (number, integer, boolean, string or select), optional limits or options, and a suggested value. Steps and agents show one optional field per setting; a blank one is not sent.
• A fixed value — for a model that only accepts one, such as a temperature of 1. It is sent whatever a step or agent asks for, and the run notes the override.

PUT /org/settings
{ "group": "aiprovider", "name": "meta", "value": {
  "protocol": "openai", "base_url": "https://api.meta.ai",
  "models": ["muse-wonder-1.0"],
  "model_settings": [ { "name": "muse-wonder-1.0", "params": [
    { "name": "reasoning_effort", "type": "select",
      "options": ["minimal", "low", "medium", "high", "max"], "suggested": "medium" } ] } ]
} }

The runtime reads these on every call, so an edit is live for all the org's workspaces on their next run. The platform ships entries of its own for models with a fixed temperature; an org entry for the same model replaces the built-in one whole. Leave model_settings out of a request to keep what is saved; send an empty list to clear it.

How a call resolves