> ## 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.

# Per-subaccount AI configuration

> Control a child organization's AI features from the parent: enable or disable AI per subaccount, pin its model provider, and mark its AI usage as comped (free), over the API or the dashboard.

# Per-subaccount AI configuration

Every subaccount under your parent organization resolves its own AI configuration: whether AI features (agents, insights, AI-assisted messaging) are enabled, which curated model provider they run on, and whether the usage is comped. You set all three boundaries separately per child, so one subaccount's defaults never leak into the next.

This is the narrative guide for `GET /api/v1/subaccounts/{id}/ai-config` and `PUT /api/v1/subaccounts/{id}/ai-config`. Field-level reference: [Subaccounts API](/api-reference/subaccounts). For the full reseller flow this plugs into, see [White-label subaccounts](/guides/subaccounts-reseller).

## What the config governs

Three controls per subaccount, stored as one settings object and resolved together:

| Control    | Values                            | Resolution                                                                                                |
| ---------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `enabled`  | `true`, `false`, or `null`        | `null` = inherit (AI on). Only an explicit `false` turns AI off for this child.                           |
| `provider` | `devotel`, `anthropic`, or `null` | `null` = the platform default provider. `devotel` is the free base tier; `anthropic` is the premium tier. |
| `comped`   | `true` or `false`                 | `true` = you mark the child's AI usage as free. Defaults to `false` unless you set it.                    |

Reads return two layers side by side: `stored` (exactly what you recorded, nulls included) and the resolved effective values plus `providerSource` — `stored` when you pinned a provider, `platform_default` when the child falls through to the default. That distinction is what you audit: how many children actually carry an override versus ride the default.

## Why set it per child

Isolating billing and behavior per child organization is the point of subaccounts; AI configuration follows the same rule:

* A customer on a lower tier can have AI disabled while the rest stay enabled — one PUT, no plan change.
* A child pinned to a specific provider keeps that choice; new subaccounts keep the platform default until you pin them.
* A comped child never accumulates AI charges against your consolidated reseller statement.

Every PUT is recorded in your audit log with the resulting field values.

## Read the current config

`GET /api/v1/subaccounts/{id}/ai-config` returns the resolved view plus the selectable provider catalog in one round trip. Owner or admin on the parent organization is required.

```bash theme={null}
curl -X GET "https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/ai-config" \
  -H "X-API-Key: dv_live_sk_your_parent_key"
```

## Update the config

`PUT` the same path with all three fields — the body is full-set:

```bash theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/ai-config" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "provider": "anthropic",
    "comped": false
  }'
```

Omitting a field returns `422`; unlike branding or pricing writes, nulls here are meaningful (see [Reset semantics](#reset-semantics)). The response echoes the resolved view back, so your automation re-renders the effective state without a second GET.

## Worked sample — disable AI and comp a child

Disable AI for a subaccount while absorbing its remaining AI usage as free:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/ai-config" \
    -H "X-API-Key: dv_live_sk_your_parent_key" \
    -H "Content-Type: application/json" \
    -d '{
      "enabled": false,
      "provider": null,
      "comped": true
    }'
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    'https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/ai-config',
    {
      method: 'PUT',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        enabled: false,
        provider: null,
        comped: true,
      }),
    },
  )
  console.log(await res.json())
  ```
</CodeGroup>

```json 200 theme={null}
{
  "data": {
    "stored": {
      "enabled": false,
      "provider": null,
      "comped": true
    },
    "enabled": false,
    "provider": "devotel",
    "providerSource": "platform_default",
    "comped": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}
```

The response also carries a `catalog` array with every selectable provider — render that, never a hard-coded list.

## Reset semantics

Reset is a write through the same endpoint — there is no separate reset route. When a child asks you to restore defaults, clear the override by sending nulls:

```json theme={null}
{ "enabled": null, "provider": null, "comped": false }
```

* `enabled: null` clears the on/off override back to inherit — AI on again.
* `provider: null` clears the pin back to the platform default, and `providerSource` flips back to `platform_default`.
* `comped: false` turns the free-usage marker off. It never clears itself by passing `null`; send `false` explicitly.

The dashboard mirrors this exactly: **Settings → Subaccounts → a child's AI tab** offers "Inherit (on)" and "Platform default" options that write these nulls.

## When comped is appropriate

Comped is a billing statement you make on behalf of the child: their AI usage counts as free. Reach for it when:

* You bundle AI into the customer's flat subscription instead of metering it back to them.
* You're running a pilot or proof-of-concept and absorbing the AI cost during evaluation.
* A service credit or goodwill adjustment is owed and you comp usage rather than refund the statement.

It is a per-child marker, so your consolidated rollup still prices the other children normally. Because the claim "usage is free" is billing-relevant, it defaults to `false` — set it deliberately, and unset it the same way.

## Anti-patterns

* **Setting `enabled: false` to control spend** — use [channel budgets](/api-reference/subaccounts) or a monthly spend cap for budget control; `enabled` gates the feature, not the wallet.
* **Hard-coding provider keys in your portal** — render the `catalog` array from the GET response so your UI tracks the selectable set.
* **Assuming a PUT is partial-update** — the body is full-set; read-modify-write with nulls preserved, or you silently clear overrides.

## See also

* [Subaccounts API](/api-reference/subaccounts) — full endpoint catalog
* [White-label subaccounts](/guides/subaccounts-reseller) — the reseller flow this configures
* [Audit log](/guides/audit-log) — where every AI-config write lands
* [Subaccount–organization model](/concepts/subaccount-organization-model) — what child-organization isolation covers