# Start here — how a UiriX agent works, and the order things happen in

Read this page before the reference pages. It explains the model behind the API: what an agent is
made of, which step feeds which, and which endpoint does each step. Every endpoint named here has
its full contract in the linked page. Base URL, auth and conventions: [README](README.md).

**Download the documentation from the API itself** (no credential needed): `GET {base}/docs/download` — a zip of every page plus `openapi.yaml`; `GET {base}/docs/all.md` — every page in one markdown file; `GET {base}/docs/pages` — the page index, `GET {base}/docs/pages/START_HERE.md` — one page; `GET {base}/openapi.yaml` / `openapi.json` — the contract. On dev: `https://dev-dashboard.uirix.com/api/ext/v1/docs/download`.

## The model in one paragraph

An **agent** is a phone / chat / voice-chat assistant that belongs to one **account**. It carries a
**knowledge summary** (the only knowledge it reads at runtime, built from the documents and pages
you give it), three **instruction prompts** (one per surface: inbound phone, chat, voice chat),
**greetings**, a **voice**, a set of **capabilities** (the tools it may call: leads, tickets,
orders, transfers, links…), and the owner's **refinement rules** ("Improve agent"). Knowledge and
instructions are **built**: you change inputs, then rebuild; the built outputs are what the agent
runs. Conversations, calls, webhooks and metrics sit on top of that.

## The lifecycle, in order

| Step | What happens | Endpoint(s) | Page |
|---|---|---|---|
| 1. Account | A tenant exists with a balance and quotas; keys are issued to it. | `GET /accounts`, `GET /accounts/{acc}/limits`, keys via `POST /users/{usr}/credentials` (master key) | [Accounts & Users](accounts-and-users.md), [Authentication](authentication.md) |
| 2. Create the agent | The only creation path is the V4 build: give a website URL and a voice, the platform crawls the site, summarises it, writes the greeting and the three prompts. Poll the build steps until done. | `POST /accounts/{acc}/agents/build` → `GET /agents/{agt}/build` (steps), `POST /agents/{agt}/build` (re-run from a step) | [Agents → Creating](agents.md#creating-an-agent--only-the-v4-build) |
| 3. Knowledge base | Add what the agent should know: upload files, post text, crawl one page or a whole site. Every document starts `processing` and becomes `indexed`. | `POST /agents/{agt}/kb/documents` (file / text / url), `GET /agents/{agt}/kb/documents` | [Agents → Knowledge base](agents.md#knowledge-base) |
| 4. "Keep as is" documents | A guide whose exact wording matters (button names, steps, prices, FAQ answers) can be excluded from the summariser: its full text then follows the summary in the prompt, on every surface. Flag it on create, with `PATCH`, or by opening the text with `IMPORTANT INSTRUCTION FOR AI ASSISTANT`. Chat carries up to 1,000,000 characters of such documents (2,000,000 on the large tier); calls 270,000 — `verbatim_in_calls` puts a document first in the calls block. | `PATCH /agents/{agt}/kb/documents/{doc}` `{ keep_verbatim, verbatim_in_calls }`; sizes in `GET /agents/{agt}/kb/status` → `verbatim` | [Agents → PATCH document](agents.md#patch-agentsagtkbdocumentsdoc--scope-kbwrite) |
| 5. Rebuild the knowledge summary | New or changed documents are `pending` until the summary is rebuilt. The rebuild reads every non-verbatim document and page and writes one summary. Watch `summary.status` and `summary.last_job`. | `POST /agents/{agt}/kb/reindex`, `GET /agents/{agt}/kb/status` | [Agents → kb/status](agents.md#get-agentsagtkbstatus--scope-kbread) |
| 6. Read (or rewrite) the summary | The summary is text you can read and, if you must, replace. Replacing it is a manual override: the next reindex overwrites it. | `GET /agents/{agt}/kb/summary`, `PATCH /agents/{agt}/kb/summary` | [Agents → The summary itself](agents.md#the-summary-itself--read-and-write) |
| 7. Instructions (prompts) | Each surface runs its own prompt. A knowledge change needs a full rebuild; an instruction change (rules, role, greeting) needs an instructions rebuild. Every build creates a prompt version you can audit, deploy or roll back. | `GET /agents/{agt}` (current prompts), `PATCH /agents/{agt}`, `GET /agents/{agt}/prompts`, `POST /agents/{agt}/prompts` (deploy), `…/restore` | [Agents → Which prompt each surface runs](agents.md#which-prompt-each-surface-runs), [When is a build needed](agents.md#when-is-a-build-needed), [Prompts and versions](agents.md#prompts-and-versions) |
| 8. Improve the agent | Plain-language rules ("never quote a monthly price", "always ask for the order number") are normalised by the builder, checked for conflicts and injected into every prompt. Keep them few: every rule costs prompt space on every call. | `PATCH /agents/{agt}` → refinement rules | [Agents → Improve agent](agents.md#improve-agent-refinement-rules) |
| 9. Capabilities | Which tools the agent may call, and the values each needs (transfer directory, website URL, where leads / tickets / orders are e-mailed). Chat via the API allows a safe subset. | `GET /capabilities`, `PATCH /agents/{agt}` → capabilities + completions | [Capabilities](capabilities.md) |
| 10. Voice and greetings | Pick the voice (per provider), the speaking rate, and the greeting per surface and language. | `GET /voices`, `GET/PATCH /agents/{agt}/voice`, greetings via `PATCH /agents/{agt}` | [Voices](voices.md), [Agents → Greetings](agents.md#greetings--which-one-is-spoken-and-in-what-language) |
| 11. Train / test it | Talk to the agent over plain HTTPS: open a conversation, send messages, read the turns. Tools fire for real (a lead is a lead). | `POST /conversations`, `POST /conversations/{conv}/messages`, `POST /conversations/{conv}/end` | [Chat via API](chat-via-api.md), [Quickstart](quickstart.md) |
| 12. Run it | The widget on the website, the inbound phone number, outbound campaigns with profiles. | `GET/PATCH /agents/{agt}/widget`, [Profiles](profiles.md), [Calls](calls.md) | |
| 13. Watch it | Every conversation as structured turns + summary + identity; webhooks the moment something happens; metrics without transcripts. | `GET /conversations`, `POST /webhooks/endpoints`, `GET /metrics/…` | [Conversations](conversations.md), [Webhooks](webhooks.md), [Metrics](metrics.md) |

## What the agent actually knows at runtime

- **Chat, voice chat, phone: the knowledge summary + the "keep as is" documents.** Nothing else —
  there is no retrieval over the raw documents during a conversation. If a fact is not in the
  summary (or in a verbatim document), the agent does not have it.
- **The summary is a compression.** Hundreds of pages become one summary written in the account's
  language. Procedures are kept step by step, but a long guide is still shortened; that is what
  "keep as is" is for.
- **Phone: the last calls with this number.** On an inbound call the agent also gets the last three
  calls between the account and the caller's number in 30 days — outbound calls the platform placed,
  and calls you imported with `POST /conversations/import` (your own voice stack's calls, with their
  summary). It is a short block, not the transcript: date, outcome, the imported summary.
- **Calls have less room than chat.** The realtime models share a 128k-token window with the audio
  of the call, so the calls block of verbatim documents is capped and documents beyond the cap are
  summarised instead. `kb/status.verbatim.calls.dropped` names them.

## What needs a rebuild, and what does not

| You changed… | Needed |
|---|---|
| Documents, pages, crawl | Knowledge rebuild (`kb/reindex`) — the summary is stale until then; the instructions builder reads the summary, so rebuild instructions after it |
| "Keep as is" flags | Nothing — read at the start of every conversation |
| Refinement rules, role, greeting, capabilities | Instructions rebuild (`POST /agents/{agt}/build` from the instructions step) |
| Voice, speaking rate, widget settings, notification e-mails | Nothing — read at runtime |

## Reading order for the rest

1. [Quickstart](quickstart.md) — ten minutes of curl.
2. [Agents](agents.md) — objects, builds, prompts, knowledge, widget, voice.
3. [Capabilities](capabilities.md) and [Voices](voices.md).
4. [Chat via API](chat-via-api.md), then [Conversations](conversations.md) and [Webhooks](webhooks.md).
5. [Profiles](profiles.md) and [Calls](calls.md) for outbound.
6. [Conventions](conventions.md), [Scopes](scopes.md), [Enums](enums.md) as references.