# Knowledge and SOP API

Knowledge (FAQ), SOPs and the persona live in the Harness content table: one identity row per entry plus immutable versions. The Console pages, Orbit, the CLI and scripts all use the same named commands. This page covers three things: how to read, edit and publish them over the API; how a code package reads them during a turn; and how tool names line up.

![Save, publish, set live, turn reads](../../assets/content-flow.en.svg "Saving and publishing change no conversation; only turns that start after set live read the new version")

- **Saving a version changes no conversation.** A turn reads only the package version it pinned when it started.
- **Publishing makes a new package version and does not set it live.** `set_package_live_version` does; rolling back is setting an older package version live again.
- **Tool names are the key that joins knowledge, SOPs and the SDK.**

Every endpoint on this page is on main (publish, create and archive arrived with #1207; creating and editing SOPs and `check_sop` with #1294; both on 11-12). All ids and content in the examples are made up.

## Conventions

Every path starts with `/api/tenants/{tenant_id}`, where `tenant_id` is your organization. Another organization's package or entry always answers `404 not_found`.

**Authentication**: send `Authorization: Bearer <key>` with a member's personal access key or a signed-in session. The CLI reads `AILO_ACCESS_KEY` or `AILO_TOKEN` (one of the two) and the server address from `AILO_BASE_URL`.

**Source**: `x-ailo-via` is `api`, `cli`, `ui` or `copilot`; without it the call counts as `api`.

**Commands**: always `POST` with the body `{ "command_id": "…", "input": { … } }`. Content commands may leave out `command_id` and the server makes one; package commands require it. Retrying with the same `command_id` and the same input returns the first result; the same `command_id` with other input is `409 idempotency_key_reused`. A refused command leaves no record, so the next try is decided afresh.

**Permissions**: reads need a specialist or above, and read-only keys can read (permission `console.view`). Editing content needs an admin (`knowledge.edit`); publishing needs an admin (`console.publish`).

| Status | `code` | Meaning |
| --- | --- | --- |
| 400 | `bad_request` | The input is wrong; `issues` says where |
| 401 | `unauthorized` | No key, or the key is not valid |
| 403 | `permission_denied` | The role is too low, or a read-only key called a write |
| 404 | `not_found` | The package or entry does not exist, or is not this organization's |
| 404 | `unknown_command` | No content command by that name (an unknown package command returns `404 not_found`) |
| 409 | `idempotency_key_reused` | The same `command_id` came with different input |
| 409 | `package_credentials_forbidden` | The content has a credential field (such as `token` or `password`) or contains a secret value this organization has stored; `field` says where. Key-shaped text is not guessed at |

:::: example
```bash [Environment]
export AILO_BASE_URL=https://api.example.com
export AILO_ACCESS_KEY=<your personal access key>
```

```json [Command body]
{
  "command_id": "4b7e2c1a-9d3f-4e8a-b6c5-0f1e2d3c4b5a",
  "input": { "content_id": "ct_7d2a", "expected_version": 3 }
}
```

```json [409 response]
{ "ok": false, "code": "version_conflict", "latest_version": 4 }
```
::::

## List content

::: endpoint GET /api/tenants/{tenant_id}/packages/{package_id}/content
:::

Every entry of one package, ordered persona, SOPs, FAQ, and by name within each kind. Query name `list_content`.

- **Permission**: specialist or above; read-only keys can call it.
- **Orbit**: on main, a read Orbit can run.
- **CLI**: `ailo content list P [--kind faq|sop|persona] [--q words]`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | No | `faq`, `sop` or `persona` |
| `q` | string | No | 1–200 characters, matched in the name, title or text, case-insensitive. A page filter, not Ailo's knowledge search |

Each item has `content_id`, `kind`, `name`, `title`, `locales`, `latest_version`, `archived`, `live_version`, `live_differs` and `updated_at`.

- `live_version`: which version of this entry the live package version carries. `null` when the live version does not have the entry, nothing is live, or the text does not match.
- `live_differs`: the live package has this name with a text that is none of the versions saved here (someone saved the package directly, around the content table).
- At most 500 items; beyond that `truncated` is `true` and you narrow with `q`.

:::: example
::: code-group
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/packages/pkg_demo/content?kind=faq&q=withdraw" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```
```bash [CLI]
pnpm ailo content list pkg_demo --kind faq --q withdraw --tenant demo-shop
```
:::

```json [200 response]
{
  "ok": true,
  "items": [
    {
      "content_id": "ct_7d2a",
      "kind": "faq",
      "name": "withdrawal-time",
      "title": "How long a withdrawal takes",
      "locales": ["en", "zh-CN"],
      "latest_version": 4,
      "live_version": 3,
      "live_differs": false,
      "updated_at": "2026-11-11T02:40:12.031Z"
    }
  ],
  "truncated": false
}
```
::::

## Read an entry

::: endpoint GET /api/tenants/{tenant_id}/content/{content_id}
:::

One entry's latest version in full, which version is live, and its history (newest first, at most 200). Query name `read_content`.

- **Permission**: specialist or above; read-only keys can call it.
- **Orbit**: on main, a read Orbit can run.
- **CLI**: `ailo content show C`

`content` has `archived`, `true` once the entry is archived.

`content.doc` is that version's document, with the fields in [SOP and document fields](#sop-and-document-fields) except `id` and `version`: the name is in `name` and the number in `latest_version`.

Each version's `source` is `import`, `save`, `create` or `site` (imported from site files). `based_on` is the version it was edited from, `package_version` the package version it was imported from.

:::: example
::: code-group
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/content/ct_7d2a" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```
```bash [CLI]
pnpm ailo content show ct_7d2a --tenant demo-shop
```
:::

```json [200 response]
{
  "ok": true,
  "content": {
    "content_id": "ct_7d2a",
    "package_id": "pkg_demo",
    "kind": "faq",
    "name": "withdrawal-time",
    "latest_version": 4,
    "live_version": 3,
    "live_differs": false,
    "created_by": "agt_demo_admin",
    "created_at": "2026-11-10T08:00:00.000Z",
    "updated_at": "2026-11-11T02:40:12.031Z",
    "doc": {
      "title": "How long a withdrawal takes",
      "content": "Usually within 30 minutes; longer at peak times.",
      "locales": ["en", "zh-CN"],
      "tags": ["withdrawal"],
      "tools": [],
      "legacy_ids": []
    }
  },
  "versions": [
    {
      "version": 4,
      "source": "save",
      "based_on": 3,
      "package_version": null,
      "note": "Mention peak times",
      "doc_sha256": "9c1f…",
      "created_by": "agt_demo_admin",
      "created_at": "2026-11-11T02:40:12.031Z"
    }
  ]
}
```
::::

## Read an older version

::: endpoint GET /api/tenants/{tenant_id}/content/{content_id}/versions/{version}
:::

One version in full, to compare or to restore it. Query name `read_content_version`.

- **Permission**: specialist or above; read-only keys can call it.
- **Orbit**: on main, a read Orbit can run.
- **CLI**: `ailo content show C --version N`

To restore an older version, save its fields again as a new version (next section). Nothing moves a pointer.

:::: example
::: code-group
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/content/ct_7d2a/versions/3" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```
```bash [CLI]
pnpm ailo content show ct_7d2a --version 3 --tenant demo-shop
```
:::

```json [200 response]
{
  "ok": true,
  "version": {
    "content_id": "ct_7d2a",
    "version": 3,
    "source": "import",
    "based_on": null,
    "package_version": 2,
    "note": null,
    "doc_sha256": "51ab…",
    "created_by": "agt_demo_admin",
    "created_at": "2026-11-10T08:00:00.000Z",
    "doc": { "title": "How long a withdrawal takes", "content": "Usually within 30 minutes.", "locales": ["en", "zh-CN"], "tags": ["withdrawal"], "tools": [], "legacy_ids": [] }
  }
}
```
::::

## Import a package's content

::: endpoint POST /api/tenants/{tenant_id}/content/commands/import_package_content
:::

Copies the persona, SOPs and FAQ of one package version into the content table, one entry each, keeping their version numbers. Existing entries are skipped, never overwritten. Nothing goes live.

- **Permission**: admin (`knowledge.edit`).
- **Orbit**: on main, a command Orbit can run; a confirmation card or a direct run, depending on the Orbit mode.
- **CLI**: `ailo content import P [--version N]`, `ailo content import P --file documents.json` (the `documents` input below)

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `package_id` | string | Yes | The package |
| `version` | integer | No | The package version to import from. Default: the latest. When it is older than the latest, entries the latest carries newer come in too (`from_latest` in the answer), so the content table is never behind the package |
| `documents` | object | No | The documents file `pnpm site:import` writes, instead of `version`. New names are added (`imported`), changed texts get their next version (`updated`), unchanged ones are only counted (`unchanged`), and entries missing from the files are kept and listed in `not_in_files` |

| Status | `code` | When |
| --- | --- | --- |
| 409 | `unsupported_package` | A code package or an archived one |
| 409 | `package_content_required` | The package has no version yet |

::: warning After an import
Once a package's content is imported, `save_package_version` with `documents` answers `409 content_managed`. The documents then change only through the commands on this page, then a publish.
:::

:::: example
::: code-group
```bash [curl]
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/content/commands/import_package_content" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"package_id": "pkg_demo"}}'
```
```bash [CLI]
pnpm ailo content import pkg_demo --tenant demo-shop
```
:::

```json [200 response]
{
  "ok": true,
  "package_id": "pkg_demo",
  "package_version": 2,
  "imported": [
    { "kind": "persona", "name": "persona", "content_id": "ct_1b90", "version": 1 },
    { "kind": "faq", "name": "withdrawal-time", "content_id": "ct_7d2a", "version": 3 }
  ],
  "skipped": []
}
```
::::

## Save a version

::: endpoint POST /api/tenants/{tenant_id}/content/commands/save_content_version
:::

Changes a few fields of the latest version and saves the result as the next version. Fields you leave out keep the latest version's values. Nothing goes live and no conversation changes.

- **Permission**: admin (`knowledge.edit`).
- **Orbit**: on main, a command Orbit can run; a confirmation card or a direct run, depending on the Orbit mode.
- **CLI**: `ailo content save C --expected-version N --file doc.json [--note text]`, where `doc.json` holds the fields to change.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `content_id` | string | Yes | The entry |
| `expected_version` | integer | Yes | The latest version you read. `version_conflict` if someone saved first |
| `title` | string | No | 1–200,000 characters |
| `content` | string | No | The text, replaced as a whole, 1–200,000 characters |
| `locales` | string[] | No | Language tags such as `en`, 1–200 of them |
| `tags` | string[] | No | Letters and digits in any script (Chinese, Thai and so on), `-` and `_`, 1–64 characters each, no spaces or punctuation; at most 200 |
| `tools` | string[] | No | SOPs only: the tool names this SOP uses; see [Tool names](#tool-names) |
| `fields` | object | No | SOPs only: replaced as a whole; see [SOP and document fields](#sop-and-document-fields) |
| `note` | string | No | What changed, 1–200 characters |

FAQ entries, the persona and SOPs can all be edited. `tools` or `fields` on an FAQ entry or the persona answers `400 bad_request`. This command does not change `legacy_ids` or `timezone`.

The new number is one more than the larger of the entry's latest version and the highest number this name has in any package version, so numbers can jump. That way `faq:<name>@<version>` always names one text.

| Status | `code` | When |
| --- | --- | --- |
| 400 | `bad_request` | The edited document is not valid; `fields` lists the fields |
| 409 | `version_conflict` | Someone saved first; `latest_version` is the current number. Read again and redo the edit |
| 409 | `no_change` | The result equals the latest version |
| 409 | `content_archived` | The entry is archived; restore it first |
| 400 | `sop_mode_required` | `fields` is passed without `mode`: every SOP says by steps or by goal |
| 409 | `sop_mode_locked` | The SOP's `fields.mode` differs from the latest version's: by steps and by goal never convert; `mode` is the current one |
| 409 | `content_unreadable` | The latest version cannot be read |

:::: example
::: code-group
```bash [curl]
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/content/commands/save_content_version" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"content_id": "ct_7d2a", "expected_version": 3,
       "content": "Usually within 30 minutes; longer at peak times.", "note": "Mention peak times"}}'
```
```bash [CLI]
echo '{"content": "Usually within 30 minutes; longer at peak times."}' > doc.json
pnpm ailo content save ct_7d2a --expected-version 3 --file doc.json \
  --note "Mention peak times" --tenant demo-shop
```
:::

```json [200 response]
{ "ok": true, "content_id": "ct_7d2a", "version": 4, "based_on": 3 }
```
::::

## Add a FAQ

::: endpoint POST /api/tenants/{tenant_id}/content/commands/create_content
:::

Adds a new FAQ entry or SOP to a package. Nothing goes live. The persona cannot be created. A package whose content is not imported but has a version gets its latest version imported first; a refused create undoes that import too. A new package with no version yet has nothing to import: the entry is written as it is, and publishing waits until the package's first version is saved.

- **Permission**: admin (`knowledge.edit`).
- **Orbit**: a command Orbit can run. A confirmation card when Orbit suggests it; runs at once when the member explicitly asked.
- **CLI**: `ailo content create P --file entry.json [--note text]`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `package_id` | string | Yes | The package |
| `kind` | string | Yes | `faq` or `sop`. The CLI sends `faq` unless the file says `"kind": "sop"` |
| `name` | string | Yes | Lower-case letters, digits and `-`, 1–64 characters; fixed once saved |
| `title` | string | Yes | The title |
| `content` | string | Yes | The text |
| `locales` | string[] | Yes | Language tags, at least one |
| `tags` | string[] | No | Tags |
| `tools` | string[] | No | SOPs only; see [Tool names](#tool-names) |
| `fields` | object | For an SOP | SOPs only, with at least `mode` (`steps` or `goal`); see [SOP and document fields](#sop-and-document-fields) |
| `note` | string | No | A note, 1–200 characters |

| Status | `code` | When |
| --- | --- | --- |
| 400 | `bad_request` | `kind` is neither `faq` nor `sop`, or an FAQ entry has `tools` or `fields` |
| 400 | `sop_mode_required` | A new SOP without `fields.mode`: it must say by steps or by goal |
| 409 | `name_taken` | The package already has this name |
| 409 | `unsupported_package` | A code package or an archived one |

:::: example
::: code-group
```bash [curl]
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/content/commands/create_content" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"package_id": "pkg_demo", "kind": "faq", "name": "bonus-rules",
       "title": "How to claim a bonus", "content": "Tap Claim on the promotion page.", "locales": ["en"]}}'
```
```bash [CLI]
pnpm ailo content create pkg_demo --file entry.json --tenant demo-shop
```
:::

```json [200 response]
{ "ok": true, "content_id": "ct_c41e", "name": "bonus-rules", "version": 1 }
```
::::

## Archive and restore

::: endpoint POST /api/tenants/{tenant_id}/content/commands/archive_content
:::

An archived entry is left out of the next publish; its versions stay, and after a restore the next publish carries its latest version again. No version is written. The persona cannot be archived. Restoring is `restore_content`, whose only input is `content_id`.

- **Permission**: admin (`knowledge.edit`).
- **Orbit**: a command Orbit can run. A confirmation card when Orbit suggests it; runs at once when the member explicitly asked.
- **CLI**: `ailo content archive C --expected-version N` and `ailo content restore C`

After an archive, customers keep getting the entry until a package version without it is set live.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `content_id` | string | Yes | The entry |
| `expected_version` | integer | To archive | The latest version you read |

| Status | `code` | When |
| --- | --- | --- |
| 409 | `persona_required` | The persona cannot be archived |
| 409 | `version_conflict` | Someone saved before the archive |
| 409 | `no_change` | Already archived (or already restored) |

:::: example
::: code-group
```bash [curl]
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/content/commands/archive_content" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"content_id": "ct_c41e", "expected_version": 1}}'
```
```bash [CLI]
pnpm ailo content archive ct_c41e --expected-version 1 --tenant demo-shop
pnpm ailo content restore ct_c41e --tenant demo-shop
```
:::

```json [200 response]
{ "ok": true, "content_id": "ct_c41e", "archived": true, "version": 1 }
```
::::

## Publish

::: endpoint POST /api/tenants/{tenant_id}/content/commands/publish_content
:::

Publishes the content table as a new version of the package, with the latest package version's settings (and the live version's engine parameters). SOPs are published one at a time: with `content_ids`, those entries go in at their latest version and every other entry stays as the latest package version has it. Without it, SOPs stay at their last published version (one never published stays out) and every other entry not archived goes in at its latest version. An entry the latest package version carries newer (same name, higher number), or that the content table lacks, is taken from that version and written back to the content table first. Articles are searched by meaning only once a member has confirmed the knowledge index; until then the FAQ list is used and the reply carries `warnings: [{code: 'articles_not_searched', reason: 'index_not_confirmed'}]`. A version that already searches by meaning builds its index first; when it can't (no embedding model, or the models don't respond) the publish is refused with `knowledge_models_unavailable` or `knowledge_index_failed`, nothing is saved and the method and confirmation stay, so publishing again works once the models are back. Only an older version whose method the system set on its own publishes on the FAQ list instead, with that `reason` in `warnings`; a publish confirmed on an Orbit card is refused either way. It **does not go live** and no conversation changes; see the next section.

- **Permission**: admin (`console.publish`).
- **Orbit**: a command Orbit can run. A confirmation card listing each entry's version before and after when Orbit suggests it; runs at once when the member explicitly asked.
- **CLI**: `ailo content publish P [--ids C,C] [--remove-ids C,C] [--note text]`

Before publishing, `check_sop` runs on every SOP that changes (see [SOP and document fields](#sop-and-document-fields)); one problem refuses the whole publish and nothing is written.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `package_id` | string | Yes | The package |
| `content_ids` | string[] | No | The entries to publish (one, or up to 5000 for a batch); one SOP failing its check refuses the batch. An archived one is `content_archived` |
| `remove_content_ids` | string[] | No | Disabled entries to take out of the new version (up to 5000; the `removed` rows of [the changes](#what-changed-and-who-saved-it)); every entry not named stays as the latest package version has it, as with `content_ids`. One enabled again is `content_not_archived` |
| `note` | string | No | What this version changes, 1–500 characters; stored on the version (`note` in the version list) |
| `expected_versions` | object | No | `{content_id: version}`: each entry's latest saved version as you read it (`latest_version` in [the changes](#what-changed-and-who-saved-it)). One saved since is `content_changed`, so nothing goes in unseen |
| `expected_content_sha256` | string | No | The digest of the version you previewed. If content or settings changed since, `content_changed`. Orbit's card uses it |

Returns the new version number `version`, its digest `content_sha256`, the current live version `live_version`, `changes` (each `{content_id, kind, name, from, to}`; `to: null` means this version leaves the entry out; `content_id: null` is an entry the live package has but the content table does not) and `config_changed` (`true` when the settings differ from the live version's; they go live with it).

| Status | `code` | When |
| --- | --- | --- |
| 409 | `content_not_imported` | The package's content has not been imported |
| 409 | `content_changed` | Someone changed an entry the publish was writing back from the package; nothing was saved, try again |
| 409 | `no_change` | Same as the live version; or same as the latest saved package version, then with `version`: set that one live |
| 409 | `sop_check_failed` | `problems` lists each SOP's problems |
| 409 | `content_changed` | Does not match `expected_content_sha256`, or an entry's latest version is not the one in `expected_versions` |
| 409 | `content_not_archived` | An entry in `remove_content_ids` is enabled |
| 404 | `not_found` | An id in `content_ids`, `remove_content_ids` or `expected_versions` is not this package's |
| 409 | `invalid_engine_config` | The engine parameters do not read; turns on this version could only go to the team |
| 409 | `package_content_required` | The package has no version yet |
| 409 | `unsupported_package` | A code package or an archived one |
| 409 | `content_unreadable` | An entry's latest version does not read |
| 409 | `package_credentials_forbidden` | The content has a credential field (such as `token` or `password`) or contains a secret value this organization has stored; `field` says where. Key-shaped text is not guessed at |

:::: example
::: code-group
```bash [curl]
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/content/commands/publish_content" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"package_id": "pkg_demo"}}'
```
```bash [CLI]
pnpm ailo content publish pkg_demo --tenant demo-shop
```
:::

```json [200 response]
{
  "ok": true,
  "package_id": "pkg_demo",
  "version": 3,
  "content_sha256": "e3a0…",
  "live_version": 2,
  "changes": [
    { "content_id": "ct_7d2a", "kind": "faq", "name": "withdrawal-time", "from": 3, "to": 4 },
    { "content_id": "ct_c41e", "kind": "faq", "name": "bonus-rules", "from": null, "to": 1 }
  ],
  "config_changed": false
}
```
::::

## What changed and who saved it

::: endpoint GET /api/tenants/{tenant_id}/packages/{package_id}/changes
:::

With `?version=N`: what version N changed against the version before it (or `?against=M`), entry by entry, with its `note`, who saved the version and when, and `settings_changed` when tools or settings differ too (`compare_package_versions` shows those field by field). Without `version`: the entries saved since the latest version and not in any version yet, then the disabled entries the latest version still carries; what `publish_content` can put into one new version. Titles and names only, never an entry's text. Only real versions count: a 试用 version is never listed or compared.

- **Permission**: `console.view`.
- **Orbit**: a read Orbit can run (`list_package_changes`).
- **CLI**: `ailo packages changes P [--version N [--from M]]`

Each entry is `{content_id, kind, name, title, change, saves}`: `kind` is `persona`, `sop`, `faq` or `article`; `change` is `added`, `changed` or `removed`; `saves` lists each member who saved it in between with the time, newest first (an import copies a version's text and names no one). A `removed` entry names who disabled it, or who saved the version that left it out, as recorded when that version was saved. Without `version`, each entry not removed also has `latest_version`: send it back in `expected_versions`.

| Status | `code` | When |
| --- | --- | --- |
| 409 | `version_required` | `against` without `version` |
| 404 | `not_found` / `package_version_not_found` | Not this organization's package, or no such version |
| 409 | `unsupported_package` | A code package; or, without `version`, an archived one |
| 503 | `changes_timeout` | The package was too large to read in time; try again |

## Set live and roll back

::: endpoint POST /api/tenants/{tenant_id}/packages/{package_id}/commands/set_package_live_version
:::

Sets a saved package version live. Turns that start afterwards read it; a turn already running does not change. This is a package command and is on main.

- **Permission**: admin (`console.publish`).
- **Orbit**: only proposes a confirmation card; it never runs this itself.
- **CLI**: `ailo packages live P N --expected-revision R`

**Roll back**: set an older package version live the same way. `rollback_package_version` (input `expected_revision` only) also exists; it can only return to the previous live version (`ailo packages rollback P --expected-revision R`) and needs the deploy permission (`console.deploy`).

Package commands require `command_id`. Read `expected_revision` from `GET /api/tenants/{tenant_id}/packages/{package_id}` (`ailo packages show P`).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | integer | Yes | The package version to set live |
| `expected_revision` | integer | Yes | The package revision you read |

| Status | `code` | When |
| --- | --- | --- |
| 409 | `revision_conflict` | The package changed; `revision` is the current one |
| 409 | `sop_tool_missing` | A tool an SOP needs is missing or off at a site that runs the package; `missing` lists them |
| 409 | `too_many_resident_tools` | Resident tools exceed the platform's cap |
| 409 | `invalid_engine_config` | This version's engine parameters do not read |
| 409 | `no_previous_version` | A rollback with no previous live version |

:::: example
::: code-group
```bash [curl]
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/packages/pkg_demo/commands/set_package_live_version" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command_id": "c7f0b2d4-1e3a-4c5b-9d8e-7f6a5b4c3d2e",
       "input": {"version": 3, "expected_revision": 5}}'
```
```bash [CLI]
pnpm ailo packages live pkg_demo 3 --expected-revision 5 --tenant demo-shop
# back to version 2
pnpm ailo packages live pkg_demo 2 --expected-revision 6 --tenant demo-shop
```
:::

```json [200 response]
{ "ok": true, "version": 3, "content_sha256": "e3a0…", "revision": 6 }
```
::::

## SOP and document fields

The persona, each SOP and each FAQ entry are the same kind of document in a package version (`packageDocumentSchema` in `apps/server/src/package-content.ts`). A package version's `documents` is `{ persona, sops[], faq[] }`: at most 500 SOPs and 2,000 FAQ entries, with no `id` twice within a kind.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The name: lower-case letters, digits and `-`, 1–64 characters. Called `name` in the content table |
| `version` | integer | Version number, a positive integer |
| `title` | string | Title, 1–200,000 characters |
| `content` | string | Text, 1–200,000 characters. Called `text` in a code package |
| `locales` | string[] | Language tags, 1–200 of them |
| `tags` | string[] | Tags: letters and digits in any script, `-` and `_`, 1–64 characters each; at most 200 |
| `tools` | string[] | Tool names this SOP uses; see [Tool names](#tool-names) |
| `legacy_ids` | string[] | Former names, same format as `id` |
| `timezone` | string | Optional IANA time zone |
| `locale_timezones` | object | Optional, language tag to IANA time zone |

**An SOP's `fields`.** Besides the document above, each SOP version can store `fields` for the editor and the team. They live only on the content version and are not part of the package version: **Ailo does not read them in a turn yet**, and variables are declarations only, with no run-time assignment yet.

| Field | Type | Description |
| --- | --- | --- |
| `description` | string | What the SOP does, 1–256 characters |
| `when_to_use`, `not_for` | string[] | When it applies and when it does not, up to 20 items each, 1–200 characters per item |
| `mode` | string | `steps` or `goal`, required: a new SOP or a save that passes `fields` without it is refused (`sop_mode_required`). Set at creation and never changed between the two (`sop_mode_locked`). An SOP imported from a package has none yet; its first save with `fields` chooses it |
| `triggers` | string[] | What invokes it: `conversation`, `event`, `sop` |
| `events` | string[] | Only when `triggers` includes `event`: which triggers |
| `variables` | object[] | Up to 50, each with `name`, `type` (`string`, `integer`, `enum`, `date-time`, `boolean`), `options`, `description`, `required`, and an optional `default` for booleans |

**Checking an SOP: `check_sop`.** Before a publish every SOP gets a structural check: formats and names only, no model call, and no judgement of how well the SOP is written. Any problem refuses the publish with `409 sop_check_failed {problems}`. You can also check the latest version of one SOP on its own:

::: endpoint GET /api/tenants/{tenant_id}/content/{content_id}/check
:::

- **Permission**: Specialist and above; read-only keys work (`console.view`).
- **Orbit**: can call it.
- **CLI**: `ailo content check C`
- Returns `{ ok: true, version, problems }`. An entry that is not an SOP, or belongs to another organization, answers `404 not_found`.
- Whether a tool is on at each site is not checked here; set live checks it (`sop_tool_missing`).

| `code` | When |
| --- | --- |
| `content_empty` | The text is empty |
| `tool_format` | A tool name is malformed |
| `tool_unknown` | The tool library has no such tool |
| `tool_undeclared` | The text links a tool that is not in `tools` (Ailo's built-in tools excepted) |
| `procedure_unknown` | A linked SOP does not exist or is archived |
| `procedure_in_condition` | A condition contains another SOP |
| `condition_too_deep` | Conditions nested deeper than two levels |
| `variable_undeclared` | A variable is used but not declared in `fields.variables` |

:::: example
```ts [One problem]
export interface SopProblem {
  sop: string;   // the SOP's name (the package document's id)
  field: string; // a field path, such as 'tools[1]', 'content' or 'content[ailo:tool/name]'
  code: string;  // a code from the table above
}
```

```json [check response]
{
  "ok": true,
  "version": 2,
  "problems": [
    { "sop": "withdrawal-delay", "field": "tools[0]", "code": "tool_unknown" }
  ]
}
```

```json [An SOP]
{
  "id": "withdrawal-delay",
  "version": 2,
  "title": "Handling a delayed withdrawal",
  "content": "1. Check the withdrawal's status.\n2. Over 2 hours: open an assist ticket.",
  "locales": ["en"],
  "tags": ["withdrawal"],
  "tools": ["query_transactions", "request_assistance"],
  "legacy_ids": []
}
```
::::

## How a code package reads it

When a turn starts, the platform reads the package's live version and pins it (package, version number, content digest). The whole turn reads only that version. So:

- Saving and publishing change no conversation.
- Once a version is set live, the next turn reads it, in conversations already open too.
- A turn already running does not change.

A code package's `main(context, handle)` gets that version's content as `context.package` (`PackageContent` in `packages/ailo-sdk/src/protocol.ts`):

| Field | Comes from |
| --- | --- |
| `prompt` | The persona's text |
| `procedure_catalogue` | Each SOP's `{name, title, tags}`, for listing in the prompt |
| `faq_catalogue` | Each FAQ entry's `{id, title, tags}` |
| `procedures` | SOPs by name; each has `title`, `version`, `text`, `tools`, `tags` |
| `faq` | FAQ entries by name, same fields |
| `settings` | Site settings; `settings.knowledge` is `true` when this version has the knowledge search on |

**Desk records the knowledge search.** The standard package runs `search_faq` itself: it takes entries by name from `context.package.faq`, each cited as `faq:<name>@<version>`, then calls `recordExternal` with a `record` (`category: 'knowledge'`, `entries` holding only the refs). Only once Desk records it can those refs back a reply; when Desk refuses, the tool answers `lookup_rejected`.

Today only the built-in standard package runs this way; custom code packages are not open yet. For using the SDK, see [Ailo SDK](sdk.md).

:::: example
```ts [Read an SOP and a FAQ entry]
import type { Main } from '@ailodesk/ailo-sdk';

export const main: Main = async (context, handle) => {
  const sop = context.package.procedures.get('withdrawal-delay');
  const faq = context.package.faq.get('withdrawal-time');
  // sop?.version and faq?.version are the numbers in the version this turn pinned
  // …
  return { success: true };
};
```

```ts [Hand Desk a search record]
const recorded = await scope.recordExternal?.({
  requestId: scope.id('lookup'),
  name: 'search_faq',
  content: body,
  record: {
    category: 'knowledge',
    query: 'withdrawal-time',
    call_id: scope.id(),
    entries: [{ ref: 'faq:withdrawal-time@4' }],
  },
});
if (!recorded?.receipt?.accepted) {
  // answer lookup_rejected and keep no citable ref
}
```
::::

## Tool names

A tool name is the key the three lines share; renaming one changes the interface. The same name appears in three places:

1. **An SOP's `tools`**: each name is lower-case letters, digits and `_`, 1–64 characters, at most 200.
2. **The tool library, `list_agent_tools`**: where the SOP editor picks names. `GET /api/tenants/{tenant_id}/agent-tools[?site_id=…]`, readable by admins (`knowledge.edit`); CLI `ailo tools [--site S]`. It returns three groups: `builtin` (Ailo's own tools, including `read_procedure` and `search_faq`), `business` (business system actions) and `mcp` (imported MCP tools, named `mcp_<system>_<tool>`). Each tool has `kind` (`read` or `write`) and `surfaces` (whether it is on for Ailo, the workbench and Orbit).
3. **The SDK's `defineTool({ name, … })`**: a code package's own tools. The SDK does not check the name's format; `runAgent` refuses two tools with one name (`duplicate_tool`).

Names are checked at three points:

- **Publish**: `check_sop` matches an SOP's `tools` and the tools linked in its text against the `list_agent_tools` names.
- **Set live**: for each site that runs the package, every tool an SOP needs must exist and be on for Ailo, else `sop_tool_missing`; resident tools that no SOP declares must stay within the platform's cap (20 by default).
- **During a turn**: in the built-in loop, an imported MCP tool that an SOP declares appears only after the model has read that SOP; the standard package gets every tool from the start of the turn.

:::: example
::: code-group
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/agent-tools" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```
```bash [CLI]
pnpm ailo tools --tenant demo-shop
```
:::

```json [200 response (excerpt)]
{
  "builtin": [
    { "name": "read_procedure", "kind": "read", "surfaces": { "ailo": true, "desk": false, "orbit": false } }
  ],
  "business": [],
  "mcp": [
    { "name": "mcp_shop_order_status", "kind": "read", "surfaces": { "ailo": true, "desk": true, "orbit": false },
      "system_id": "shop", "tool": "order_status", "configured": true }
  ]
}
```
::::

## Still open

- Tools a code package defines with `defineTool` are not in `list_agent_tools`. How publish and set live check an SOP that names one is to be confirmed.
- Whether content commands will work on code packages once custom code packages open (today they answer `unsupported_package`) is to be confirmed.
