> For the complete documentation index, see [llms.txt](https://lmile.gitbook.io/lmile-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lmile.gitbook.io/lmile-docs/operator-api/stocktake.md).

# Stocktake — 棚卸

拠点の在庫を数えて、帳簿との差異を確認し、承認して反映する API です。棚（店舗なら売場 / バックヤードなどのエリア）ごとに「数え始める → 数えた数をまとめて送って締める」を繰り返し、全部を締めたらセッションを提出します。管理者が承認（`commit`）すると差分を反映します。

反映のしかたは拠点の種類で変わります（`mode`）。

| 拠点                                                  | `mode`     | 帳簿数                                                 | 承認で起きること                                                                                                                |
| --------------------------------------------------- | ---------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| MFC（自己在庫。`location_type` が `mfc`、または `mfc_enabled`） | `shelf`    | 棚ごとの棚在庫 / 状態別在庫（棚を締めた時点で固定）                         | **締めた時点の帳簿数との差分**を今の棚の数に当てる。締めたあとの出荷・入庫と二重になりません                                                                        |
| それ以外（店舗。スマレジや Shopify が在庫の正）                        | `location` | 商品ごとに、取り込み元の生の在庫数 + 注文に引き当て済みでまだ確保していない数（提出した時点で固定） | 棚は動かさず、商品ごとの差分を[外部システムへの調整](/lmile-docs/routing-api/inventory-adjustments.md)として貯める（在庫同期の向きが双方向の拠点だけ。取り込みのみの拠点は差異の記録まで） |

商品状態（良品 / アウトレット / 不良品 / 検品中 など。`agent_read.inventory_condition_codes`）ごとに数えます。良品以外の数は販売可能数に入りません。

> **Base URL** `https://api.lmile.io` · **認証** `x-ingest-secret` ヘッダー または operator JWT（`Authorization: Bearer`）（[詳細](/lmile-docs/getting-started/authentication.md)） · `shop` はリクエストボディに含めます（API キーで呼ぶ場合は省略できます）

## エンドポイント

| Method | Path                                   | 用途                                                                        | テーブル                                                                                                                |
| ------ | -------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `POST` | `/api/operator/stocktake/open`         | セッションを開く（拠点ごとに進行中は 1 つ。`mode` は拠点の種類で決まる）                                 | `lm_stocktake_sessions`                                                                                             |
| `POST` | `/api/operator/stocktake/shelf-start`  | 棚を数え始める（開始時刻を取る。締めた棚なら再計数）                                                | `lm_stocktake_shelves`                                                                                              |
| `POST` | `/api/operator/stocktake/shelf-submit` | 数えた数をまとめて送って棚を締める（帳簿数を固定し、差異を返す）                                          | `lm_stocktake_counts`                                                                                               |
| `POST` | `/api/operator/stocktake/transition`   | 提出（`submit`。`location` では商品ごとの帳簿数をここで固定）/ 取消（`cancel`）/ 提出の取り下げ（`reopen`） | `lm_stocktake_sessions` / `lm_stocktake_location_lines`                                                             |
| `POST` | `/api/operator/stocktake/commit`       | 承認して反映（商品単位の部分反映。`shelf` は棚へ、`location` は外部システムへの調整へ）                     | `lm_shelf_inventory` / `lm_shelf_condition_stock` / `lm_shelf_inventory_logs` / `lm_inventory_external_adjustments` |
| `GET`  | `/api/operator/stocktake/current`      | 拠点で進行中のセッションと棚の進捗、商品状態の一覧（現場アプリの初期表示。operator JWT）                        | read                                                                                                                |

読み取りは `agent_read.stocktake_sessions` / `stocktake_shelves` / `stocktake_counts` / `stocktake_location_lines`（`location` の商品ごとの行）です。

### 流れ

```
open ──► shelf-start ──► shelf-submit ──┐  （棚ごとに繰り返す。締めた棚は再 start で数え直せる）
            ▲                           │
            └───────────────────────────┘
         transition(submit) ──► commit（承認）──► committed
                 │                 └─ 保留が残れば submitted のまま。直して再 commit
                 └─ transition(reopen / cancel)
```

### 状態

| セッション       | 意味                                                 |
| ----------- | -------------------------------------------------- |
| `counting`  | 数えている。棚の start / submit ができる                       |
| `submitted` | 提出済み。承認（`commit`）か、取り下げ（`reopen`）か、取消（`cancel`）を待つ |
| `committed` | 全部の計数行を反映した                                        |
| `cancelled` | 取り消した。在庫は動いていない                                    |

棚は `counting`（数え始めた）/ `closed`（締めた）。行が無い棚は未計数です。

***

## `POST` /api/operator/stocktake/open

拠点の棚卸セッションを開きます。拠点ごとに進行中（`counting` / `submitted`）のセッションは 1 つです。`mode` は拠点の種類で決まります（MFC = `shelf` / それ以外 = `location`。冒頭の表）。

### リクエスト

```http
POST https://api.lmile.io/api/operator/stocktake/open
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json
```

```json
{ "shop": "demo-store.myshopify.com", "locationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "note": "10月 定期棚卸" }
```

### ボディパラメータ

| パラメータ        | 型             |  必須 | 説明                         |
| ------------ | ------------- | :-: | -------------------------- |
| `shop`       | string        |  ✓  | 店舗ドメイン（API キーで呼ぶ場合は省略できます） |
| `locationId` | string (uuid) |  ✓  | 拠点                         |
| `note`       | string        |     | メモ（最大 500 文字）              |

### レスポンス

```json
{ "ok": true, "session": { "sessionId": "…", "shop": "…", "locationId": "…", "mode": "shelf", "status": "counting", "note": "10月 定期棚卸", "openedAt": "2026-10-08T01:00:00Z", "submittedAt": null, "committedAt": null, "cancelledAt": null } }
```

### 挙動・冪等性

* 進行中のセッションがあると `409 session_already_open`（その `sessionId` を返します）。同じ拠点で 2 つ同時に数えることはできません。
* `mode` は選べません。店舗（`location`）でも数え方は同じで、`shelfCode` には売場 / バックヤードなどのエリアのコードを入れます（形式は棚コードと同じ）。

***

## `POST` /api/operator/stocktake/shelf-start

棚を数え始めます。この時刻から締めるまでにその棚の在庫が動くと、締めたときに `movementDetected: true` になります（数え直しの目安）。締めた棚をもう一度 start すると**再計数**になり、前の計数は履歴として残して（`superseded`）置き換えます。

### リクエスト

```http
POST https://api.lmile.io/api/operator/stocktake/shelf-start
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json
```

```json
{ "shop": "demo-store.myshopify.com", "sessionId": "…", "shelfCode": "SA-A-13" }
```

### レスポンス

```json
{ "ok": true, "sessionId": "…", "shelf": { "shelfCode": "SA-A-13", "status": "counting", "startedAt": "2026-10-08T01:05:00Z", "recountNo": 0 } }
```

### 挙動・冪等性

* 数えている途中（`counting`）の棚への再 start は何もしません（開始時刻を縮めません）。
* 棚マスタ（[Shelves](/lmile-docs/shelf-api/shelves.md)）に無い棚コードは登録します。
* セッションが `counting` でないと `409 invalid_state`。

***

## `POST` /api/operator/stocktake/shelf-submit

棚で数えた数をまとめて送り、棚を締めます。送った時点の帳簿数（良品 = 棚在庫、良品以外 = 状態別在庫）を `expected` として固定し、差異（`counted − expected`）を返します。\*\*帳簿にあるのに送られなかった商品は「0 と数えた」\*\*として記録されます。

### リクエスト

```http
POST https://api.lmile.io/api/operator/stocktake/shelf-submit
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json
```

```json
{
  "shop": "demo-store.myshopify.com",
  "sessionId": "…",
  "shelfCode": "SA-A-13",
  "lines": [
    { "barcode": "4912345678901", "countedQty": 5 },
    { "barcode": "4912345678901", "countedQty": 1, "conditionCode": "C" },
    { "barcode": "4912345678918", "countedQty": 2 }
  ]
}
```

### ボディパラメータ

| パラメータ       | 型                 |  必須 | 説明                                                                  |
| ----------- | ----------------- | :-: | ------------------------------------------------------------------- |
| `shop`      | string            |  ✓  | 店舗ドメイン                                                              |
| `sessionId` | string (uuid)     |  ✓  | セッション                                                               |
| `shelfCode` | string            |  ✓  | 棚コード（形式は [Shelf Inventory](/lmile-docs/shelf-api/inventory.md) と同じ） |
| `countedAt` | string (ISO 8601) |     | 数えた時刻。省略すると送った時刻                                                    |
| `lines[]`   | array             |  ✓  | 数えた数（最大 5,000 行）。**空配列 = 棚に何も無かった**                                 |

#### `lines[]` オブジェクト

| パラメータ           | 型            |  必須 | 説明                                    |
| --------------- | ------------ | :-: | ------------------------------------- |
| `barcode`       | string       |  ✓  | 商品 barcode                            |
| `countedQty`    | number (int) |  ✓  | 数えた数（0 以上）。同じ barcode × 状態が複数行あれば足します |
| `conditionCode` | string       |     | 商品状態。省略すると良品                          |

### レスポンス

```json
{
  "ok": true,
  "sessionId": "…",
  "shelfCode": "SA-A-13",
  "linesRecorded": 3,
  "unresolved": [],
  "movementDetected": false,
  "recountNo": 0,
  "variance": [
    { "barcode": "4912345678901", "condition": "A", "counted": 5, "expected": 6, "delta": -1 },
    { "barcode": "4912345678901", "condition": "C", "counted": 1, "expected": 0, "delta": 1 },
    { "barcode": "4912345678918", "condition": "A", "counted": 2, "expected": 2, "delta": 0 }
  ]
}
```

| フィールド              | 説明                                                                                                             |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| `unresolved[]`     | 記録できなかった行（`product_not_found` / `condition_unresolved` / `missing_barcode_or_qty` / `negative_qty`）。他の行は記録されます |
| `movementDetected` | 数え始めてから締めるまでに、この棚の在庫が動いた                                                                                       |
| `variance[]`       | 棚 × 商品 × 状態ごとの 数えた数 / 帳簿数 / 差                                                                                  |

### 挙動・冪等性

* まだ start していない棚への submit は、送った時点を開始時刻として締めます（`movementDetected` は判定できないので `false`）。
* 店舗（`location`）には棚在庫が無いので `expected` は 0 になり、`variance[]` はエリアごとの差異としては意味を持ちません。商品ごとの差異は提出（`transition: submit`）のときに拠点全体で出します。
* 締めた棚への再 submit は**再計数**です。前の計数は履歴として残り（`superseded`）、新しい計数で置き換わります。
* 同じ内容の再送は同じ結果になります（置き換えなので二重になりません）。
* 在庫は動きません。反映は `commit` です。

***

## `POST` /api/operator/stocktake/transition

セッションの状態を変えます。

### リクエスト

```http
POST https://api.lmile.io/api/operator/stocktake/transition
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json
```

```json
{ "shop": "demo-store.myshopify.com", "sessionId": "…", "action": "submit" }
```

| `action` | 遷移                                     | 条件                                                                                                 |
| -------- | -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `submit` | `counting` → `submitted`               | start したまま締めていない棚があると `409 shelves_still_counting`（棚の一覧を返します）。`location` では、この時点で商品ごとの帳簿数を固定します（下） |
| `reopen` | `submitted` → `counting`               | 1 行でも反映済みなら不可（`409 invalid_state`）                                                                 |
| `cancel` | `counting` / `submitted` → `cancelled` | 在庫は動きません                                                                                           |

### レスポンス

```json
{ "ok": true, "session": { "sessionId": "…", "status": "submitted", "submittedAt": "…", "…": "…" } }
```

### 店舗（`location`）の提出で固定する帳簿数

商品ごとに 1 行（`agent_read.stocktake_location_lines`）を作ります。

* `countedGoodQty` = 全エリアで数えた良品の合計 / `countedOtherQty` = 良品以外の合計（記録のみ。反映しません）
* `bookOnHandQty` = 取り込み元（スマレジなど）が送ってきた**生の在庫数**。販売可能数ではありません（販売可能数は取り置きや発売前の 0 を含むため）
* `allocatedUnsecuredQty` = この拠点の注文に引き当て済みで、まだ確保（取り分け）していない数。**確保済みの現物は数えない**前提です
* `expectedQty` = `bookOnHandQty + allocatedUnsecuredQty`。差 = `countedGoodQty − expectedQty`
* `bookSourceSystem` = 帳簿数を送ってきた取り込み元（`smaregi` / `shopify`）。承認で差分を当てる先と違う商品は保留になります（下の `book_source_mismatch`）
* `uncounted` = 帳簿にある（生の在庫数が 1 以上、または引き当て済みで未確保がある）のに、どのエリアでも読まれなかった商品。`countedGoodQty` は 0 で、差は −帳簿数（紛失として扱う）。棚ごとの棚卸の「帳簿にあるのに送られなかった商品は 0 と数えた」と同じ扱いです。承認では既定で保留になります
* `movementDetected` = 最初のエリアを数え始めてから提出までに、その商品の在庫行か引き当てが動いた（営業中の計数で売れた・入荷した）。承認では既定で保留になります。承認のたびに同じ窓（開始〜提出）で見直すので、提出のあとに遅れて届いた取り込みも拾います

行の母集合は「数えた商品 ∪ 帳簿がある商品」です。一部のエリアしか数えずに提出すると、残りのエリアにある商品が `uncounted` として並びます。全部のエリアを締めてから提出してください。

取り下げ（`reopen`）して数え直して再提出すると、作り直します。

***

## `POST` /api/operator/stocktake/commit

提出済みのセッションを承認し、反映します。

* **MFC（`shelf`）**: 計数行ごとに **締めた時点の帳簿数との差分（`counted − expected`）** を今の棚の数に当てるので、締めたあとに出荷・入庫があっても二重になりません。良品が動いた商品は、同じトランザクションで販売可能数を再計算し、[出荷元在庫の通知](/lmile-docs/webhooks/source-inventory.md)を送ります。
* **店舗（`location`）**: 棚は動かしません。商品ごとの差（`countedGoodQty − expectedQty`）が 0 以外なら、拠点の在庫同期の向きが**双方向**のとき[外部システムへの調整](/lmile-docs/routing-api/inventory-adjustments.md)を 1 行作ります（`writeBack: "adjustment"`）。取り込みのみの拠点、または外部 ID（スマレジ店舗 ID / Shopify ロケーション ID）が無い拠点は記録だけです（`record_only`）。LastMile の在庫数は、コネクタが外部システムに当てたあとの取り込みで追いつきます。

### リクエスト

```http
POST https://api.lmile.io/api/operator/stocktake/commit
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json
```

```json
{ "shop": "demo-store.myshopify.com", "sessionId": "…", "limit": 100 }
```

| パラメータ              | 型            |  必須 | 説明                                                                       |
| ------------------ | ------------ | :-: | ------------------------------------------------------------------------ |
| `limit`            | number (int) |     | 1 回で処理する商品（barcode）の数（1〜500。既定 100）。`remaining` が 0 になるまで繰り返し呼びます        |
| `includeMoved`     | boolean      |     | `location` のみ。数えている間に動いた商品（`movementDetected`）も通す（既定 `false` = 保留）       |
| `includeUncounted` | boolean      |     | `location` のみ。帳簿にあるのに読まれなかった商品（`uncounted`。差 = −帳簿数）も通す（既定 `false` = 保留） |

### レスポンス

```json
{
  "ok": true,
  "committed": false,
  "session": { "sessionId": "…", "status": "submitted", "…": "…" },
  "applied": 41,
  "held": [
    { "shelfCode": "SA-A-13", "barcode": "4912345678901", "condition": "A", "errorKind": "counted_below_active", "shelfTotal": 3, "shelfTotalAfter": 1, "active": 2 }
  ],
  "remaining": 0,
  "changed": [{ "locationId": "…", "barcode": "4912345678918", "before": 2, "after": 4 }]
}
```

| フィールド                | 説明                                                          |
| -------------------- | ----------------------------------------------------------- |
| `committed`          | 全部の計数行を反映して `committed` になった                                |
| `applied`            | この呼び出しで反映した行数                                               |
| `held[]`             | 保留した行とその理由（下）。反映されていません                                     |
| `remaining`          | まだ処理していない行数（`limit` に当たった分）。0 になるまで繰り返し呼びます                 |
| `changed[]`          | 販売可能数が変わった商品（`location` では常に空）                              |
| `adjustmentsCreated` | `location` のみ。この呼び出しで作った外部システムへの調整の数                        |
| `writeBack`          | `location` のみ。`smaregi` / `shopify`（調整を作る）または `record_only` |

### 挙動・冪等性

* **商品（barcode）単位の部分反映**です。ある商品が保留でも、他の商品は反映します。
* **保留（`held[]`）**:
  * `counted_below_active` — 良品の棚の合計が、注文に引き当て済みの数を上回る状態から下回る状態に変わる。その商品の良品の行をすべて保留します（良品以外の行は反映します）。引き当てを見直してから再 commit するか、棚を数え直します
  * `negative_after_delta` — 差分を当てると棚の数が負になる（締めたあとに現物が動いた）。その行だけ保留します
  * `moved_while_counting` — `location` のみ。数えている間にその商品の在庫行か引き当てが動いた。`includeMoved: true` で通すか、取り下げて数え直します
  * `uncounted` — `location` のみ。帳簿にあるのにどのエリアでも読まれなかった商品（差 = −帳簿数）。本当に無いなら `includeUncounted: true` で通し、数え忘れなら取り下げてそのエリアを数えます
  * `book_source_mismatch` — `location` のみ。帳簿数を送ってきた取り込み元（`bookSourceSystem`）が、差分を当てる先のコネクタと違う（例: スマレジの店舗なのに Shopify の数が帳簿になっている）。通す選択肢はありません。取り込みの経路を直してから、取り下げて数え直します
* 保留が残る間、セッションは `submitted` のままです。再 commit は未反映の行だけを処理します（反映済みの行は二度当てません）。保留の行も再 commit で再評価します。
* `committed` のセッションへの再 commit は `ok: true` + `alreadyCommitted: true` で何もしません。
* 反映した増減は増減ログ（`reason: stocktake`）にセッション id 付きで残ります。
* `location` では、この拠点に生の在庫数（取り込み元の `on_hand_qty`）が一度も届いていなければ `422 book_quantity_unavailable` で承認しません（届く前は帳簿数が 0 になり、差分が全部マイナスになるため）。コネクタの取り込みを確認してから再 commit します。

***

## `GET` /api/operator/stocktake/current

拠点で進行中（`counting` / `submitted`）のセッションと、その中で数えた棚の進捗、shop の商品状態の一覧を返します。現場アプリが計数画面を開くときに読みます。進行中が無ければ `session: null` です。認証は operator JWT のみ（読み取り専用。`shop` と `locationId` はクエリ）。

```http
GET /api/operator/stocktake/current?shop=demo-store.myshopify.com&locationId=b2c3d4e5-f6a7-8901-bcde-f23456789012
Authorization: Bearer <operator JWT>
```

```json
{
  "ok": true,
  "locationMode": "shelf",
  "syncMode": "inbound_only",
  "session": { "sessionId": "…", "locationId": "…", "mode": "shelf", "status": "counting", "note": null, "openedAt": "…", "submittedAt": null },
  "shelves": [
    { "shelfCode": "SA-A-13", "status": "closed", "startedAt": "…", "closedAt": "…", "movementDetected": false, "recountNo": 0, "countedLines": 3, "varianceLines": 1 }
  ],
  "conditions": [
    { "code": "A", "label": "通常品", "isDefault": true },
    { "code": "C", "label": "販売不可/修理", "isDefault": false }
  ]
}
```

| フィールド          | 説明                                                                                             |
| -------------- | ---------------------------------------------------------------------------------------------- |
| `locationMode` | この拠点で開く棚卸の形（`shelf` / `location`）。進行中が無くても返します                                                 |
| `syncMode`     | 拠点の在庫同期の向き（`bidirectional` / `inbound_only`）。`location` で `bidirectional` のときだけ承認で外部システムへ反映します |

## エラー

エンドポイント固有:

| Status | 条件                                   | レスポンス例                                                                                            |
| :----: | ------------------------------------ | ------------------------------------------------------------------------------------------------- |
|  `404` | `sessionId` が shop に無い               | `{ "ok": false, "error_kind": "not_found", "error": "session not found" }`                        |
|  `409` | 進行中のセッションがある（`open`）                 | `{ "ok": false, "error_kind": "session_already_open", "error": "...", "sessionId": "…" }`         |
|  `409` | セッションの状態がその操作を許さない                   | `{ "ok": false, "error_kind": "invalid_state", "error": "...", "status": "submitted" }`           |
|  `409` | 締めていない棚がある（`transition: submit`）     | `{ "ok": false, "error_kind": "shelves_still_counting", "error": "...", "shelves": ["SA-A-14"] }` |
|  `422` | 棚コード形式不正                             | `{ "ok": false, "error_kind": "invalid_shelf_code", "error": "...", "shelfCode": "SA_A_13" }`     |
|  `422` | `locationId` が shop に無い（`open`）      | `{ "ok": false, "error_kind": "location_unresolved" }`                                            |
|  `422` | 生の在庫数が一度も届いていない（`commit`・`location`） | `{ "ok": false, "error_kind": "book_quantity_unavailable" }`                                      |
|  `422` | shop に既定の商品状態が無い                     | `{ "ok": false, "error_kind": "condition_master_missing" }`                                       |

`shelf-submit` の行単位のエラーは HTTP `200` の `unresolved[]`、`commit` の保留は `200` の `held[]` に返します（silent skip しません）。

共通エラー（`401` / `400` / `403` / `405` / `500` / `503`）は [Error Codes](/lmile-docs/reference/error-codes.md) を参照。

## データモデル

* `sot.lm_stocktake_sessions` — セッション。拠点ごとに進行中は 1 つ（部分 UNIQUE）。`status` / `mode`（`shelf` / `location`）/ 開いた・提出した・承認した・取り消した時刻と操作者。読み取り view: `agent_read.stocktake_sessions`
* `sot.lm_stocktake_shelves` — セッションの中で数える棚。`status`（`counting` / `closed`）/ `started_at` / `closed_at` / `movement_detected` / `recount_no`。読み取り view: `agent_read.stocktake_shelves`（計数行数・差異行数つき）
* `sot.lm_stocktake_counts` — 計数。1 行 = 棚 × 商品 × 状態。`counted_qty` / `expected_qty` / `superseded_at`（再計数で置き換えた旧行）/ `applied_at` / `applied_delta` / `apply_error_kind`。読み取り view: `agent_read.stocktake_counts`（`delta` つき）
* `sot.lm_stocktake_location_lines` — `location` の商品ごとの行（提出で固定）。`counted_good_qty` / `counted_other_qty` / `book_on_hand_qty` / `allocated_unsecured_qty` / `expected_qty` / `movement_detected` / `applied_at` / `applied_delta` / `apply_error_kind` / `write_back`。読み取り view: `agent_read.stocktake_location_lines`（`delta` つき）
* 反映先は `shelf` が `sot.lm_shelf_inventory`（良品）/ `sot.lm_shelf_condition_stock`（良品以外）。増減ログ `sot.lm_shelf_inventory_logs` に `reason = stocktake` と `stocktake_session_id`。`location` は `sot.lm_inventory_external_adjustments`（[Inventory Adjustments](/lmile-docs/routing-api/inventory-adjustments.md)）


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://lmile.gitbook.io/lmile-docs/operator-api/stocktake.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.