Skip to main content

​
Set your organization’s LLM provider preference

Orbit’s AI-assisted features — agents, translations, and conversation summaries — run on a curated provider lineup, and your organization picks which tier it prefers. This guide walks you through recording that preference: what the endpoint does, who can record it, what the tiers cost, and how the choice shows up downstream on the LLM spend dashboard.

​
What the endpoint does

The preference endpoints on the Organization API read and record your organization’s LLM provider selection from the curated lineup. A provider appears in the selectable list only after it passes a measured best-fit evaluation (quality, latency, cost); a provider still in evaluation is never selectable and never resolves, so the lineup grows only through curation. Today the lineup has two tiers:
  • Devotel LLM (devotel) — the free base tier with zero vendor cost. It exists so every tenant can run AI-assisted features without a per-token vendor bill backing them.
  • Anthropic Claude (anthropic) — the premium tier, priced per usage, on the standing partner lineup.
You never call a provider directly. There are no provider keys to manage, no provider SDKs to integrate, and no provider accounts to maintain: you record a preference once, and the platform resolves the provider per request for every AI-assisted feature in the organization. The GET /api/v1/organization/llm-provider response always includes the current resolution, so “what would the platform actually use for this org?” is a question you can answer with one API call rather than by inference.

​
Recording the preference

Recording a selection is one PUT with a two-value enum:
Role scoping. Recording a preference requires the owner or admin role on your own organization, and it is a whitelabel-parent / root-organization capability: a subaccount can read the catalog and its resolution but always gets 403 on the PUT. Every write is audit-logged with the user, the chosen provider, and the timestamp. Scope of the preference. The record is tenant-level, not per API key. One preference covers the whole organization — there is no per-key or per-agent provider override on this surface. Because usage aggregation (the per-API-key spend budgets governance) rides below the provider tier, a single tenant-level record is enough: the resolution the platform returns applies to every request in the organization. Clearing back to default. Send null to clear a recorded preference:
A cleared preference returns the organization to the platform default — the response says source: "platform_default" rather than source: "stored". You can always read the effective state through GET /api/v1/organization/llm-provider/resolve if you only need the resolution without the catalog payload.

​
Cost and capability tradeoffs

The tradeoff between the two tiers is the standard free-vs-premium exchange, with one important property: the orbit-side mechanism is identical either way. Recording a preference changes a resolution, not an integration.
  • Devotel LLM (free base) — zero vendor cost. There is no per-token vendor bill behind the free tier, so AI-assisted features run with a zero vendor-cost ceiling by construction. The tradeoff is on the capability axis: the premium premium-tier models exist for the cases where the free base’s quality on long, nuanced outputs (a patient-facing summary, a translation that must preserve tone) is not enough.
  • Anthropic Claude (premium) — priced per usage. The premium tier costs money per request, metered into your LLM spend. In exchange you get the higher-capability model for the AI features that resolve through it. The quality gain carries a spend line; the question the spend dashboard answers is whether that line is worth it per feature.
The reason a tenant records this as an organizational preference rather than wiring it per feature is exactly this tradeoff: one recorded decision, downstream to every AI reply, with the cost impact readable on one dashboard.

​
How it shows up on the LLM spend dashboard

The /insights/llm-spend dashboard (page title LLM spend) reports tokens and cents per agent, per model, and per conversation. When you change the preference, the per-provider split on that dashboard is where the change becomes visible: tokens and cents that flowed through Devotel LLM appear on its line, tokens and cents through Anthropic Claude on the premium line. Read the walkthrough in Insights dashboards — LLM spend for the endpoint shapes behind it (/api/v1/insights/llm-spend/...). Minimum working sequence:
  1. Record the preference (PUT /organization/llm-provider).
  2. Wait for the preferred routing to land (the timeline below).
  3. Read the per-provider split on /insights/llm-spend — the new provider starts accruing traffic; the old one drains.
If the preference sits on the platform default (no selection recorded), the split continues to resolve on the default and nothing changes.

​
Operator playbook

A worked example, end to end — enable premium on a patient-facing AI agent for higher-quality summaries, then watch whether the spend deltas justify the tier:
  1. Read the current state. Call GET /api/v1/organization/llm-provider and confirm the current selection, the resolution (source: "stored" vs "platform_default"), and the catalog rows that are selectable. If there is no recorded selection you already know what changing it would resolve to.
  2. Record the preference. PUT /api/v1/organization/llm-provider with { "provider": "anthropic" } — the response returns the new resolution (source: "stored").
  3. Watch the next seven days of per-provider LLM spend. Open /insights/llm-spend (or call the LLM spend endpoints) and confirm the premium line is accruing tokens on the daily trend, by agent and by feature. Check the cost per summary against the free base’s per-summary cost on the same window — the comparison only means anything over a full week.
  4. Decide. If the resolution rate and quality of the summaries justify the premium tier’s line on the dashboard, keep it. If the ROI drops, roll back: PUT { "provider": null } to clear, and the org returns to the platform default cleanly — the rollback is just the clearing step.
For the per-KPI read on agent outcomes the same week (containment, resolution, margin), use the capabilities matrix on Agent comparison — it prices each agent’s performance against the org baseline so “the premium summaries cost X but resolution moved Y” reads as a decision instead of a guess.

​
See also