> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Set your organization's LLM provider preference

> Record which curated provider tier your organization prefers for AI-assisted features — the free Devotel LLM base tier or the premium Anthropic Claude tier — and understand what the choice changes downstream.

# 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](/api-reference/organization) 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:

```bash theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/organization/llm-provider" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "devotel"}'
```

**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](/guides/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:

```bash theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/organization/llm-provider" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": null}'
```

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](/guides/insights-dashboards) 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](/api-reference/insights)) 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](/guides/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

* [Insights dashboards — LLM spend](/guides/insights-dashboards) — where the per-provider spend split appears
* [Organization API](/api-reference/organization) — endpoint shapes for the preference endpoints
* [Agent comparison](/guides/agent-comparison) — the per-KPI capabilities matrix behind the ROI read
* [Per-API-key spend budgets](/guides/per-api-key-spend-budgets) — cap the ceiling the premium tier can spend under
* [API key usage budget alerts](/guides/api-key-usage-budget-alerts) — alert thresholds on usage budgets for enforcement
* [AI agent cost controls](/agents/cost-controls) — the governor surface for budget caps and model downshift