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

# Orby operator assistant: natural-language settings lookup

> How Orby resolves a free-text "Where do I configure X" question to the dashboard setting that controls it — ranked matches with a dashboard route, a doc link, and a relevance score, available to any signed-in operator role.

# Orby operator assistant: natural-language settings lookup

One of Orby's load-bearing skills is answering a "where do I configure X?" question with the dashboard route where the setting actually lives, not a paraphrase from memory. The settings-resolution helper behind it is ranked, grounded, and available to every signed-in operator role — from the billing-only viewer to the super-admin. For the full operator experience (panel, threads, approvals), see [Using Orby in the dashboard](/guides/orby-in-dashboard); for the endpoint contract, see the [Orby API reference](/api-reference/orby).

This guide walks through the settings-lookup surface itself: where it sits in the dashboard, what a ranked match contains, how to phrase the lookup, how the knowledge base degrades while it initializes, and how tool actions pair with the lookup.

## Where Orby lives in the dashboard

Orby is available on any dashboard page — open the panel with the **Orby** button (sparkles icon) in the top bar, or **Ctrl+J** / **Cmd+J**. Inside the panel, every question goes through Orby's operator session, and settings lookups are part of the panel's read-only surface. Beyond the panel, the **Cmd+K** docs-search shortcut anywhere in the dashboard opens the same knowledge-base surface that powers settings lookup.

Every Orby request runs in the context of the signed-in operator:

* **Operator-session auth only.** Orby runs on the operator-session auth layer — requests authenticated with an API key (`X-API-Key` or a `dv_*` Bearer token) are rejected with `403 ORBY_SESSION_REQUIRED` before any handler runs. There is no server-to-server path.
* **Any operator role can look up a setting.** The `owner`, `admin`, `developer`, `viewer`, and `billing` roles all reach the lookup surface — a billing-only operator can ask "where do I set quiet hours?" and get the route back. Super-admin-only endpoints in the knowledge base (`reindex`, `status`) exist for index maintenance, not for lookup.
* **Same permissions, not more.** Orby can only reach the settings and pages the operator's role could already navigate to. There's no separate assistant identity.

## Natural-language settings resolution

When you ask Orby a question of the form *"Where do I configure X?"* — or pick a result from the Cmd+K docs search — Orby resolves the free-text query against the knowledge base and returns ranked matches. Each match carries:

| Field | What it tells you |
| - | - |
| `setting_path` | Dotted path of the setting in the workspace config model (`settings.messaging.quiet_hours`) |
| `dashboard_url` | The dashboard route to click through (`/settings/messaging#quiet-hours`) |
| `label` | The human-readable setting name, as shown in the dashboard |
| `description` | A one-line summary of what the setting controls |
| `doc_url` | The doc page the match was grounded on |
| `snippet` | The excerpt from that page Orby used |
| `score` | Relevance score (0–1) the ranking engine returned |

The endpoint behind this is `POST /api/v1/orby/kb/find-setting`. Public endpoint and field names stay as-is — the table above states the order the JSON body arrives in.

### Phrasing the lookup

* Use **natural language**, not setting names — *"Where do I set quiet hours for SMS campaigns?"* resolves better than `quiet_hours`. The endpoint rewrites the query with a settings bias, so the prose form finds the match the keyword form would.
* Ask for **one thing at a time.** "Where do I set quiet hours and quiet hours for voice?" splits the ranking.
* The `description` field accepts up to **500 characters** — long multi-sentence questions still resolve, but the first sentence carries most of the weight.
* Ask a follow-up **command** ("Where do I set X?") rather than a statement ("quiet hours") — the ranked matcher is tuned for intent phrasing.

A few worked prompts and the ranked-match shape they return:

**"Where do I set quiet hours for SMS campaigns?"**

```json theme={null}
{
  "data": {
    "matches": [
      {
        "setting_path": "settings.messaging.quiet_hours",
        "dashboard_url": "/settings/messaging#quiet-hours",
        "label": "Quiet hours",
        "description": "Pause outbound campaigns during set hours.",
        "doc_url": "https://docs.orbit.devotel.io/compliance/quiet-hours",
        "snippet": "Set the hours during which campaigns pause…",
        "score": 0.9
      }
    ]
  },
  "meta": { "request_id": "req_orby_qh01", "timestamp": "2026-10-01T12:00:00Z" }
}
```

**"Where do I change the welcome message that plays in the ACD queue?"**

```json theme={null}
{
  "data": {
    "matches": [
      {
        "setting_path": "settings.voice.acd_queues.welcome_prompt",
        "dashboard_url": "/settings/voice/queues#welcome",
        "label": "Queue welcome message",
        "description": "Greeting that plays once when a caller enters the queue.",
        "doc_url": "https://docs.orbit.devotel.io/voice/queues",
        "snippet": "The welcome prompt plays before the caller is offered to an agent…",
        "score": 0.86
      }
    ]
  },
  "meta": { "request_id": "req_orby_wl01", "timestamp": "2026-10-01T12:00:01Z" }
}
```

**"Where do I upload the 10DLC brand documents?"**

```json theme={null}
{
  "data": {
    "matches": [
      {
        "setting_path": "settings.messaging.10dlc.brand",
        "dashboard_url": "/settings/messaging/10dlc#brand",
        "label": "10DLC brand registration",
        "description": "Upload brand identity and vetting documents for US carrier registration.",
        "doc_url": "https://docs.orbit.devotel.io/messaging/10dlc-registration",
        "snippet": "Register your brand with the Campaign Registry for US A2P throughput…",
        "score": 0.88
      }
    ]
  },
  "meta": { "request_id": "req_orby_10dlc", "timestamp": "2026-10-01T12:00:02Z" }
}
```

The exact fields and error envelope are in the [Orby API reference — Find a setting](/api-reference/orby#find-a-setting).

## Tool actions: read-only lookup, guarded execution

The settings lookup is **read-only** — it proposes nothing and never pauses for approval. Orby's **tool actions** run when a turn's intent is a change (send a message, reassign a conversation, pause a campaign) and they pause behind the same approval gate described in [Using Orby](/guides/orby-in-dashboard#tool-actions-proposal-and-approval).

The knowledge-base endpoints power both sides of the surface:

* `GET /api/v1/orby/kb/search` — free-text docs search (query: 1–500 chars, optional section/category filter).
* `POST /api/v1/orby/kb/find-setting` — natural-language settings resolution (description: `z.string().min(1).max(500)` — one to 500 characters).
* Both endpoints are available to any authenticated operator role, and both scope their audit rows to the organization, tenant, and operator.
* `POST /kb/reindex` and `GET /kb/status` are super-admin-only maintenance endpoints; they appear in the operator surface only in the rare event of a stuck index, never in the lookup flow itself.

Examples of safe, allowed lookups — all read-only, all resolvable for any role:

* "Where do I configure quiet hours?"
* "Where do I upload my 10DLC brand documents?"
* "Where do I see the campaign cost per send?"
* "Where do I pause an ACD queue?"

## Degradation behavior: `kb_outage_hint`

While the knowledge base is initializing — the `orbit_docs` Qdrant collection is cold, or being reindexed — the lookup does not error. Instead it returns an **empty `matches` array** plus a `kb_outage_hint`:

```json theme={null}
{
  "data": {
    "matches": [],
    "kb_outage_hint": "Orbit's knowledge base is temporarily initialising or reindexing. Try again shortly."
  },
  "meta": { "request_id": "req_orby_cold01", "timestamp": "2026-10-01T12:00:00Z" }
}
```

Treat an empty result with this hint as a **temporary cold index**, not as "Orby thinks nothing matches." Operators should:

1. Wait a few seconds and re-ask — the index typically initializes on the first hit after a deploy or a reindex.
2. If you're a super-admin, check `GET /api/v1/orby/kb/status` for index health (total and stale chunk counts, last run, cache hit rate).
3. If the hint persists for more than a few minutes, the worker that owns reindex is likely unavailable — escalate to your super-admin to trigger `POST /api/v1/orby/kb/reindex` once the worker is back.

In parallel, if Orby's backing store drops briefly (a database failover), the thread list and reopened threads degrade to empty shapes — not errors — and recover when the store returns. A failed turn never pretends to run; the write side reports a real error. See [Orby in the dashboard — degraded behaviour](/guides/orby-in-dashboard#session-only-guard-and-degraded-behaviour).

## FAQ

**Am I rate-limited on lookups?** Lookups share Orby's per-operator limits. `POST /assistant` (a free-form turn that also does settings lookup) is 60 turns per minute per operator; exceeding it returns `429 ORBY_RATE_LIMITED` with a `Retry-After` seconds header. Knowledge-base `search` / `find-setting` calls are not separately limited beyond this — they cost one turn each from the dashboard panel.

**What queries are recorded?** Every lookup is audit-logged with `orby.kb.find_setting` (or `orby.kb.searched`) — the organization, tenant, operator identity, query text (truncated to 200 characters), result count, latency, and the cold-index flag. Audit rows are for SOC-2 / ops reconstruction only; they never see the outside of your workspace.

**Do trial orgs get access?** Yes. Orby's settings lookup is on for every organization, including trials — any authenticated operator role can use it. The only role-gated endpoints are the super-admin maintenance pair (`reindex`, `status`), which no trial org typically needs. Contacts, threads, and query logs stay scoped to the trial tenant.

## See also

* [Using Orby, the in-dashboard operator assistant](/guides/orby-in-dashboard) — the panel, threads, and approval gate
* [Orby API reference](/api-reference/orby) — endpoint shapes for turns, threads, tool confirmations, knowledge-base search, and settings lookup
* [Troubleshooting: Orby operator errors](/troubleshooting/orby-operator-errors) — `ORBY_*` codes, including the rate-limit and cold-index cases
* [Orby operator assistant architecture](/concepts/orby-operator-assistant) — session boundary, thread model, and tool registry on the inside