API 使用手冊API manualAPI マニュアル

jt-ipam 的 REST API、phpIPAM 相容層、Graylog 查表、機櫃圖嵌入與 MCP。以下所有網址請把 https://ipam.example.com 換成你自己的位址。 The jt-ipam REST API, phpIPAM compatibility layer, Graylog lookups, rack embeds and MCP. Replace https://ipam.example.com below with your own address.jt-ipam の REST API、phpIPAM 互換レイヤ、Graylog 用のルックアップ、ラック図の埋め込み、そして MCP です。以下の URL の https://ipam.example.com は、ご自身のアドレスに置き換えてください。

1認證：API 權杖Auth: API tokens認証：API トークン

外部程式一律用 API 權杖，不要用帳號密碼登入拿 JWT（JWT 只有 15 分鐘、是給網頁前端用的）。 External programs should always use an API token rather than logging in for a JWT (JWTs last 15 minutes and exist for the web UI).外部のプログラムからは必ず API トークンを使ってください。ユーザー名とパスワードでログインして JWT を取得する方法は避けてください（JWT は 15 分で切れ、Web UI のためのものです）。

怎麼取得權杖Getting a tokenトークンの取得

登入 jt-ipam → 右上角使用者選單 → API 權杖 → 新增。填名稱、有效天數（1～365，預設 90）、權限範圍，按儲存。 Sign in to jt-ipam → user menu (top right) → API tokens → Add. Give it a name, a lifetime (1–365 days, default 90) and a scope, then save.jt-ipam にログイン → 右上のユーザーメニュー → API トークン → 追加。名称、有効日数（1～365、既定は 90）、スコープを入力して保存します。

怎麼帶權杖Sending the tokenトークンの送り方

curl -H "Authorization: Bearer jt_prod_xxxxxxxxxxxxxxxx" \
  https://ipam.example.com/api/v1/subnets

權杖首碼 jt_ 會讓後端自動辨識為 API 權杖（沒有這個首碼則當成 JWT 解析）。 The jt_ prefix tells the backend this is an API token (without it, the value is parsed as a JWT).先頭の jt_ によって、バックエンドはこれが API トークンだと判断します（この接頭辞が無ければ JWT として解析されます）。

權限範圍（scope）Scopesスコープ

建立權杖時只接受這兩種。填其他值（例如 write、subnets:read）會被拒絕回 422，這是刻意的：不提供無法真正強制執行的權限旋鈕。唯一的例外是 phpIPAM 相容層登入時發出的權杖，它帶 phpipam:*，效果等同不限制（見第 16 節）。 These are the only two values accepted when you create a token. Any other value (e.g. write, subnets:read) is rejected with 422, deliberately, so there is no knob that looks like a restriction but isn't enforced. The one exception is the token issued by the phpIPAM compatibility login: it carries phpipam:*, which behaves as unrestricted (see section 16).トークン作成時に受け付けるのはこの二つだけです。それ以外の値（write や subnets:read など）は 422 で拒否されます。これは意図的な仕様で、実際には強制されない「制限のように見えるつまみ」を用意しないためです。唯一の例外は phpIPAM 互換レイヤのログインで発行されるトークンで、phpipam:* を持ち、制限なしと同じ扱いになります（第 16 節を参照）。

每把權杖每分鐘最多 600 次請求（REST 與 MCP 合計，超過回 429）。權杖在到期前 14、7、1 天與當天會通知擁有者；帳號停用時，它的權杖全部撤銷（重新啟用帳號也不會回來）。 Each token is limited to 600 requests a minute (REST and MCP combined; more returns 429). The owner is notified 14, 7 and 1 days before a token expires and on the day; deactivating an account revokes all of its tokens (reactivating the account does not bring them back).トークンごとに毎分 600 リクエストまでです（REST と MCP の合計。超えると 429）。期限の 14・7・1 日前と当日に所有者へ通知します。アカウントを無効化すると、そのトークンはすべて失効します（アカウントを再度有効にしても戻りません）。

用 API 管理權杖Managing tokens via the APIAPI からのトークン管理

curl -X POST https://ipam.example.com/api/v1/api-tokens \
  -H "Authorization: Bearer <jwt-or-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"monitoring","expires_in_days":180,"scopes":["read"]}'

{
  "id": "3f1c...", "name": "monitoring",
  "token": "jt_prod_XXXXXXXXXXXXXXXXXXXX",
  "token_prefix": "jt_prod_", "expires_at": "2027-01-26T00:00:00Z",
  "scopes": ["read"]
}

2通用慣例Conventions共通の決まり

• 基底路徑：/api/v1。請求與回應預設是 JSON（Content-Type: application/json）；例外會在各節明講（CSV 匯出、multipart 匯入、DSV 純文字、SVG、SSE 串流）。 Base path: /api/v1. Requests and responses are JSON (Content-Type: application/json) unless a section says otherwise (CSV exports, multipart imports, DSV text, SVG, SSE streams).ベースパスは /api/v1 です。リクエストもレスポンスも既定は JSON（Content-Type: application/json）で、例外は各節で明記します（CSV エクスポート、multipart の取り込み、DSV のテキスト、SVG、SSE ストリーム）。
• 識別碼是 UUID，不是遞增整數。 Identifiers are UUIDs, not incrementing integers.識別子は UUID であり、連番の整数ではありません。
• 時間一律是 UTC 的 ISO 8601，但寫法有兩種：用 schema 定義回應的端點寫成 2026-07-30T12:34:56.123456Z，直接回字典的端點寫成 2026-07-30T12:34:56.123456+00:00，兩者都可能帶微秒。phpIPAM 相容層的權杖到期時間則是 YYYY-MM-DD HH:MM:SS（UTC）。請用通用的 ISO 8601 解析器，不要比對固定格式字串。 Timestamps are always UTC ISO 8601, written two ways: endpoints with a response schema return 2026-07-30T12:34:56.123456Z, endpoints that return a plain dict return 2026-07-30T12:34:56.123456+00:00, and either may carry microseconds. The phpIPAM layer's token expiry is YYYY-MM-DD HH:MM:SS (UTC). Use a general ISO 8601 parser instead of matching a fixed format string.時刻はすべて UTC の ISO 8601 ですが、書き方が二通りあります。スキーマで応答を定義したエンドポイントは 2026-07-30T12:34:56.123456Z、辞書をそのまま返すエンドポイントは 2026-07-30T12:34:56.123456+00:00 で、どちらもマイクロ秒が付くことがあります。phpIPAM 互換レイヤのトークン有効期限は YYYY-MM-DD HH:MM:SS（UTC）です。固定の書式文字列と照合せず、汎用の ISO 8601 パーサを使ってください。
• 未知欄位會被拒絕。寫入用的 schema 是嚴格模式（extra=forbid）：多送一個拼錯的欄位會回 422，而不是安靜忽略。 Unknown fields are rejected. Write schemas are strict (extra=forbid): a misspelled extra field returns 422 instead of being silently ignored.未知の項目は拒否されます。書き込み用のスキーマは厳格モード（extra=forbid）です。綴りを誤った項目を余分に送ると、黙って無視されるのではなく 422 が返ります。
• 部分更新用 PATCH，只送要改的欄位。 Use PATCH for partial updates, sending only the fields you want to change.部分更新には PATCH を使い、変更したい項目だけを送ってください。

分頁與列表的三種形狀Pagination: three list shapesページング：一覧の三つの形

列表端點有三種形狀。各端點用哪一種、上限多少，以該端點的 schema 為準（見第 22 節）： List endpoints come in three shapes. Which one an endpoint uses, and its limits, is defined by that endpoint's schema (see section 22):一覧系のエンドポイントには三つの形があります。どの形か、上限はいくつかは、各エンドポイントのスキーマで確認してください（第 22 節を参照）。

page_size（或 limit）的上限因端點而異：多數是 500（預設 50）；/api-tokens、/notifications、/webhooks、/ip-requests、/scan-agents、/cert-agents、/tasks 等是 200；/addresses 是 1000（預設 100），/dns/records、/librenms/arp、/librenms/fdb 也是 1000。超過上限回 422，不會自動截斷。要抓完整資料就依 total 逐頁取。 The page_size (or limit) cap varies: most endpoints allow 500 (default 50); /api-tokens, /notifications, /webhooks, /ip-requests, /scan-agents, /cert-agents, /tasks and a few others allow 200; /addresses allows 1000 (default 100), as do /dns/records, /librenms/arp and /librenms/fdb. Exceeding the cap returns 422 rather than silently truncating. To fetch everything, page through using total.page_size（または limit）の上限はエンドポイントごとに異なります。多くは 500（既定 50）、/api-tokens・/notifications・/webhooks・/ip-requests・/scan-agents・/cert-agents・/tasks などは 200、/addresses は 1000（既定 100）で、/dns/records・/librenms/arp・/librenms/fdb も 1000 です。上限を超えると黙って切り詰めるのではなく 422 を返します。全件取得するには total を見ながらページを進めてください。

3錯誤與狀態碼Errors & status codesエラーとステータスコード

錯誤回應的外層是 {"detail": …}，但 detail 有兩種型別，客戶端兩種都要處理： Error responses are wrapped as {"detail": …}, but detail comes in two types, and clients must handle both:エラー応答の外枠は {"detail": …} ですが、detail には二つの型があり、クライアントは両方を扱う必要があります。

• 字串：例如 {"detail": "Admin required"}。 A string, e.g. {"detail": "Admin required"}.文字列：例 {"detail": "Admin required"}。
• 物件 {code, params, message}：code 是穩定的機器可讀代碼，params 是代入句子的參數（常含 reason，也就是底層錯誤原文），message 是給人看的後備句子，可能是中文。請依 code 判斷，顯示時用 message。 An object {code, params, message}: code is a stable machine-readable code, params holds values for the sentence (often including reason, the underlying error text), and message is a human-readable fallback that may be in Chinese. Branch on code; show message to people.オブジェクト {code, params, message}：code は安定した機械可読のコード、params は文に埋め込む値（下層のエラー原文である reason を含むことが多い）、message は人が読むための代替文で、中国語の場合があります。判定には code を使い、表示には message を使ってください。

{ "detail": "Admin required" }

{ "detail": { "code": "range_auto_managed",
              "params": { "source": "fw-a · KEA" },
              "message": "…" } }

欄位驗證失敗（422）固定是 {"detail": "Invalid request", "errors": […]}，errors 指出哪個欄位不合法。未預期的錯誤回 500 {"detail": "Internal Server Error"}，伺服器端不會回 stack trace。 Validation failures (422) are always {"detail": "Invalid request", "errors": […]}, with errors pinpointing the invalid fields. Unexpected errors return 500 {"detail": "Internal Server Error"}; stack traces are never returned.項目の検証エラー（422）は常に {"detail": "Invalid request", "errors": […]} で、errors がどの項目が不正かを示します。想定外のエラーは 500 {"detail": "Internal Server Error"} を返し、スタックトレースが返ることはありません。

{ "detail": "Invalid request",
  "errors": [ { "loc": ["body","cidr"], "msg": "value is not a valid IPv4 network", "type": "value_error" } ] }

4權限模型Permission model権限モデル

jt-ipam 是預設關閉（deny by default）。你的權杖看得到什麼，完全取決於擁有者被授權了什麼： jt-ipam is deny by default. What your token can see depends entirely on what its owner has been granted:jt-ipam は既定で拒否（deny by default）です。トークンで何が見えるかは、その所有者に何が許可されているかで決まります。

• 可逐物件授權的資料（客戶/區段/子網路/IP/裝置/機櫃/地點）→ 只回你可見範圍內的，連 total、統計與趨勢都會跟著縮放。授權分 read/write/admin 三級，區段、子網路與 IP 的寫入依該物件的等級判斷。但建立區段，以及裝置、客戶、地點、機櫃的新增/修改/刪除只有 admin 能做。 Per-object data (customers / sections / subnets / IPs / devices / racks / locations) → only what you can see, and total, counts and trends scale with it. Grants have three levels, read / write / admin, and writes to sections, subnets and IPs are checked against the level on that object. However, creating sections and creating, editing or deleting devices, customers, locations and racks is admin-only.オブジェクト単位で許可されるデータ（顧客/セクション/サブネット/IP/機器/ラック/拠点）→ 閲覧可能な範囲だけが返り、total・集計・傾向もその範囲に合わせて縮小します。許可は read/write/admin の三段階で、セクション・サブネット・IP への書き込みはそのオブジェクトの段階で判定します。ただしセクションの作成と、機器・顧客・拠点・ラックの作成/変更/削除は admin だけが行えます。
• 全域基礎設施資料（VLAN/VRF/NAT/DNS/虛擬化/佈線/電力、以及多數整合帶回的資料…）→ 讀取需要「全域讀取」（admin 或萬用讀取授權），寫入需要 admin。只被指派特定物件的帳號會拿到 403。有些整合連讀取都只給 admin（見第 12 節）。 Global infrastructure (VLAN / VRF / NAT / DNS / virtualization / cabling / power, and most data pulled in by integrations…) → reading requires global read (admin or a wildcard read grant); writing requires admin. Accounts scoped to specific objects get 403. Some integrations are admin-only even for reads (see section 12).全体に関わる基盤データ（VLAN/VRF/NAT/DNS/仮想化/配線/電源、および多くの連携が取り込んだデータなど）→ 読み取りには全体の読み取り権限（admin またはワイルドカードの読み取り許可）、書き込みには admin が必要です。特定のオブジェクトだけを割り当てられたアカウントは 403 になります。読み取りも admin 限定の連携があります（第 12 節を参照）。
• 純管理資料（稽核記錄、使用者/群組/權限、系統與整合設定）→ 需要 admin。例外是少數顯示用的設定（例如 GET /system/ui-display、/system/ip-cooldown、/system/search-settings）與 GET /custom-fields，任何登入帳號都能讀。 Administrative data (audit log, users / groups / permissions, system and integration settings) → requires admin. The exceptions are a few display settings (e.g. GET /system/ui-display, /system/ip-cooldown, /system/search-settings) and GET /custom-fields, which any signed-in account can read.管理系のデータ（監査ログ、ユーザー/グループ/権限、システムと連携の設定）→ admin が必要です。例外は表示用の一部の設定（GET /system/ui-display・/system/ip-cooldown・/system/search-settings など）と GET /custom-fields で、ログイン済みの任意のアカウントが読めます。

想知道自己這把權杖有什麼能力，打 GET /api/v1/auth/me：回應含 is_admin、has_visibility（是否有任何可見範圍）、has_global_read、can_edit（是否有任何 write/admin 授權）、can_ssh、ai_enabled 等欄位。注意路徑在 /auth 底下；/api/v1/me/preferences 則是個人偏好設定。 To discover what your token can do, call GET /api/v1/auth/me: the response includes is_admin, has_visibility (any visible scope at all), has_global_read, can_edit (any write/admin grant), can_ssh, ai_enabled and more. Note that the path is under /auth; /api/v1/me/preferences holds personal preferences.自分のトークンに何ができるかを知るには GET /api/v1/auth/me を呼びます。応答に is_admin・has_visibility（閲覧可能な範囲があるか）・has_global_read・can_edit（write/admin の許可があるか）・can_ssh・ai_enabled などが含まれます。パスは /auth の下にある点に注意してください。/api/v1/me/preferences は個人の設定です。

curl -H "Authorization: Bearer $TOKEN" https://ipam.example.com/api/v1/auth/me

5區段（Sections）Sectionsセクション（Sections）

最上層的分組容器，子網路掛在區段底下。可有父子階層。 The top-level grouping container that subnets belong to. Supports parent/child nesting.最上位のグループ用コンテナで、サブネットはこの下にぶら下がります。親子の入れ子にも対応します。

建立區段Create a sectionセクションの作成

curl -X POST https://ipam.example.com/api/v1/sections \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Main DC","description":"main site"}'

6子網路（Subnets）Subnetsサブネット（Subnets）

建立子網路的欄位Create fields作成時の項目

上層子網路（master_subnet_id）在建立時依包含關係自動算出，之後可以用 PATCH 調整。 The parent subnet (master_subnet_id) is computed from containment on create; you can adjust it later with PATCH.親サブネット（master_subnet_id）は作成時に包含関係から自動で決まり、後から PATCH で調整できます。

curl -X POST https://ipam.example.com/api/v1/subnets \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"cidr":"192.0.2.0/24","section_id":"<section-uuid>","description":"office LAN",
       "gateway":"192.0.2.1","scan_enabled":true,"scan_agent_id":"<agent-uuid>",
       "scan_method":["icmp","arp","rdns"]}'

位址範圍（集區）Address ranges (pools)アドレス範囲（プール）

子網路底下可以劃出位址範圍，purpose 是 dhcp（預設）、reserved 或 other。讀取需要子網路 read、寫入需要 write。清單是純陣列，每筆附 size、used、first_free。自動建立的範圍（auto）被 DHCP 排除區間切成好幾段時合成一列：起訖是設定的整個範圍，size 已扣掉排除的位址，excluded 是排除數，segments 是各段起訖（first_free 會跳過排除的位址）。範圍超出子網路回 400、與既有範圍重疊回 409；依偵測到的 DHCP 發放範圍自動建立的（auto: true）跟著上游同步，不能手動修改或刪除（409 range_auto_managed）。 A subnet can hold address ranges whose purpose is dhcp (default), reserved or other. Reading needs read on the subnet; writing needs write. The list is a bare array, each item with size, used and first_free. An auto range (auto) that DHCP exclusions split into pieces is shown as one row: the start and end are the whole configured range, size leaves out excluded addresses, excluded is how many, and segments lists each piece (first_free skips excluded addresses). A range outside the subnet returns 400; an overlap with an existing range returns 409. Ranges created automatically from a detected DHCP pool (auto: true) follow the upstream server and cannot be edited or deleted by hand (409 range_auto_managed).サブネットの中にアドレス範囲を設けられます。purpose は dhcp（既定）・reserved・other のいずれかです。読み取りにはサブネットの read、書き込みには write が必要です。一覧は配列のみで、各要素に size・used・first_free が付きます。DHCP の除外範囲で複数に分かれた自動範囲（auto）は 1 行にまとめ、開始と終了は設定された範囲全体、size は除外アドレスを除いた数、excluded は除外数、segments は各区間です（first_free は除外アドレスを飛ばします）。サブネット外の範囲は 400、既存の範囲との重複は 409 です。検出した DHCP 配布範囲から自動作成されたもの（auto: true）は上流に従って同期され、手動では変更も削除もできません（409 range_auto_managed）。

curl -X POST https://ipam.example.com/api/v1/subnets/<subnet-uuid>/ranges \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"start_ip":"192.0.2.100","end_ip":"192.0.2.199","purpose":"dhcp","name":"office DHCP"}'

7IP 位址（Addresses）IP addressesIP アドレス（Addresses）

IP 的權限跟著所屬子網路走：讀取要 read、新增與修改要 write、刪除要 admin。下表括號內是需要的等級。 IP permissions follow the parent subnet: reading needs read, creating and editing need write, deleting needs admin. The level each call needs is shown in brackets below.IP の権限は所属するサブネットに従います。読み取りは read、作成と変更は write、削除は admin が必要です。下表の括弧内が必要な段階です。

查詢參數Query parametersクエリパラメータ

全站 IP 異動記錄：GET /api/v1/ip-changes，依子網路可見範圍過濾。參數：q（IP、欄位、新舊值、備註）、ip_id、subnet_id、section_id、customer_id、event_type、source、since / until、page / page_size（上限 500）、sort（created_at 預設、ip 照位址大小、event_type、field、source、actor）/ order（預設 desc）。沒有值的排最後；每筆帶 ip_id，IP 已刪除時是 null。Site-wide IP change log: GET /api/v1/ip-changes, filtered by subnet visibility. Parameters: q (IP, field, old/new value, note), ip_id, subnet_id, section_id, customer_id, event_type, source, since / until, page / page_size (max 500), sort (created_at default, ip by address value, event_type, field, source, actor) / order (default desc). Rows without a value sort last; each row carries ip_id, which is null once the IP has been deleted.全体の IP 変更履歴：GET /api/v1/ip-changes（サブネットの閲覧範囲で絞り込み）。パラメータ：q（IP・項目・新旧の値・備考）、ip_id、subnet_id、section_id、customer_id、event_type、source、since / until、page / page_size（上限 500）、sort（created_at が既定、ip はアドレスの大小順、event_type、field、source、actor）/ order（既定 desc）。値のない行は最後。各行に ip_id があり、IP が削除されると null になります。

# 查某網段裡所有 IP / all IPs in one subnet
curl -G https://ipam.example.com/api/v1/addresses \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "subnet_id=<subnet-uuid>" --data-urlencode "page_size=1000"

# 依主機名稱找 / find by hostname
curl -G https://ipam.example.com/api/v1/addresses \
  -H "Authorization: Bearer $TOKEN" --data-urlencode "q=web01"

CSV 匯入CSV importCSV の取り込み

POST /api/v1/addresses/import 是 multipart/form-data，欄位是 subnet_id（必填）、file（必填，UTF-8 CSV，最大 16 MB）、dry_run（預設 false）。CSV 依標題列對欄，至少要有 ip；已存在的「子網路 + IP」會略過。dry_run=true 同步回預覽、不寫入；實際匯入走背景作業，回 task_id，進度用 GET /api/v1/tasks/{task_id} 查。 POST /api/v1/addresses/import is multipart/form-data with subnet_id (required), file (required, UTF-8 CSV, up to 16 MB) and dry_run (default false). Columns are matched by the header row, which must include ip; existing (subnet, IP) pairs are skipped. dry_run=true returns a preview synchronously without writing; a real import runs as a background task and returns a task_id you can follow with GET /api/v1/tasks/{task_id}.POST /api/v1/addresses/import は multipart/form-data で、項目は subnet_id（必須）、file（必須、UTF-8 の CSV、最大 16 MB）、dry_run（既定 false）です。列は見出し行で対応付け、ip が必須です。既存の「サブネット + IP」は飛ばします。dry_run=true は書き込まずにプレビューを同期で返し、実際の取り込みはバックグラウンド処理になって task_id を返します。進捗は GET /api/v1/tasks/{task_id} で確認します。

GET /api/v1/addresses/unmanaged?subnet_id=… 回這個子網路裡沒有 IP 記錄、但最近 7 天看得到在用的位址（掃描代理的目擊與 LibreNMS ARP 表），每筆有 ip、last_seen_at、sources（scanner、arp:librenms…）、mac、vendor、hostname。權限同 IP 清單（子網路的讀取權限，沒有回 404）。 GET /api/v1/addresses/unmanaged?subnet_id=… returns the addresses in that subnet that have no IP record but were seen in use in the last 7 days (scan agent sightings and LibreNMS ARP), each with ip, last_seen_at, sources (scanner, arp:librenms, …), mac, vendor and hostname. Same permission as the IP list (read access to the subnet, 404 otherwise).GET /api/v1/addresses/unmanaged?subnet_id=… は、そのサブネットで IP の記録はないが直近 7 日に使用が見えたアドレス（スキャンエージェントの観測と LibreNMS の ARP）を返します。各件に ip・last_seen_at・sources（scanner、arp:librenms など）・mac・vendor・hostname があります。権限は IP 一覧と同じです（サブネットの読み取り権限、無ければ 404）。

curl -X POST https://ipam.example.com/api/v1/addresses/import \
  -H "Authorization: Bearer $TOKEN" \
  -F subnet_id=<subnet-uuid> -F dry_run=true -F file=@addresses.csv

8裝置（Devices）Devices機器（Devices）

讀取依裝置的可見範圍；新增、修改、刪除與匯入都只有 admin 能做。 Reads follow device visibility; creating, editing, deleting and importing are admin-only.読み取りは機器の閲覧範囲に従います。作成・変更・削除・取り込みは admin のみです。

裝置匯入Device import機器の取り込み

POST /api/v1/devices/import 是 multipart/form-data：file（CSV 或 Excel .xlsx，最大 16 MB、最多 5,000 列）、dry_run、on_existing（skip 預設/update）。注意 dry_run 預設是 true：不帶參數時只回每一列的預覽（新增/更新/略過/錯誤與原因），不寫入。帶 dry_run=false 才真的匯入，走背景作業並回 task_id。 POST /api/v1/devices/import is multipart/form-data: file (CSV or Excel .xlsx, up to 16 MB and 5,000 rows), dry_run, and on_existing (skip by default, or update). Note that dry_run defaults to true: without it you only get a per-row preview (create / update / skip / error with the reason) and nothing is written. Send dry_run=false to import for real; that runs as a background task and returns a task_id.POST /api/v1/devices/import は multipart/form-data で、file（CSV または Excel の .xlsx、最大 16 MB・5,000 行）、dry_run、on_existing（既定 skip、または update）を受け取ります。dry_run の既定は true である点に注意してください。指定しないと行ごとのプレビュー（作成/更新/スキップ/エラーと理由）だけが返り、何も書き込まれません。実際に取り込むには dry_run=false を送ります。バックグラウンド処理になり task_id を返します。

curl -X POST https://ipam.example.com/api/v1/devices/import \
  -H "Authorization: Bearer $TOKEN" \
  -F file=@devices.xlsx -F dry_run=false -F on_existing=update

9搜尋與 IP 工具Search & IP tools検索と IP ツール

GET /api/v1/search?q=…&limit_per_type=… 是全站搜尋（q 1～128 字，limit_per_type 1～50、預設 8），跨區段/子網路/IP/裝置/客戶/機櫃/地點/VLAN/虛擬機/NAT/DNS 記錄等型別，並依你的可見範圍過濾。支援部分 MAC 首碼（如 00:00:5e）。每個型別先排真正包含查詢字的結果，再排相似的；有任何包含查詢字的結果時，只回傳那些。搜哪些型別、比對哪些欄位、排列順序照管理員的全站搜尋設定（GET/PUT /api/v1/system/search-settings：instant 隨打即找、types 依排列順序列出 {type, enabled, fields}、catalog 是每個型別可比對的欄位；任何登入帳號可讀，修改要 admin 並留稽核，一個型別都沒開或開了沒勾欄位時回 422 search_settings_no_type/search_settings_no_field）。回應的 order 是分組順序。虛擬機：vm 的 id 是它的 IP 記錄，vm_record（沒有 IP 記錄，需全域讀取）的 id 是「平台.VM id」。 GET /api/v1/search?q=…&limit_per_type=… is a global search (q 1–128 chars, limit_per_type 1–50, default 8) across sections, subnets, IPs, devices, customers, racks, locations, VLANs, VMs, NAT, DNS records and more, filtered to what you may see. Partial MAC prefixes (e.g. 00:00:5e) work. Each type ranks results that contain the query before similar ones, and when any result contains the query only those are returned. Which types and fields are searched, and in what order, follows the administrator's global search settings (GET/PUT /api/v1/system/search-settings: instant for search as you type, types as {type, enabled, fields} in display order, and catalog with the fields each type can match; any signed-in account can read it, changing it needs admin and is audited, and no enabled type or an enabled type without fields returns 422 search_settings_no_type/search_settings_no_field). The response's order is the group order. Virtual machines: a vm hit's id is its IP record; a vm_record hit (no IP record, needs global read) has id "platform.VM id".GET /api/v1/search?q=…&limit_per_type=… は横断検索です（q は 1～128 文字、limit_per_type は 1～50・既定 8）。セクション/サブネット/IP/機器/顧客/ラック/拠点/VLAN/仮想マシン/NAT/DNS レコードなどの種別をまたぎ、閲覧可能な範囲に絞って返します。MAC の部分的な接頭辞（00:00:5e など）にも対応します。各種別でクエリを含む結果を類似の結果より先に並べ、クエリを含む結果があればそれだけを返します。検索する種別・照合するフィールド・並び順は管理者の全体検索設定に従います（GET/PUT /api/v1/system/search-settings：instant は入力中に検索、types は並び順どおりの {type, enabled, fields}、catalog は各種別で照合できるフィールド。ログイン済みなら読めますが、変更は admin のみで監査ログに残り、種別が 1 つもオンでない・オンの種別にフィールドがない場合は 422 search_settings_no_type/search_settings_no_field）。応答の order はグループの順序です。仮想マシン：vm の id は IP レコード、vm_record（IP レコードなし、全体の閲覧権限が必要）の id は「プラットフォーム.VM id」です。

計算與查詢工具（GET）Calculators and lookups (GET)計算と照会のツール（GET）

以下 /api/v1/tools/* 都是 GET、不改任何資料，任何登入帳號都能用，唯讀權杖也可以。其中 dns-lookup、dns-mail 會由伺服器向 DNS 解析器查詢，geoip 會呼叫 MaxMind GeoLite2 網路服務（管理者要先填好憑證）。 The /api/v1/tools/* calls below are all GET, change no data, and work for any signed-in account, read-only tokens included. dns-lookup and dns-mail query DNS resolvers from the server, and geoip calls the MaxMind GeoLite2 web service (an admin must configure credentials first).以下の /api/v1/tools/* はすべて GET でデータを変更せず、ログイン済みの任意のアカウント（読み取り専用トークンを含む）で使えます。dns-lookup と dns-mail はサーバーから DNS リゾルバに問い合わせ、geoip は MaxMind GeoLite2 の Web サービスを呼びます（管理者が先に認証情報を設定する必要があります）。

網路診斷 tools/net/*（會實際送封包）Network diagnostics tools/net/* (send real traffic)ネットワーク診断 tools/net/*（実際にパケットを送ります）

curl -X POST https://ipam.example.com/api/v1/tools/net/tcp \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"targets":"192.0.2.10, 192.0.2.11","ports":[22,443]}'

10IP 探測IP probeIP プローブ

IP 探測是管理員限定的單次深度識別：由該位址所屬子網路的掃描代理，對目標跑一次 nmap 服務偵測（前面先做反解、NetBIOS、mDNS），再用已安裝的 Recog 指紋庫把結果歸納成作業系統與產品。jt-ipam 伺服器本身不會連到目標。代理要跑的腳本清單寫死在代理程式裡（banner、http-title、http-server-header、ssl-cert、ssh-hostkey、smb-os-discovery、rdp-ntlm-info），伺服器改不了。banner 只跑在 FTP、SSH、Telnet、SMTP、POP3、IMAP 的埠（代理 1.18.1 起）：nmap 的 banner 在不先說話的埠上會改用 TLS 再連一次，印表機的 RAW 列印埠（9100）會把那段 TLS 交握當成列印工作印出來。服務偵測可能觸發 IDS 告警，請只對你負責的主機使用。 The IP probe is an admin-only, single deep identification: the scan agent of the address's subnet runs one nmap service scan against the target (after reverse DNS, NetBIOS and mDNS lookups), and the result is summarised into OS and product using the installed Recog fingerprint database. The jt-ipam server never connects to the target itself. The list of scripts is hard-coded in the agent (banner, http-title, http-server-header, ssl-cert, ssh-hostkey, smb-os-discovery, rdp-ntlm-info) and cannot be changed by the server. banner runs only on FTP, SSH, Telnet, SMTP, POP3 and IMAP ports (agent 1.18.1 and later): on a port that does not speak first, nmap's banner retries over TLS, and a printer's raw print port (9100) prints that TLS handshake as a job. Service detection may trigger IDS alerts; only probe hosts you are responsible for.IP プローブは管理者限定の、一回ごとの詳細な識別です。そのアドレスが属するサブネットのスキャンエージェントが、対象に nmap のサービス検出を一度実行し（その前に逆引き、NetBIOS、mDNS を照会）、導入済みの Recog フィンガープリントで OS と製品にまとめます。jt-ipam サーバー自身が対象に接続することはありません。実行するスクリプトの一覧はエージェント側に固定されており（banner、http-title、http-server-header、ssl-cert、ssh-hostkey、smb-os-discovery、rdp-ntlm-info）、サーバーからは変更できません。banner は FTP・SSH・Telnet・SMTP・POP3・IMAP のポートだけで実行します（エージェント 1.18.1 以降）。nmap の banner は先に話さないポートでは TLS で接続し直し、プリンターの RAW 印刷ポート（9100）はその TLS ハンドシェイクを印刷ジョブとして印刷してしまうためです。サービス検出は IDS の警告を招くことがあるため、担当しているホストにだけ使ってください。

常見的拒絕：位址不在任何管理中的子網路 → 404 identify_not_managed；不是單一位址或是網路/廣播位址 → 400 identify_bad_target；重疊網段分屬不同代理 → 409 identify_ambiguous；子網路沒有啟用中的掃描代理 → 409 identify_no_agent；同一位址已有探測在跑 → 409 identify_in_progress。每個代理最多 20 件待處理工作，代理領走後 9 分鐘沒回報就作廢。每次發起都會寫稽核。tools/net/agent-probe 不接受 identify，只能從這裡發起。 Common refusals: address outside every managed subnet → 404 identify_not_managed; not a single address, or the network/broadcast address → 400 identify_bad_target; overlapping subnets served by different agents → 409 identify_ambiguous; no enabled scan agent on the subnet → 409 identify_no_agent; a probe already running for that address → 409 identify_in_progress. Each agent holds at most 20 pending jobs, and a claimed job with no report after 9 minutes expires. Every start is audited. tools/net/agent-probe refuses identify; start it only from these endpoints.よくある拒否：管理中のどのサブネットにも含まれない → 404 identify_not_managed、単一のアドレスでない・ネットワーク/ブロードキャストアドレス → 400 identify_bad_target、重複するサブネットが別々のエージェントの担当 → 409 identify_ambiguous、サブネットに有効なスキャンエージェントが無い → 409 identify_no_agent、同じアドレスのプローブが実行中 → 409 identify_in_progress。エージェントごとの待機ジョブは最大 20 件で、受け取られてから 9 分以内に報告が無ければ無効になります。開始のたびに監査に記録されます。tools/net/agent-probe は identify を受け付けないため、ここからだけ開始できます。

curl -X POST https://ipam.example.com/api/v1/identify/ip/192.0.2.50 \
  -H "Authorization: Bearer $TOKEN"

11IP 變更評估IP change assessmentIP 変更評価

改 IP、除役裝置、交換器維護或節點停機之前的評估：找出引用、判定影響、列出資料不足的項目與待辦。引用的來源包括 IPAM（新位址的記錄、冷卻期、待審核的 IP 申請、IP 範圍）、子網路的閘道與 DNS、DNS/DHCP（含掃描代理看到的 DHCP 伺服器與它發的預設閘道）、防火牆與 NAT、監控、虛擬化、憑證、VPN 端點、線路、跳板主機、各整合與 jt-ipam 系統設定（LDAP、SMTP、AI 模型、稽核轉送、Webhook）的連線位址、服務的依賴與端點（除役時照服務的依賴判定哪些服務會中斷），以及說明欄裡的文字線索。評估只讀，不會改任何設備、不會推送 DNS/DHCP/防火牆設定。功能預設關閉，管理員以 PUT /api/v1/change-impact/settings（或系統設定頁）打開；關閉時下列端點回 403 impact_feature_disabled。An assessment before renumbering an IP, decommissioning a device, switch maintenance or node downtime: it finds references, judges the impact, and lists data gaps and tasks. References come from IPAM (records at the new address, cooldowns, pending IP requests, IP ranges), subnet gateways and DNS servers, DNS/DHCP (including DHCP servers seen by scan agents and the default gateway they hand out), firewalls and NAT, monitoring, virtualization, certificates, VPN endpoints, circuits, jump hosts, the connection addresses of integrations and of jt-ipam's own settings (LDAP, SMTP, AI model, audit forwarding, webhooks), service dependencies and endpoints (a decommission works out which services break from their dependencies), and text hints in descriptions. It is read-only: no device is changed and no DNS, DHCP or firewall setting is pushed. It is off by default; an admin turns it on with PUT /api/v1/change-impact/settings (or the system settings page). While off, the endpoints below return 403 impact_feature_disabled.ログイン中のアカウントは enabled、ai_available を取得できます。管理者は config も取得・変更できます（スイッチ、AI、有効時間、保存日数、上限）。監査に記録されます。確認者は下の /change-impact/review-policy（画面では「申請の承認設定」）で設定します。旧フィールド reviewer_user_ids/reviewer_group_ids/allow_self_review も書き込めて、確認の設定に反映されます。リストには存在するユーザーとグループだけが残ります

資料來源（M1）：IPAM 本身（位址、子網路閘道與 DNS 伺服器、冷卻期、跳板、整合端點、說明裡的文字線索）、DNS 的 A/AAAA/PTR、DHCP 保留、租約與發放範圍、OPNsense、pfSense、FortiGate（依 VDOM）、Palo Alto（依 vsys）、Check Point（依網域與政策套件）、MikroTik 的規則與別名/位址物件（群組遞迴並偵測循環，停用與反向比對分開）、NAT、LibreNMS、Zabbix、Wazuh、OCS、RustDesk、Proxmox VE 與 ESXi 的虛擬機、憑證的 IP SAN。尚未支援、會列成資料不足的：DNS 的 CNAME 與 view、DHCP 租約到期時間、對不上 IP 記錄的租約與 NAT 位址、Proxmox VE 防火牆、虛擬化 HA。Data sources (M1): IPAM itself (addresses, subnet gateways and DNS servers, cooldowns, jump hosts, integration endpoints, text hints in descriptions), DNS A/AAAA/PTR, DHCP reservations, leases and pools, rules and aliases/address objects on OPNsense, pfSense, FortiGate (per VDOM), Palo Alto (per vsys), Check Point (per domain and policy package) and MikroTik (groups resolved recursively with cycle detection; disabled and negated rules kept apart), NAT, LibreNMS, Zabbix, Wazuh, OCS, RustDesk, Proxmox VE and ESXi VMs, and certificate IP SANs. Not supported yet and reported as gaps: DNS CNAMEs and views, DHCP lease expiry, leases and NAT addresses without an IP record, the Proxmox VE firewall, and virtualization HA.データソース（M1）：IPAM 自体（アドレス、サブネットのゲートウェイと DNS サーバー、クールダウン、踏み台、連携の接続先、説明文中のテキスト）、DNS の A/AAAA/PTR、DHCP の予約・リース・配布範囲、OPNsense・pfSense・FortiGate（VDOM ごと）・Palo Alto（vsys ごと）・Check Point（ドメインとポリシーパッケージごと）・MikroTik のルールとエイリアス/アドレスオブジェクト（グループは再帰的に展開し循環を検出。無効なルールと否定条件は区別）、NAT、LibreNMS、Zabbix、Wazuh、OCS、RustDesk、Proxmox VE と ESXi の仮想マシン、証明書の IP SAN。未対応でデータの欠落として表示するもの：DNS の CNAME と view、DHCP リースの期限、IP レコードに対応しないリースと NAT のアドレス、Proxmox VE のファイアウォール、仮想化の HA。

MCP 工具：impact_list_plans、impact_get_run、impact_list_findings、impact_get_evidence、impact_prepare_scenario（只驗證、不寫入，回伺服器簽發的 draft_token；四種情境都可以，維護與停機可帶 mode、also_down）；impact_create_plan（要帶 draft_token，內容被改過就拒絕）、impact_start_run、impact_accept_task_draft 屬於異動工具，只給管理員、唯讀金鑰不能呼叫。功能關閉時這些工具不出現在清單裡。MCP tools: impact_list_plans, impact_get_run, impact_list_findings, impact_get_evidence, impact_prepare_scenario (validates only, writes nothing, returns a server-signed draft_token; all four scenarios, with mode and also_down for maintenance and downtime); impact_create_plan (needs the draft_token and refuses a changed payload), impact_start_run and impact_accept_task_draft change data, so they are admin-only and blocked for read-only keys. While the feature is off, the tools are not listed.MCP ツール：impact_list_plans、impact_get_run、impact_list_findings、impact_get_evidence、impact_prepare_scenario（検証のみで書き込まず、サーバーが署名した draft_token を返します。4 つのシナリオすべてに対応し、メンテナンスと停止では mode と also_down を指定できます）。impact_create_plan（draft_token が必要で、内容が変わっていれば拒否）、impact_start_run、impact_accept_task_draft はデータを変更するツールのため管理者専用で、読み取り専用キーでは使えません。機能が無効の間、これらのツールは一覧に出ません。

12整合Integrations連携

每種整合的端點形狀大致相同：清單與 POST 建立、PATCH/DELETE 單筆、POST …/{id}/test（連線診斷）、POST …/{id}/sync（立即同步）。多數同步走背景作業並回 task_id（用 GET /api/v1/tasks/{task_id} 查進度）；ESXi 與 pfSense 的同步是同步執行，上游出錯回 502。密碼與 API 金鑰只寫不讀，讀取時最多只看到 has_password 之類的旗標。設定一律需要 admin；讀取權限見下表。 Every integration has roughly the same shape: a list and POST to create, PATCH/DELETE per item, POST …/{id}/test (connection diagnostics) and POST …/{id}/sync (sync now). Most syncs run as a background task and return a task_id (follow it with GET /api/v1/tasks/{task_id}); ESXi and pfSense sync synchronously and return 502 on an upstream error. Passwords and API keys are write-only; reads show at most a flag such as has_password. Configuration always requires admin; read access is in the table below.どの連携もエンドポイントの形はほぼ同じです。一覧と POST での作成、単件の PATCH/DELETE、POST …/{id}/test（接続診断）、POST …/{id}/sync（即時同期）。多くの同期はバックグラウンド処理で task_id を返します（進捗は GET /api/v1/tasks/{task_id}）。ESXi と pfSense の同期は同期実行で、上流のエラー時は 502 を返します。パスワードと API キーは書き込み専用で、読み取り時は has_password のようなフラグが見える程度です。設定には常に admin が必要で、読み取り権限は下表のとおりです。

作業清單 GET /api/v1/tasks 可帶 status_in（逗號分隔）、kind、trigger（manual/scheduled）、q（搜尋類型、目標、錯誤訊息，不分大小寫，% 與 _ 照字面比對）與 active_only；GET /api/v1/tasks/kinds 回看得到的作業裡出現過的類型。排程同步、代理回報（rustdesk.sync、isc_dhcp.sync）與資料庫更新（oui.refresh、recog.refresh、geoip.refresh）每個來源只保留一列 trigger=scheduled，每次更新同一列；手動操作每次一列。 The task list GET /api/v1/tasks accepts status_in (comma separated), kind, trigger (manual/scheduled), q (searches type, target and error, case insensitive, with % and _ matched literally) and active_only; GET /api/v1/tasks/kinds returns the types that appear among the tasks you can see. Scheduled syncs, agent reports (rustdesk.sync, isc_dhcp.sync) and database refreshes (oui.refresh, recog.refresh, geoip.refresh) keep one trigger=scheduled row per source that every run updates; manual actions add one row each time.作業一覧 GET /api/v1/tasks には status_in（カンマ区切り）、kind、trigger（manual/scheduled）、q（種類・対象・エラーを大文字小文字を区別せず検索し、% と _ は文字どおりに照合）、active_only を指定できます。GET /api/v1/tasks/kinds は見える作業に現れた種類を返します。定期同期、エージェントの報告（rustdesk.sync、isc_dhcp.sync）、データベースの更新（oui.refresh、recog.refresh、geoip.refresh）はソースごとに trigger=scheduled の行を 1 行だけ持ち、実行のたびに同じ行を更新します。手動操作は毎回 1 行ずつ追加されます。

ISOinsight 整合（Beta，/isoinsight）ISOinsight integration (Beta, /isoinsight)ISOinsight 連携（Beta、/isoinsight）

jt-ipam 伺服器登入 ISOinsight 的網頁介面，再以同一個 Session 讀 /isosvc?act=DhcpLease。原廠說明的方式（新增時的預設）是 POST JSON 到 /logon 取得 SessionID，以網址參數 sessionid 帶給租約網址：auth_mode=token、token_path=SessionID、token_in=query、token_param=sessionid（token_in=header 時改用 token_header 與 token_prefix）。GET 或 POST form/JSON、Cookie 或 Token 都由管理員明確選擇，不會自動切換。網址裡的 Session ID 不會出現在連線記錄與日誌。只做登入與查詢，不改設備的 DHCP 設定或租約。密碼加密保存、寫入後不回傳（只有 has_password）；Cookie 與 Token 只在單次工作的記憶體裡，不存資料庫。待真機驗證：登入回應的格式（Cookie 或 Token 欄位）、GET 與 POST 何者可用、租約是否全量與時區，這裡的設定都只是相容性選項。 The jt-ipam server logs in to the ISOinsight web interface, then reads /isosvc?act=DhcpLease with the same session. The vendor's method (the default for new sources) is to POST JSON to /logon for a SessionID and pass it to the lease URL as the sessionid query parameter: auth_mode=token, token_path=SessionID, token_in=query, token_param=sessionid (with token_in=header, token_header and token_prefix are used instead). GET or POST form/JSON and cookie or token are explicit admin choices and never switch automatically. A session ID in the URL never appears in the connection trace or the logs. It only logs in and reads; it never changes DHCP settings or leases on the device. The password is stored encrypted and never returned (only has_password); cookies and tokens live only in the memory of a single job and are never stored. Pending verification on a real device: the login response (cookie or token field), whether GET or POST works, whether the lease list is complete, and the time zone; these settings are compatibility options only.jt-ipam サーバーが ISOinsight の Web インターフェイスにログインし、同じセッションで /isosvc?act=DhcpLease を読みます。メーカーが案内している方式（新規作成時の既定値）は、/logon に JSON を POST して SessionID を取得し、URL パラメーター sessionid としてリース URL に付ける方式です：auth_mode=token、token_path=SessionID、token_in=query、token_param=sessionid（token_in=header のときは token_header と token_prefix を使用）。GET か POST form/JSON か、Cookie かトークンかは管理者が明示的に選び、自動では切り替えません。URL 内のセッション ID は接続記録とログに出ません。ログインと参照のみで、機器の DHCP 設定やリースは変更しません。パスワードは暗号化して保存し、書き込み後は返しません（has_password のみ）。Cookie とトークンは 1 回のジョブのメモリ内だけにあり、保存しません。実機での検証待ち：ログイン応答の形式（Cookie またはトークン項目）、GET と POST のどちらが使えるか、リースが全件か、タイムゾーン。ここの設定は互換性のための選択肢にすぎません。

合併規則：只有租約期間內、沒有 MAC 衝突、唯一配對到允許子網路的那一筆會碰 IP 記錄；MAC 與主機名稱照既有的來源優先序（人工維護的值不會被蓋），名稱空白不清除、MAC 不合法不寫，租約有效不更新上線時間。不依「這次沒出現」推定釋放，租約只依到期時間管理；空清單、失敗、停用或刪除來源都不刪正式 IP。登入失敗後排程自動暫停（避免反覆送出帳密觸發帳號鎖定），修改設定或測試成功後解除；429 依 Retry-After 延後。AI 對話與 MCP 用唯讀工具 list_isoinsight_leases 查同一份資料，權限與這個端點相同。 Merge rules: only a lease that is within its lease period, has no MAC conflict and matches exactly one allowed subnet touches the IP record; MAC and host name follow the existing source precedence (values maintained by people are never overwritten), an empty name clears nothing, an invalid MAC is not written, and a valid lease never updates the last-seen time. Absence from a response never releases a lease; leases are managed by their end time only. An empty list, a failure, or disabling or deleting the source never deletes IP records. After a login failure the schedule pauses on its own (so credentials are not sent again and again, which could lock the account) until the settings change or a test succeeds; HTTP 429 postpones it by Retry-After. AI chat and MCP read the same data with the read-only tool list_isoinsight_leases, with the same permissions as this endpoint.統合のルール：リース期間内で MAC の競合がなく、許可されたサブネットに一意に対応したものだけが IP レコードに反映されます。MAC とホスト名は既存のソース優先順位に従い（人が管理している値は上書きしません）、空の名前は消さず、不正な MAC は書かず、有効なリースでも最終確認時刻は更新しません。応答に現れなかったことを理由にリースを解放せず、リースは期限時刻だけで管理します。空のリスト、失敗、ソースの無効化や削除で IP レコードを削除することはありません。ログインに失敗するとスケジュールは自動で一時停止し（資格情報を繰り返し送ってアカウントがロックされないように）、設定の変更またはテスト成功で解除されます。HTTP 429 では Retry-After に従って延期します。AI チャットと MCP は読み取り専用ツール list_isoinsight_leases で同じデータを参照し、権限はこのエンドポイントと同じです。

curl -X POST https://ipam.example.com/api/v1/isoinsight/sources \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"iso-hq","base_url":"https://192.0.2.10","login_method":"POST","post_format":"form",
       "username":"ipam-ro","password":"...","scope_all":true,
       "source_timezone":"Asia/Taipei","timezone_confirmed":true}'

SNMP 收集（/snmp）SNMP collection (/snmp)SNMP 収集（/snmp）

伺服器不連設備：負責的掃描代理（1.19.0 以上，工具盤點要有 snmpbulkwalk，也就是裝了 net-snmp 用戶端工具）只對指派給它的收集目標做唯讀 SNMP 讀取（GET、GETNEXT、GETBULK），OID 是代理裡寫死的允許清單：路由器的 ARP 表（IP-MIB ipNetToPhysicalTable，沒有時用 ipNetToMediaTable）、交換器的 MAC 表（Q-BRIDGE-MIB，沒有時用 BRIDGE-MIB；Cisco 依 vtpVlanState 逐個 VLAN 讀，v2c 用 community@vlan、v3 用 context vlan-N）、LLDP 與 CDP 鄰居、介面（IF-MIB）與介面位址。收集目標就是既有的裝置（一台裝置一筆），管理位址用裝置的主要 IP，必要時填 ip_override。憑證集中管理：v2c 社群字串，或 v3 帳號、安全等級（authPriv/authNoPriv，不開放 noAuthNoPriv）、認證（MD5/SHA/SHA-224/SHA-256/SHA-384/SHA-512）與加密（DES/AES-128/AES-192/AES-256）。v2c 的社群字串在網路上是明文。全部端點限 admin。 The server never connects to the devices: the responsible scan agent (1.19.0 or later, with snmpbulkwalk in its tool inventory, that is, the net-snmp client tools installed) reads only the collection targets assigned to it, read-only (GET, GETNEXT, GETBULK), from an OID allowlist hard-coded in the agent: router ARP tables (IP-MIB ipNetToPhysicalTable, falling back to ipNetToMediaTable), switch MAC tables (Q-BRIDGE-MIB, falling back to BRIDGE-MIB; on Cisco one VLAN at a time from vtpVlanState, community@vlan for v2c and context vlan-N for v3), LLDP and CDP neighbors, interfaces (IF-MIB) and interface addresses. A collection target is an existing device (one per device); the management address is the device's primary IP unless ip_override is set. Credentials are managed centrally: a v2c community, or a v3 user with a security level (authPriv/authNoPriv; noAuthNoPriv is not offered), authentication (MD5/SHA/SHA-224/SHA-256/SHA-384/SHA-512) and privacy (DES/AES-128/AES-192/AES-256). A v2c community travels in plain text. Every endpoint is admin-only.サーバーは機器に接続しません。担当のスキャンエージェント（1.19.0 以降で、ツール一覧に snmpbulkwalk があるもの、つまり net-snmp のクライアントツールを導入済み）が、割り当てられた収集対象だけを読み取り専用（GET・GETNEXT・GETBULK）で、エージェントに固定で書かれた OID の許可リストから読みます：ルーターの ARP テーブル（IP-MIB ipNetToPhysicalTable、なければ ipNetToMediaTable）、スイッチの MAC テーブル（Q-BRIDGE-MIB、なければ BRIDGE-MIB。Cisco は vtpVlanState から VLAN ごとに読み、v2c は community@vlan、v3 はコンテキスト vlan-N）、LLDP と CDP のネイバー、インターフェイス（IF-MIB）とインターフェイスのアドレス。収集対象は既存の機器（機器ごとに 1 件）で、管理アドレスは機器のプライマリ IP、必要なら ip_override を指定します。認証情報は一元管理です：v2c のコミュニティ、または v3 のユーザー、セキュリティレベル（authPriv/authNoPriv。noAuthNoPriv は選べません）、認証（MD5/SHA/SHA-224/SHA-256/SHA-384/SHA-512）と暗号化（DES/AES-128/AES-192/AES-256）。v2c のコミュニティはネットワーク上を平文で流れます。すべてのエンドポイントは admin 限定です。

寫入規則：ARP 只補既有 IP 記錄的 MAC（MAC 來源優先序的 snmp，與防火牆的 ARP 表同一級），同一個位址在好幾個子網路都有（重疊網段）就不寫。上線證據分兩個來源：arp:snmp（ipNetToMediaTable 與不是 reachable 的項目，沒有時間，只補 MAC、不會過期、預設不採信）、arp:snmp_live（ipNetToPhysicalState 為 reachable 的動態項目，會過期、預設採信，升級前存過的上線來源設定也會自動加入）；介面位址所在介面 ifOperStatus 為 up 時記 iface:snmp（會過期）。MAC 表寫進 fdb_entries（source=snmp、switch_device_id 是目標裝置），跟 LibreNMS、MikroTik 的列一起推交換器位置與拓樸；鄰居畫成拓樸的交換器連線；介面寫進裝置連接埠（VLAN、loopback 等邏輯介面不寫）。舊資料只在該區段完整讀到時才清，部分失敗只新增與更新。auto_create_ips 開了才依 ARP 建立 IPAM 沒有的位址（discovery_source=snmp_arp，與 LibreNMS 依 ARP 建立同一套把關：唯一且最精確的既有子網路、略過代理 ARP、冷卻期與 DHCP 動態範圍、一輪最多 500 筆；沒有時間的項目要交換器 MAC 表 24 小時內也看過，reachable 的項目不必）。 Write rules: ARP only fills the MAC of existing IP records (MAC source precedence snmp, at the same level as firewall ARP tables), and nothing is written when the same address exists in several subnets (overlapping networks). Liveness evidence comes in two sources: arp:snmp (ipNetToMediaTable and entries that are not reachable; no time, so it only fills the MAC, never expires and is not trusted by default) and arp:snmp_live (dynamic entries whose ipNetToPhysicalState is reachable; expires and is trusted by default, also on sites that saved their liveness sources before the upgrade). An interface address whose interface has ifOperStatus up is recorded as iface:snmp (expires). The MAC table goes to fdb_entries (source=snmp, switch_device_id = the target device) and works with the LibreNMS and MikroTik rows for switch positions and the topology; neighbors become switch links in the topology; interfaces become device ports (logical interfaces such as VLANs and loopbacks are skipped). Old data is cleared only after a complete read of that section; a partial failure only adds and updates. With auto_create_ips on, ARP entries the IPAM does not have are created (discovery_source=snmp_arp) with the same guards as the LibreNMS ARP auto-create: a unique, most specific existing subnet, no proxy ARP, no cooldown or DHCP dynamic ranges, at most 500 per round; entries without a time need the switch MAC table to have seen the MAC within 24 hours, reachable entries do not.書き込みのルール：ARP は既存の IP レコードの MAC だけを補います（MAC ソースの優先順位は snmp で、ファイアウォールの ARP テーブルと同じ段階）。同じアドレスが複数のサブネットにある場合（重複ネットワーク）は書きません。稼働の根拠は 2 つのソースに分かれます：arp:snmp（ipNetToMediaTable と reachable でないエントリ。時刻がないため MAC を補うだけで、期限切れにならず、既定では採用しません）と arp:snmp_live（ipNetToPhysicalState が reachable の動的エントリ。期限があり、既定で採用し、アップグレード前に稼働ソースを保存したサイトでも自動で加わります）。インターフェイスの ifOperStatus が up のインターフェイスアドレスは iface:snmp（期限あり）として記録します。MAC テーブルは fdb_entries（source=snmp、switch_device_id は対象機器）に入り、LibreNMS や MikroTik の行と一緒にスイッチの位置とトポロジーに使われます。ネイバーはトポロジーのスイッチ間リンクになり、インターフェイスは機器ポートになります（VLAN やループバックなどの論理インターフェイスは除外）。古いデータはその区分を最後まで読めたときだけ消し、一部失敗した場合は追加と更新のみです。auto_create_ips を有効にすると、IPAM にない ARP のアドレスを作成します（discovery_source=snmp_arp）。LibreNMS の ARP による自動作成と同じ確認を行います：一意で最も詳細な既存サブネット、プロキシ ARP・クールダウン・DHCP 動的範囲は除外、1 回最大 500 件。時刻のないエントリは 24 時間以内にスイッチの MAC テーブルにも現れている必要があり、reachable のエントリは不要です。

curl -X POST https://ipam.example.com/api/v1/snmp/credentials \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"core-v3","is_default":true,"version":"v3","username":"ipam-ro",
       "security_level":"authPriv","auth_protocol":"SHA-256","auth_passphrase":"...",
       "priv_protocol":"AES-128","priv_passphrase":"..."}'

curl -X POST https://ipam.example.com/api/v1/snmp/targets \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"device_id":"<device uuid>","collector":"auto","collect_fdb":true}'

未安裝代理的 IP（/wazuh/missing-agents、/ocs/missing-agents）IPs without an agent (/wazuh/missing-agents, /ocs/missing-agents)エージェント未導入の IP（/wazuh/missing-agents・/ocs/missing-agents）

不帶 page 時回整份清單（陣列，與舊版相同）。大站台可能有數萬筆，請改帶 page：由伺服器篩選、排序、分頁，回 {"items":[…],"total":…,"total_all":…,"facets":{…}}。total 是符合篩選的筆數、total_all 是全部缺口，facets 列出可用的區段、子網路（選了區段就只列該區段的）、單位與上線狀態。每筆多一個 status（online/stale/offline/unknown），判斷規則與 IP 清單的燈號相同；另帶 device_kind、device_model（掃描代理判讀出的設備類型與型號）。 Without page the full list comes back (an array, as before). Large sites can have tens of thousands of rows, so pass page: the server filters, sorts and pages, returning {"items":[…],"total":…,"total_all":…,"facets":{…}}. total counts rows matching the filters and total_all counts every gap; facets lists the available sections, subnets (only those in the chosen section, if any), units and liveness states. Each row gains a status (online/stale/offline/unknown) decided by the same rule as the lights in the IP list, plus device_kind and device_model (the device type and model the scan agent identified).page を付けないと一覧全体（配列、従来どおり）を返します。大規模なサイトでは数万行になるため、page を付けてください。サーバー側で絞り込み・並べ替え・ページングを行い、{"items":[…],"total":…,"total_all":…,"facets":{…}} を返します。total は条件に合う件数、total_all は未導入の全件数です。facets には選べるセクション、サブネット（セクションを選んだ場合はその配下のみ）、単位、稼働状態が入ります。各行には status（online/stale/offline/unknown）が付き、判定規則は IP 一覧のランプと同じです。各行には device_kind・device_model（スキャンエージェントが判定した機器タイプと型番）も含まれます。

算好的缺口在伺服器上保留最多 60 秒（IP 或代理資料一有變動就重算），翻頁與換篩選不必每次重算。The computed gaps are kept on the server for up to 60 seconds (recomputed as soon as IP or agent data changes), so paging and changing filters do not recompute each time.算出した未導入の一覧はサーバー側で最長 60 秒保持され（IP やエージェントのデータが変わるとすぐ再計算）、ページ送りや条件変更のたびに再計算はしません。

curl -G https://ipam.example.com/api/v1/wazuh/missing-agents \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "page=1" --data-urlencode "page_size=100" \
  --data-urlencode "status=online" --data-urlencode "sort=hostname"

13AI、事件規則與跳板AI, event rules & jump hostsAI・イベントルール・踏み台

AI 對話AI chatAI チャット

POST /api/v1/ai/chat（或 SSE 串流的 /ai/chat/stream）讓任何登入帳號用自然語言查 IPAM，前提是管理員已啟用 LLM；每個來源 IP 每分鐘最多 20 次。模型要呼叫會改資料的工具時，對話會先停下來等使用者確認，確認後由 POST /api/v1/ai/chat/confirm {"tool","args"} 執行。工具清單見 GET /api/v1/ai/tools（第 19 節）。 POST /api/v1/ai/chat (or /ai/chat/stream over SSE) lets any signed-in account query the IPAM in natural language, once an admin has enabled the LLM; each source IP may call it at most 20 times per minute. When the model wants a tool that changes data, the chat stops and waits for the user to confirm, and POST /api/v1/ai/chat/confirm {"tool","args"} then runs it. The tool list is at GET /api/v1/ai/tools (section 19).POST /api/v1/ai/chat（または SSE の /ai/chat/stream）で、ログイン済みの任意のアカウントが自然言語で IPAM に問い合わせられます。管理者が LLM を有効にしていることが前提で、送信元 IP ごとに毎分最大 20 回です。モデルがデータを変更するツールを使おうとすると会話は止まってユーザーの確認を待ち、確認後に POST /api/v1/ai/chat/confirm {"tool","args"} で実行されます。ツール一覧は GET /api/v1/ai/tools（第 19 節）です。

三個 SSE 串流（/ai/chat/stream、/investigate/narrative/stream、/tools/net/traceroute/stream）在等待模型或沒回應的躍點時，每 10 秒送一行 : keepalive，這是 SSE 規格的註解行，讓反向代理不會因為等太久而切斷連線。自己解析串流時只讀 data: 開頭的行，冒號開頭的行請略過。 The three SSE streams (/ai/chat/stream, /investigate/narrative/stream, /tools/net/traceroute/stream) send a : keepalive line every 10 seconds while waiting for the model or a silent hop. It is an SSE comment line that keeps reverse proxies from timing out the connection. If you parse the stream yourself, read only lines starting with data: and skip lines starting with a colon.3 つの SSE ストリーム（/ai/chat/stream、/investigate/narrative/stream、/tools/net/traceroute/stream）は、モデルや応答のないホップを待つ間、10 秒ごとに : keepalive の行を送ります。これは SSE 仕様のコメント行で、待ち時間が長くてもリバースプロキシに接続を切られないようにするためのものです。ストリームを自前で解析する場合は data: で始まる行だけを読み、コロンで始まる行は読み飛ばしてください。

兩個管理員用的模型檢查（都只讀、不改資料）：GET /api/v1/ai/embedding-check 實際取一次向量，回報維度是否與資料庫欄位相符；GET /api/v1/ai/thinking-check 用 AI 巡檢與判讀同一套「關閉思考」參數，對對話模型以及另外指定的巡檢、判讀模型各問一句極短的話，回 {"results":[{"role","model","ok","thinking","reasoning_chars","think_tag","empty_answer","seconds","rejected_params","error"}]}。thinking 為 true 表示伺服器或閘道沒有照做（回答是空的也算，有些閘道不把思考內容轉出來）。維度不合時 embedding-check 回 dim（模型實際回幾維）與 expected，error 為 null。GET /api/v1/ai/index-status（管理員，只讀資料庫、不呼叫模型）回語意搜尋的索引需不需要重建：{"model","last","counts","described","missing","needs_reindex","reason"}，reason 是 never（還沒用目前模型重建過）、model_changed（上次重建的模型跟現在不同）、missing（有說明卻沒有向量）或 null；last 是上次 POST /api/v1/ai/reindex 的模型、維度、時間與筆數。reindex 的回應多了 error_code、error_params（第一個失敗的錯誤代碼，例如 ai_embedding_dim_mismatch 帶 got、expected）。 Two admin-only model checks (read-only): GET /api/v1/ai/embedding-check fetches one vector and reports whether its dimension matches the database column; GET /api/v1/ai/thinking-check sends one very short question to the chat model and to any separately set audit or interpretation model, with the same thinking-off controls AI audit and interpretation use, and returns {"results":[{"role","model","ok","thinking","reasoning_chars","think_tag","empty_answer","seconds","rejected_params","error"}]}. thinking true means the server or gateway ignored the controls (an empty answer counts too: some gateways do not pass the reasoning through). On a dimension mismatch embedding-check returns dim (what the model actually returned) and expected, with error null. GET /api/v1/ai/index-status (admin; reads the database only, no model call) says whether the semantic search index needs a rebuild: {"model","last","counts","described","missing","needs_reindex","reason"}, where reason is never (not rebuilt with the current model), model_changed (the last rebuild used another model), missing (items with a description but no vector) or null; last is the model, dimension, time and counts of the last POST /api/v1/ai/reindex. The reindex response also carries error_code and error_params (the first failure's code, for example ai_embedding_dim_mismatch with got and expected).管理者向けのモデルチェックが二つあります（どちらも読み取りのみ）。GET /api/v1/ai/embedding-check はベクトルを一度取得し、次元がデータベースの列と一致するかを返します。GET /api/v1/ai/thinking-check は AI 監査・判定と同じ「思考を無効にする」パラメータで、チャットモデルと個別に指定した監査・判定モデルにごく短い質問を送り、{"results":[{"role","model","ok","thinking","reasoning_chars","think_tag","empty_answer","seconds","rejected_params","error"}]} を返します。thinking が true ならサーバーやゲートウェイが従っていません（回答が空の場合も含みます。思考内容を転送しないゲートウェイがあるため）。次元が合わない場合 embedding-check は dim（モデルが実際に返した次元）と expected を返し、error は null です。GET /api/v1/ai/index-status（管理者、データベースだけを読みモデルは呼ばない）はセマンティック検索のインデックスを再構築すべきかを返します：{"model","last","counts","described","missing","needs_reindex","reason"}。reason は never（現在のモデルで未再構築）、model_changed（前回の再構築とモデルが異なる）、missing（説明があるのにベクトルがない）または null。last は前回の POST /api/v1/ai/reindex のモデル・次元・時刻・件数です。reindex の応答には error_code と error_params（最初の失敗のエラーコード。例：ai_embedding_dim_mismatch と got・expected）も含まれます。

GET /api/v1/ai/semantic-search?q=&limit=：以描述的向量找相近的子網路、IP 與裝置（需要已啟用 LLM 與嵌入模型）。結果依呼叫者的可見範圍過濾（先過濾再取前幾筆），歸檔的子網路與其中的 IP 不列。GET /api/v1/ai/semantic-search?q=&limit=: finds subnets, IPs and devices with similar descriptions by vector (needs the LLM and an embedding model). Results are filtered by what the caller can see (filtered before the limit), and archived subnets and their IPs are left out.GET /api/v1/ai/semantic-search?q=&limit=：説明文のベクトルで似たサブネット、IP、機器を探します（LLM と埋め込みモデルが必要）。結果は呼び出し元が見える範囲だけに絞られ（絞り込んでから件数を制限）、アーカイブ済みのサブネットとその IP は含みません。

AI 巡檢（/ai-audit）AI audit (/ai-audit)AI 監査（/ai-audit）

全部限 admin，讀取也是。POST /api/v1/ai-audit/run 在背景跑一輪巡檢（已有一輪在跑時回 409），GET /ai-audit/status 看進度，GET /ai-audit/summary 與 GET /ai-audit/findings（status、severity、category，page_size 上限 200）看結論。POST /ai-audit/dismiss//restore {"ids":[…]} 忽略或還原（被忽略的同一問題之後會自動忽略），DELETE /ai-audit/findings 刪掉全部結論。 Admin-only, reads included. POST /api/v1/ai-audit/run starts a run in the background (409 if one is already running), GET /ai-audit/status shows progress, and GET /ai-audit/summary and GET /ai-audit/findings (status, severity, category; page_size up to 200) return the results. POST /ai-audit/dismiss / /restore {"ids":[…]} dismiss or restore findings (a dismissed issue stays dismissed in later runs), and DELETE /ai-audit/findings deletes every finding.読み取りを含めすべて admin 限定です。POST /api/v1/ai-audit/run でバックグラウンドで監査を実行し（実行中なら 409）、GET /ai-audit/status で進捗、GET /ai-audit/summary と GET /ai-audit/findings（status・severity・category、page_size の上限 200）で結果を見ます。POST /ai-audit/dismiss//restore {"ids":[…]} で無視・復帰（無視した同じ問題は以後も自動で無視）、DELETE /ai-audit/findings で全件を削除します。

單一 IP 調查（/investigate）Investigate one IP (/investigate)IP の調査（/investigate）

GET /api/v1/investigate?ip=… 把一個位址在各來源的事實彙整成一份檔案（dossier），任何登入帳號都能用，但只看得到可見子網路裡的資料；看不到或不存在時回 found: false，而不是 403。加 narrative=true 會另外請 LLM 寫一段解讀（lang 預設 zh-TW）。POST /api/v1/investigate/narrative/stream?ip=… 以 SSE 串流同一段解讀，事件的 type 依序是 thinking/content、最後 done（或 error），逾時 120 秒。要求解讀時會寫稽核。 GET /api/v1/investigate?ip=… gathers the facts every source has about one address into a dossier. Any signed-in account can use it, but only for data in subnets it can see; an address you cannot see, or that does not exist, returns found: false rather than 403. Add narrative=true to also ask the LLM for an interpretation (lang defaults to zh-TW). POST /api/v1/investigate/narrative/stream?ip=… streams the same interpretation over SSE: event type is thinking / content, then done (or error), with a 120-second timeout. Requests for an interpretation are audited.GET /api/v1/investigate?ip=… は、1 つのアドレスについて各ソースが持つ事実を 1 つの dossier にまとめます。ログイン済みの任意のアカウントで使えますが、見えるのは閲覧可能なサブネットのデータだけで、見えない・存在しないアドレスには 403 ではなく found: false を返します。narrative=true を付けると LLM による解説も付きます（lang の既定は zh-TW）。POST /api/v1/investigate/narrative/stream?ip=… は同じ解説を SSE で送り、イベントの type は thinking/content、最後に done（または error）で、タイムアウトは 120 秒です。解説を求めた場合は監査に記録されます。

dossier 依權限分三層，沒有資料的段落不會出現在回應裡（原本就有的 hostname_sources、arp、changes、dns、nat、firewall_rules 沒資料時是空清單）。看得到子網路就有：address、other_records（重疊網段的同位址紀錄）、hostname_sources、os_candidates、identity（device_kind/device_model/os_family/os_guess、類型依據 kind_reason（如 wazuh:windows、librenms:…、virt:pve-node、hostname:…）、網卡廠牌 nic_vendor、隨機 MAC mac_random）、monitoring（wazuh、librenms（裝置關聯或 primary IP）、zabbix）、agents（ocs 盤點與硬體、rustdesk 裝置含 key_problem）、virtualization（對到的 VM/容器，MAC 要對得上）、dhcp（in_lease/reserved/in_pool/excluded、reservations、leases、exclusions）、switch_ports（交換器 MAC 表，依交換器的裝置可見性）、fw_evidence（防火牆的 ARP/VPN/租約證據）、last_seen（各來源最後出現與上線判定）、arp、changes。全域讀取才有：dns、nat、firewall_rules（OPNsense）、firewall_refs（OPNsense、pfSense、FortiGate、Palo Alto、MikroTik 涵蓋這個位址的別名/位址物件與規則）、dhcp_rogue（觀測到的 DHCP 回應）、dhcp.pools（發放範圍的設定）。只有 admin：probe（最近一次 IP 探測）、anomalies（最近一次異常偵測中講到這個位址的）、ai_findings（未處理的 AI 巡檢發現）、console_sessions（最近 10 次主控台連線：誰、何時、從哪裡）。conflicts 是後端以固定規則算出的矛盾清單 [{code, params}]（names、stale_agent、duplicate、macs、macs_random、reservation_mac），畫面、匯出與 AI 解讀用的是同一份；主機名稱只差大小寫、結尾的點，或短名稱等於某個 FQDN 的第一段時算同一個名字。每段最多 20 筆。 The dossier has three tiers, and a section with no data is left out of the response (the original hostname_sources, arp, changes, dns, nat and firewall_rules are empty lists instead). Anyone who can see the subnet gets address, other_records (the same address in overlapping subnets), hostname_sources, os_candidates, identity (device_kind / device_model / os_family / os_guess, how the type was decided in kind_reason such as wazuh:windows, librenms:…, virt:pve-node or hostname:…, the NIC vendor nic_vendor and mac_random), monitoring (wazuh, librenms by device link or primary IP, zabbix), agents (ocs inventory and hardware, rustdesk devices with key_problem), virtualization (the matching VM or container; the MAC has to agree), dhcp (in_lease / reserved / in_pool / excluded, reservations, leases, exclusions), switch_ports (switch MAC tables, filtered by the switch's device visibility), fw_evidence (firewall ARP / VPN / lease evidence), last_seen (last seen by source with the liveness verdict), arp and changes. Global readers also get dns, nat, firewall_rules (OPNsense), firewall_refs (aliases, address objects and rules covering the address on OPNsense, pfSense, FortiGate, Palo Alto and MikroTik), dhcp_rogue (observed DHCP offers) and dhcp.pools (the pool configuration). Admins only: probe (the latest identify probe), anomalies (the latest anomaly run's findings about this address), ai_findings (open AI audit findings) and console_sessions (the last 10 console sessions: who, when, from where). conflicts is the list of contradictions the server computes with fixed rules, [{code, params}] (names, stale_agent, duplicate, macs, macs_random, reservation_mac); the screen, the exports and the AI interpretation all use it. Hostnames that differ only in letter case, a trailing dot, or a short name matching the first label of an FQDN count as one name. Each section has at most 20 rows.dossier は権限によって 3 段階に分かれ、データのないセクションは応答に含まれません（従来からある hostname_sources、arp、changes、dns、nat、firewall_rules は空の配列になります）。サブネットを閲覧できれば：address、other_records（重複するサブネットにある同じアドレス）、hostname_sources、os_candidates、identity（device_kind/device_model/os_family/os_guess、種別の根拠 kind_reason（wazuh:windows、librenms:…、virt:pve-node、hostname:… など）、NIC ベンダー nic_vendor、ランダム MAC の mac_random）、monitoring（wazuh、デバイスの関連付けまたはプライマリ IP による librenms、zabbix）、agents（ocs のインベントリとハードウェア、key_problem を含む rustdesk デバイス）、virtualization（対応する VM/コンテナ。MAC が一致する必要があります）、dhcp（in_lease/reserved/in_pool/excluded、reservations、leases、exclusions）、switch_ports（スイッチの MAC テーブル。スイッチのデバイス閲覧権限で絞り込み）、fw_evidence（ファイアウォールの ARP/VPN/リースの証拠）、last_seen（ソース別の最終確認と稼働判定）、arp、changes。グローバル閲覧権限があればさらに：dns、nat、firewall_rules（OPNsense）、firewall_refs（OPNsense、pfSense、FortiGate、Palo Alto、MikroTik でこのアドレスを含むエイリアス/アドレスオブジェクトとルール）、dhcp_rogue（観測された DHCP 応答）、dhcp.pools（配布範囲の設定）。admin のみ：probe（最新の IP 探査）、anomalies（最新の異常検知でこのアドレスに関するもの）、ai_findings（未処理の AI 監査の検出事項）、console_sessions（直近 10 回のコンソール接続：誰が、いつ、どこから）。conflicts はサーバーが固定のルールで算出した矛盾の一覧 [{code, params}]（names、stale_agent、duplicate、macs、macs_random、reservation_mac）で、画面、書き出し、AI の解説はすべてこれを使います。大文字と小文字、末尾のドット、または短い名前と FQDN の先頭ラベルだけが違うホスト名は同じ名前として扱います。各セクションは最大 20 件です。

curl -G https://ipam.example.com/api/v1/investigate \
  -H "Authorization: Bearer $TOKEN" --data-urlencode "ip=192.0.2.10"

事件規則（/event-rules）Event rules (/event-rules)イベントルール（/event-rules）

限 admin。一條規則是「事件 → 條件 → 動作」：events 是事件名稱清單（["*"] 表示全部），conditions 是結構化的 {field, op, value}（不支援運算式或正規表示式），actions 是 notify_admins 或 webhook（要帶既有 webhook 訂閱的 subscription_id）。GET/POST /api/v1/event-rules、PATCH/DELETE /event-rules/{id}；POST /event-rules/{id}/test {"event","payload"} 回傳每個條件的比對結果，不會執行動作。 Admin-only. A rule is "event → conditions → actions": events is a list of event names (["*"] means all), conditions are structured {field, op, value} objects (no expressions or regular expressions), and actions are notify_admins or webhook (with the subscription_id of an existing webhook subscription). GET/POST /api/v1/event-rules, PATCH/DELETE /event-rules/{id}; POST /event-rules/{id}/test {"event","payload"} returns how each condition evaluated and does not run the actions.admin のみ。ルールは「イベント → 条件 → アクション」です。events はイベント名の一覧（["*"] はすべて）、conditions は構造化された {field, op, value}（式や正規表現は使えません）、actions は notify_admins または webhook（既存の Webhook 購読の subscription_id が必要）です。GET/POST /api/v1/event-rules、PATCH/DELETE /event-rules/{id}。POST /event-rules/{id}/test {"event","payload"} は各条件の評価結果を返し、アクションは実行しません。

跳板主機（/jump-hosts）Jump hosts (/jump-hosts)踏み台ホスト（/jump-hosts）

限 admin。跳板是 SSH 跳板主機，作為六種網頁主控台（SSH、SFTP、RDP、VNC、noVNC、BMC）的連線出口，指定在子網路（jump_host_id），IP 也可以個別覆寫。GET/POST /api/v1/jump-hosts、PATCH/DELETE /jump-hosts/{id}、GET /jump-hosts/{id}/usage（哪些子網路與 IP 指向它）、POST /jump-hosts/{id}/test。主機金鑰還沒釘選前，test 只抓指紋、不送出帳密；用 PATCH 帶 host_key_fingerprint 釘選後才會真的被拿來連線。密碼與私鑰不會回傳（只有 has_secret）。刪除跳板會讓指向它的子網路與 IP 改回直連；停用的跳板則會拒絕連線（錯誤代碼 jump_host_disabled），不會改用直連，避免在重疊網段連錯主機。 Admin-only. A jump host is an SSH bastion used as the outbound route for the six web consoles (SSH, SFTP, RDP, VNC, noVNC, BMC). It is assigned on a subnet (jump_host_id) and can be overridden per IP. GET/POST /api/v1/jump-hosts, PATCH/DELETE /jump-hosts/{id}, GET /jump-hosts/{id}/usage (which subnets and IPs point to it), POST /jump-hosts/{id}/test. Until its host key is pinned, test only fetches the fingerprint and sends no credentials; it is used for connections only after you pin it with host_key_fingerprint via PATCH. Passwords and private keys are never returned (only has_secret). Deleting a jump host switches the subnets and IPs that used it back to direct connections; a disabled jump host refuses the connection instead (error code jump_host_disabled) and never falls back to direct, so overlapping networks cannot reach the wrong host.admin のみ。踏み台は SSH の踏み台ホストで、6 種類の Web コンソール（SSH、SFTP、RDP、VNC、noVNC、BMC）の接続経路になります。サブネットに割り当て（jump_host_id）、IP ごとに上書きもできます。GET/POST /api/v1/jump-hosts、PATCH/DELETE /jump-hosts/{id}、GET /jump-hosts/{id}/usage（参照しているサブネットと IP）、POST /jump-hosts/{id}/test。ホスト鍵を固定するまでは test はフィンガープリントを取得するだけで認証情報を送りません。PATCH で host_key_fingerprint を固定して初めて接続に使われます。パスワードと秘密鍵は返されません（has_secret のみ）。踏み台を削除すると、それを使っていたサブネットと IP は直接接続に戻ります。無効にした踏み台は接続を拒否し（エラーコード jump_host_disabled）、直接接続には切り替えません。重複するネットワークで別のホストにつながらないようにするためです。

經由掃描代理中繼主控台（console_agent_id）Console relay through a scan agent (console_agent_id)スキャンエージェント経由のコンソール中継（console_agent_id）

後端連不進客戶網路時，主控台（SSH、SFTP、RDP、VNC）可以由放在客戶端的掃描代理往外撥回來中繼。子網路與 IP 的 console_agent_id 指定經由哪一台代理，與 jump_host_id 擇一（只送一邊時另一邊自動清掉，兩邊都送非空值回 console_egress_both），而且必須是該子網路的掃描代理（否則 console_agent_not_assigned；換掉子網路的掃描代理時若出口還指著舊代理也會被擋）。兩道開關都開才會中繼：PUT /api/v1/system/console-security 的 console_relay、PATCH /scan-agents/{id} 的 relay_allowed；同一個端點另有 relay_ports（允許的埠，預設 "22,3389,5900-5910"，格式不對回 relay_ports_invalid）與 relay_max_sessions。代理主機不必設定任何東西；主機擁有者可以用 JT_IPAM_RELAY=0 在本機否決（回 relay_agent_host_off），或用 JT_IPAM_RELAY_PORTS/JT_IPAM_RELAY_MAX/JT_IPAM_RELAY_CIDRS 再限縮。GET /scan-agents 另回 relay_caps（代理回報的狀態與本機限縮，舊代理為 null）與 relay_active。任何一道沒開、代理離線、代理拒絕，主控台都會以 relay_* 錯誤代碼拒絕，不會改用直連；BMC 主控台不經由代理。When the server cannot reach into a customer network, consoles (SSH, SFTP, RDP, VNC) can be relayed by the scan agent on site, which dials out. console_agent_id on a subnet or IP picks the agent; it is one or the other with jump_host_id (sending only one clears the other; two non-empty values return console_egress_both) and must be that subnet's scan agent (otherwise console_agent_not_assigned; changing a subnet's scan agent while its exit still points at the old one is refused too). Both switches must be on: console_relay in PUT /api/v1/system/console-security and relay_allowed in PATCH /scan-agents/{id}; the same endpoint takes relay_ports (allowed ports, default "22,3389,5900-5910"; an invalid list returns relay_ports_invalid) and relay_max_sessions. Nothing needs to be set on the agent host; its owner can refuse locally with JT_IPAM_RELAY=0 (relay_agent_host_off) or narrow things with JT_IPAM_RELAY_PORTS / JT_IPAM_RELAY_MAX / JT_IPAM_RELAY_CIDRS. GET /scan-agents also returns relay_caps (the agent's state and local limits, null for older agents) and relay_active. If any switch is off, the agent is offline or it refuses, the console fails with a relay_* error code and never connects directly; the BMC console is never relayed.サーバーから顧客ネットワークに入れない場合、現地のスキャンエージェントが外向きに接続してコンソール（SSH、SFTP、RDP、VNC）を中継できます。サブネットと IP の console_agent_id で経由するエージェントを指定します。jump_host_id とはどちらか一方で（片方だけ送るともう片方は自動的に消え、両方に値を送ると console_egress_both）、そのサブネットのスキャンエージェントでなければなりません（違う場合は console_agent_not_assigned。出口が旧エージェントを指したままサブネットのスキャンエージェントを変更する場合も拒否）。2 つのスイッチの両方が必要です：PUT /api/v1/system/console-security の console_relay と PATCH /scan-agents/{id} の relay_allowed。同じエンドポイントで relay_ports（許可するポート、既定 "22,3389,5900-5910"。形式が不正なら relay_ports_invalid）と relay_max_sessions も設定できます。エージェントホスト側の設定は不要です。ホスト所有者は JT_IPAM_RELAY=0 でローカルに拒否（relay_agent_host_off）したり、JT_IPAM_RELAY_PORTS/JT_IPAM_RELAY_MAX/JT_IPAM_RELAY_CIDRS で絞ったりできます。GET /scan-agents は relay_caps（エージェントの状態とローカル制限、古いエージェントは null）と relay_active も返します。どれかが無効、エージェントがオフライン、またはエージェントが拒否した場合、コンソールは relay_* エラーコードで失敗し、直接接続にはなりません。BMC コンソールは中継しません。

代理協定（代理 1.15.0 起）：輪詢 /scan-agents/poll 時帶 X-Agent-Relay: enabled=1;ports=;max=0;pinned=0（enabled=0＝主機擁有者否決；ports/max 是本機限縮，空或 0＝不限）。回應的 relay_cidrs、relay_ports、relay_max 是網頁上允許的範圍（被指派掃描的子網路、允許的埠、同時上限），只有兩道開關都開時才有內容，否則是空的，代理什麼都不中繼（本機限縮只能縮小，伺服器無法放寬）。開一條主控台時伺服器派一筆 relay_open 工作（sid、單次票證、目標、埠，以及當下的範圍 scope，讓剛打開的開關立刻生效；這個種類無法經由工具頁的探測 API 建立），代理確認目標與埠、先連上目標，再撥 wss://<伺服器>/api/v1/scan-agents/relay/{sid}/ws，帶 X-Agent-Key 與 X-Relay-Ticket（30 秒、只能用一次、綁定這台代理）。伺服器在 127.0.0.1 開一個只接受第一個連線的埠交給主控台，雙向搬運二進位框；每條中繼都寫一筆稽核（console_relay：使用者、代理、目標、起訖、雙向位元組數、結束原因）。nginx 需要這個路徑的 WebSocket 設定，安裝與升級腳本會自動補上；外部反向代理請照 deploy/nginx/jt-ipam-external-proxy.conf 加上同樣的 location。Agent protocol (agent 1.15.0 and later): the agent polls /scan-agents/poll with X-Agent-Relay: enabled=1;ports=;max=0;pinned=0 (enabled=0 = the host owner refuses; ports / max are local limits, empty or 0 = none). relay_cidrs, relay_ports and relay_max in the reply are the scope allowed in the web UI (subnets it scans, allowed ports, session limit); they are filled only while both switches are on and empty otherwise, in which case the agent relays nothing (local limits can only narrow; the server cannot widen them). For each console the server queues a relay_open job (sid, one-time ticket, target, port, and the current scope so a switch that was just turned on works right away; this kind cannot be created through the Tools probe API). The agent checks target and port, connects to the target, then dials wss://<server>/api/v1/scan-agents/relay/{sid}/ws with X-Agent-Key and X-Relay-Ticket (30 seconds, single use, bound to that agent). The server opens a port on 127.0.0.1 that accepts only the first connection, hands it to the console and moves binary frames both ways; every relay writes an audit entry (console_relay: user, agent, target, start and end, bytes each way, reason). nginx needs a WebSocket location for this path; the install and upgrade scripts add it, and external reverse proxies should add the same location as deploy/nginx/jt-ipam-external-proxy.conf.エージェントのプロトコル（エージェント 1.15.0 以降）：/scan-agents/poll のポーリング時に X-Agent-Relay: enabled=1;ports=;max=0;pinned=0 を送ります（enabled=0 はホスト所有者による拒否、ports/max はローカル制限で、空または 0 は制限なし）。応答の relay_cidrs、relay_ports、relay_max は Web 画面で許可された範囲（スキャン対象のサブネット、許可ポート、同時接続上限）で、2 つのスイッチが両方オンのときだけ値が入り、それ以外は空でエージェントは何も中継しません（ローカル制限は狭めるだけで、サーバーからは広げられません）。コンソールを開くたびにサーバーは relay_open ジョブ（sid、ワンタイムチケット、接続先、ポート、オンにしたばかりのスイッチがすぐ効くよう現在の範囲 scope。この種類はツール画面のプローブ API からは作成できません）を登録します。エージェントは接続先とポートを確認して接続先に接続してから、X-Agent-Key と X-Relay-Ticket（30 秒、1 回限り、そのエージェント専用）を付けて wss://<サーバー>/api/v1/scan-agents/relay/{sid}/ws へ接続します。サーバーは最初の接続だけを受け付ける 127.0.0.1 のポートを開いてコンソールに渡し、バイナリフレームを双方向に転送します。中継ごとに監査記録（console_relay：ユーザー、エージェント、接続先、開始と終了、双方向のバイト数、終了理由）を残します。このパスには nginx の WebSocket 設定が必要で、インストールとアップグレードのスクリプトが自動で追加します。外部のリバースプロキシでは deploy/nginx/jt-ipam-external-proxy.conf と同じ location を追加してください。

14系統管理System administrationシステム管理

本節的端點都需要 admin。 Everything in this section requires admin.この節のエンドポイントはすべて admin が必要です。

權限授權（/system/permissions）Permission grants (/system/permissions)権限の付与（/system/permissions）

這就是第 1 節說的「在『管理 → 權限指派』授權物件」背後的 API。 This is the API behind "grant objects under Admin → Permissions" from section 1.第 1 節の「管理 → 権限でオブジェクトを許可する」操作の裏側にある API です。

POST 的欄位：object_type（customer/section/subnet/ip/device/rack/location）、object_id（UUID；null 表示該類型全部物件，也就是萬用授權）、principal_type（user/group）、principal_id、level（read/write/admin）。授權與撤銷都會寫稽核。 POST fields: object_type (customer / section / subnet / ip / device / rack / location), object_id (UUID; null means every object of that type, i.e. a wildcard grant), principal_type (user / group), principal_id, level (read / write / admin). Grants and revocations are audited.POST の項目：object_type（customer/section/subnet/ip/device/rack/location）、object_id（UUID。null はその種別のすべてのオブジェクト、つまりワイルドカードの許可）、principal_type（user/group）、principal_id、level（read/write/admin）。付与と取り消しは監査に記録されます。

curl -X POST https://ipam.example.com/api/v1/system/permissions \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"object_type":"subnet","object_id":"<subnet-uuid>",
       "principal_type":"user","principal_id":"<user-uuid>","level":"read"}'

帳號與群組本身在 /api/v1/users、/api/v1/groups（位移式分頁），群組成員用 POST/DELETE /api/v1/groups/{id}/members/{user_id}。稽核記錄在 GET /api/v1/audit（可依 object_type、object_id、actor_user_id、action、since、until 篩選，limit 上限 500），POST /api/v1/audit/verify 驗證稽核鏈是否完整。 Accounts and groups themselves live at /api/v1/users and /api/v1/groups (offset-based paging); group membership is POST/DELETE /api/v1/groups/{id}/members/{user_id}. The audit log is GET /api/v1/audit (filter by object_type, object_id, actor_user_id, action, since, until; limit up to 500), and POST /api/v1/audit/verify checks that the audit chain is intact.アカウントとグループ自体は /api/v1/users・/api/v1/groups（オフセット式ページング）、グループのメンバーは POST/DELETE /api/v1/groups/{id}/members/{user_id} です。監査ログは GET /api/v1/audit（object_type・object_id・actor_user_id・action・since・until で絞り込み、limit の上限 500）、POST /api/v1/audit/verify で監査チェーンが完全かを検証します。

登入安全、工作階段與備份加密Sign-in security, sessions and backup encryptionログインのセキュリティ・セッション・バックアップの暗号化

停用帳號（PATCH /api/v1/users/{id} {"is_active":false}）會撤銷工作階段與 API 權杖；管理員重設密碼會撤銷所有工作階段。每個人自己的工作階段在 GET /api/v1/auth/sessions、DELETE /auth/sessions/{id}、POST /auth/sessions/revoke-others；復原碼重新產生是 POST /auth/totp/recovery-codes（要帶目前密碼或驗證碼）。以上都寫稽核。 Deactivating an account (PATCH /api/v1/users/{id} {"is_active":false}) revokes its sessions and API tokens; an administrator password reset revokes all sessions. Everyone's own sessions are at GET /api/v1/auth/sessions, DELETE /auth/sessions/{id} and POST /auth/sessions/revoke-others; recovery codes are regenerated with POST /auth/totp/recovery-codes (with the current password or a code). All of these are audited.アカウントを無効化する（PATCH /api/v1/users/{id} {"is_active":false}）とセッションと API トークンが取り消され、管理者によるパスワードのリセットはすべてのセッションを取り消します。各自のセッションは GET /api/v1/auth/sessions・DELETE /auth/sessions/{id}・POST /auth/sessions/revoke-others、リカバリーコードの再生成は POST /auth/totp/recovery-codes（現在のパスワードまたはコードが必要）です。いずれも監査に記録されます。

系統匯出/匯入（/system/transfer）System export / import (/system/transfer)システムのエクスポート/インポート（/system/transfer）

把整台的設定與資料搬到另一台。流程：GET /system/transfer/schema 看有哪些範圍可以選、各有多少筆 → POST /system/transfer/export {"scope":[…],"passphrase":"…"}（密語至少 8 字，背景作業，回 task_id）→ GET /system/transfer/export/{task_id}/download 下載加密檔（還沒好回 409，保留 48 小時，過期回 410）。匯入：POST /system/transfer/import/analyze 是 multipart（file、passphrase，最大 512 MiB），不寫入，回一個 token 與內容摘要 → POST /system/transfer/import/apply {"token","passphrase","mode":"merge"|"replace","dry_run":false}。 Moves a whole instance's settings and data to another one. Export: GET /system/transfer/schema shows the selectable scopes and row counts → POST /system/transfer/export {"scope":[…],"passphrase":"…"} (passphrase at least 8 characters; background task, returns task_id) → GET /system/transfer/export/{task_id}/download fetches the encrypted file (409 until ready; kept 48 hours, then 410). Import: POST /system/transfer/import/analyze is multipart (file, passphrase, up to 512 MiB), writes nothing, and returns a token plus a summary → POST /system/transfer/import/apply {"token","passphrase","mode":"merge"|"replace","dry_run":false}.インスタンス全体の設定とデータを別のインスタンスへ移します。エクスポート：GET /system/transfer/schema で選べる範囲と件数を確認 → POST /system/transfer/export {"scope":[…],"passphrase":"…"}（パスフレーズは 8 文字以上。バックグラウンド処理で task_id を返す）→ GET /system/transfer/export/{task_id}/download で暗号化ファイルを取得（準備中は 409、48 時間保持、期限切れは 410）。インポート：POST /system/transfer/import/analyze は multipart（file・passphrase、最大 512 MiB）で何も書き込まず、token と内容の要約を返します → POST /system/transfer/import/apply {"token","passphrase","mode":"merge"|"replace","dry_run":false}。

版本與自我診斷Version and self-diagnosisバージョンと自己診断

GET /api/v1/system/version 回應用程式版本，以及套件、前端、主機、PostgreSQL 與選用工具的狀態；GET /system/version/check-latest 會對外連到 GitHub 查最新版。GET /api/v1/system/doctor 回一組 JSON 檢查項目（每項附修正建議），/system/doctor/report 是同樣內容的純文字版；GET /api/v1/system/doctor/stats 回各類資料的筆數（groups[].items[] 每項有 key、count、approx：大表逾時時是資料庫估計值），只在本機計算、不傳送到任何地方；GET /api/v1/system/doctor/storage 回容量用量：database（總大小、groups 依功能分類加總、tables 最大的幾張表，含索引與 TOAST）、directories（備份、程式與套件、資料目錄、日誌，approx 表示時間到沒量完、denied 表示有讀不到的檔案）與 disk，目錄大小快取幾分鐘，帶 refresh=true 重新量。後端看不到 systemd、nginx、備份等主機層面的狀態，那些請在主機上跑 jt-ipam.sh doctor。 GET /api/v1/system/version returns the application version plus package, frontend, host, PostgreSQL and optional-tool status; GET /system/version/check-latest makes an outbound request to GitHub for the latest release. GET /api/v1/system/doctor returns a set of JSON checks, each with a suggested fix, and /system/doctor/report is the same as plain text; GET /api/v1/system/doctor/stats returns record counts per kind (groups[].items[] with key, count and approx, true when a big table timed out and the database estimate is shown), counted locally and never sent anywhere; GET /api/v1/system/doctor/storage returns storage usage: database (total size, groups summed per feature, tables with the largest tables including indexes and TOAST), directories (backups, program and packages, data directory and logs; approx means the walk ran out of time, denied that some files were unreadable) and disk; directory sizes are cached for a few minutes, and refresh=true measures again. The backend cannot see host-level state such as systemd, nginx or backups; run jt-ipam.sh doctor on the host for those.GET /api/v1/system/version はアプリケーションのバージョンと、パッケージ・フロントエンド・ホスト・PostgreSQL・任意ツールの状態を返します。GET /system/version/check-latest は GitHub へ外部接続して最新版を確認します。GET /api/v1/system/doctor は修正案付きの JSON のチェック項目を返し、/system/doctor/report は同じ内容のテキスト版です。GET /api/v1/system/doctor/stats は種類ごとの件数を返します（groups[].items[] の各項目に key・count・approx。大きな表が時間切れのときはデータベースの推定値で approx が true）。このサーバー上でのみ数え、どこにも送信しません。GET /api/v1/system/doctor/storage は容量の使用状況を返します：database（全体の容量、機能別に合計した groups、大きいテーブルの tables。インデックスと TOAST を含む）、directories（バックアップ、プログラムとパッケージ、データディレクトリ、ログ。approx は時間切れで計測しきれなかったこと、denied は読み取れないファイルがあったことを示します）、disk。ディレクトリの容量は数分間キャッシュし、refresh=true で再計測します。systemd・nginx・バックアップなどホスト側の状態はバックエンドからは見えないため、ホスト上で jt-ipam.sh doctor を実行してください。

15完整資源索引Full resource indexリソース一覧

OpenAPI 列出約 466 條路徑、641 個操作，另外還有約 20 條不在 OpenAPI 裡的路由（WebSocket、代理用端點、安裝腳本、機櫃嵌入 SVG、健康檢查、phpIPAM 根路徑與 MCP）。上面詳述的是最常用的資源；其餘大多遵循同一套 GET 列表 / GET {id} / POST / PATCH / DELETE 慣例。下表的權限是整組的通則，個別端點以程式與 schema 為準。 OpenAPI lists about 466 paths and 641 operations, and about 20 more routes are hidden from it (WebSockets, agent endpoints, installer scripts, the rack embed SVG, health checks, the phpIPAM root and MCP). The sections above cover the most-used resources; most others follow the same GET list / GET {id} / POST / PATCH / DELETE convention. The access column states each group's general rule; individual endpoints are defined by the code and schema.OpenAPI にはおよそ 466 のパスと 641 の操作が載っており、ほかに OpenAPI に載らない経路が約 20 本あります（WebSocket、エージェント用エンドポイント、インストールスクリプト、ラック図の埋め込み SVG、ヘルスチェック、phpIPAM のルート、MCP）。上で詳しく説明したのはよく使うリソースで、それ以外の多くは同じ GET 一覧 / GET {id} / POST / PATCH / DELETE の作法に従います。下表の権限はグループ全体の原則で、個々のエンドポイントはコードとスキーマに従います。