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

jt-ipam 的 REST API、phpIPAM 相容層、Graylog 查表與 MCP。以下所有網址請把 https://ipam.example.com 換成你自己的位址。 The jt-ipam REST API, phpIPAM compatibility layer, Graylog lookups 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 —— 這是刻意的：不提供無法真正強制執行的權限旋鈕。 These are the only two supported. Any other value (e.g. write, subnets:read) is rejected with 422 at creation — deliberately, so there is no knob that looks like a restriction but isn't enforced.対応しているのはこの二つだけです。それ以外の値（write や subnets:read など）は作成時に 422 で拒否されます。これは意図的な仕様で、実際には強制されない「制限のように見えるつまみ」を用意しないためです。

用 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 端點。 Base path: /api/v1. Requests and responses are JSON (Content-Type: application/json), apart from a few explicitly-CSV endpoints.ベースパスは /api/v1 です。明示的に CSV と記載された一部を除き、リクエストもレスポンスも JSON（Content-Type: application/json）です。
• 識別碼是 UUID，不是遞增整數。 Identifiers are UUIDs, not incrementing integers.識別子は UUID であり、連番の整数ではありません。
• 時間一律 ISO 8601、UTC（2026-07-30T12:34:56Z）。 Timestamps are ISO 8601 in UTC (2026-07-30T12:34:56Z).時刻はすべて ISO 8601 の UTC です（2026-07-30T12:34:56Z）。
• 未知欄位會被拒絕。寫入用的 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ページング

列表端點吃 page（從 1 起算）與 page_size，回應固定是這個外層： List endpoints take page (1-based) and page_size, and always return this envelope:一覧系のエンドポイントは page（1 起算）と page_size を受け取り、常にこの外枠を返します。

{ "items": [ … ], "total": 1234, "page": 1, "page_size": 50 }

page_size 上限視端點而定（多數是 200）。要抓完整資料就依 total 逐頁取。 The page_size cap depends on the endpoint (usually 200). To fetch everything, page through using total.page_size の上限はエンドポイントによります（多くは 200）。全件取得するには total を見ながらページを進めてください。

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

錯誤回應一律是 {"detail": "…"}；422 另外附 errors 陣列指出哪個欄位不合法。伺服器端不會回 stack trace。 Errors are always {"detail": "…"}; 422 additionally carries an errors array pinpointing the invalid fields. Stack traces are never returned.エラーは常に {"detail": "…"} の形です。422 の場合はどの項目が不正かを示す errors 配列も付きます。スタックトレースが返ることはありません。

{ "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、統計與趨勢都會跟著縮放。 Per-object data (sections / subnets / IPs / devices / racks / locations / customers) → only what you can see, and total, counts and trends scale with it.オブジェクト単位で許可されるデータ（セクション／サブネット／IP／機器／ラック／拠点／顧客）→ 閲覧可能な範囲だけが返り、total・集計・傾向もその範囲に合わせて縮小します。
• 全域基礎設施資料（VLAN／VRF／NAT／防火牆／DNS／虛擬化／佈線／電力…）→ 需要「全域讀取」（admin 或萬用讀取授權）。只被指派特定物件的帳號會拿到 403。 Global infrastructure (VLAN / VRF / NAT / firewalls / DNS / virtualization / cabling / power…) → requires global read (admin or a wildcard read grant). Accounts scoped to specific objects get 403.全体に関わる基盤データ（VLAN／VRF／NAT／ファイアウォール／DNS／仮想化／配線／電源など）→ 全体の読み取り権限（admin またはワイルドカードの読み取り許可）が必要です。特定のオブジェクトだけを割り当てられたアカウントは 403 になります。
• 純管理資料（稽核記錄、使用者／群組／權限、系統與整合設定）→ 需要 admin。 Administrative data (audit log, users / groups / permissions, system and integration settings) → requires admin.管理系のデータ（監査ログ、ユーザー／グループ／権限、システムと連携の設定）→ admin が必要です。

想知道自己這把權杖有什麼能力，打 GET /api/v1/me：回應含 is_admin、has_visibility、has_global_read。 To discover what your token can do, call GET /api/v1/me: the response includes is_admin, has_visibility and has_global_read.自分のトークンに何ができるかを知るには GET /api/v1/me を呼びます。応答に is_admin・has_visibility・has_global_read が含まれます。

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":"Taipei DC","description":"main site"}'

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

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"}'

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

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

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

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

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

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

GET /api/v1/search?q=…&limit_per_type=… 是全域搜尋，跨區段／子網路／IP／裝置／客戶等型別，並依你的可見範圍過濾。支援部分 MAC 首碼（如 bc:24）。 GET /api/v1/search?q=…&limit_per_type=… searches across sections, subnets, IPs, devices, customers and more, filtered to what you may see. Partial MAC prefixes (e.g. bc:24) work.GET /api/v1/search?q=…&limit_per_type=… は横断検索で、セクション／サブネット／IP／機器／顧客などの種別をまたぎ、閲覧可能な範囲に絞って返します。MAC の部分的な接頭辞（bc:24 など）にも対応します。

/api/v1/tools/* 是一組無副作用的計算端點，適合腳本直接呼叫： /api/v1/tools/* is a set of side-effect-free calculators handy for scripts:/api/v1/tools/* は副作用のない計算用エンドポイント群で、スクリプトから直接呼ぶのに向いています。

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

API 共約 500 條路由。上面詳述的是最常用的核心資源；其餘資源大多遵循同一套 GET 列表 ／ GET {id} ／ POST ／ PATCH ／ DELETE 慣例。 The API has roughly 500 routes. The sections above cover the core resources in detail; most others follow the same GET list / GET {id} / POST / PATCH / DELETE convention.API の経路はおよそ 500 本あります。上で詳しく説明したのは最もよく使う中核のリソースで、それ以外の多くは同じ GET 一覧 ／ GET {id} ／ POST ／ PATCH ／ DELETE の作法に従います。

11phpIPAM 相容 API-compatible API 互換 API

給既有的 phpIPAM 腳本用的相容層：換掉網址與權杖就能沿用，回應是 phpIPAM 的外層格式。 A compatibility layer for existing phpIPAM scripts: change the URL and token and they keep working, with phpIPAM-shaped response envelopes.既存の phpIPAM 用スクリプトのための互換レイヤです。URL とトークンを差し替えればそのまま使え、応答も phpIPAM と同じ外枠の形で返します。

基底路徑：/api/phpipam/<app_id>/。<app_id> 沿用你原本 phpIPAM 的 App ID 字串。 Base path: /api/phpipam/<app_id>/, where <app_id> is whatever App ID string your scripts already use.ベースパスは /api/phpipam/<app_id>/ です。<app_id> には、これまで使っていた phpIPAM の App ID 文字列をそのまま指定します。

認證Authentication認証

三種標頭都收（挑一個就好）：token: jt_…、phpipam-token: jt_…、Authorization: Bearer jt_…。也可以用帳號密碼走 Basic Auth 換一把 30 天的權杖： Any one of three headers works: token: jt_…, phpipam-token: jt_…, or Authorization: Bearer jt_…. You can also exchange username/password over Basic Auth for a 30-day token:次の三つのヘッダのいずれでも構いません。token: jt_…、phpipam-token: jt_…、Authorization: Bearer jt_…。また、Basic 認証でユーザー名とパスワードを送り、30 日間有効なトークンと交換することもできます。

curl -X POST -u 'user:password' \
  https://ipam.example.com/api/phpipam/myapp/user/

{ "code":200, "success":true, "data":{ "token":"jt_prod_…", "expires":"…" }, "time":0.01 }

12Graylog DSV 查表 lookups ルックアップ

給 Graylog 的「DSV File from HTTP」配接器用的免登入唯讀端點，回 CSV。認證是一把系統層級的權杖，走網址參數 ?token=（由 admin 在「管理 → Graylog DSV」產生），因為 Graylog 抓檔時不能帶自訂標頭。 Unauthenticated, read-only CSV endpoints for Graylog's "DSV File from HTTP" adapter. They are gated by a system-level token passed as ?token= (generated under Admin → Graylog DSV), because Graylog cannot send custom headers when fetching.Graylog の「DSV File from HTTP」アダプタ向けの認証不要・読み取り専用の CSV エンドポイントです。Graylog は取得時に独自ヘッダを送れないため、認証はシステムレベルのトークンを URL パラメータ ?token= で渡す方式です（admin が「管理 → Graylog DSV」で生成します）。

curl "https://ipam.example.com/api/v1/lookup/hostnames?token=<dsv-token>"

"192.0.2.10","web01"
"192.0.2.11","db01"

在 Graylog 的 DSV 配接器裡，Key column = 0、Value column = 1（欄位索引從 0 起算）。防火牆相關端點要先在該台整合設定裡勾選「提供防火牆 DSV」才會有資料。 In Graylog's DSV adapter set Key column = 0 and Value column = 1 (indices are 0-based). The firewall endpoints only return data once "expose firewall DSV" is enabled on that instance.Graylog の DSV アダプタでは Key column = 0、Value column = 1 に設定してください（索引は 0 起算です）。ファイアウォール関連のエンドポイントは、その連携の設定で「ファイアウォール DSV を提供する」を有効にして初めてデータを返します。

13MCP（給 LLM 用） (for LLMs)（LLM 向け）

jt-ipam 內建 MCP（Model Context Protocol）伺服器，讓 LLM 用自然語言查 IPAM。走 JSON-RPC 2.0： jt-ipam ships an MCP (Model Context Protocol) server so an LLM can query the IPAM in natural language, over JSON-RPC 2.0:jt-ipam には MCP（Model Context Protocol）サーバーが組み込まれており、LLM が自然言語で IPAM を問い合わせられます。通信は JSON-RPC 2.0 です。

• Streamable HTTP：POST /api/mcp。initialize 的回應會帶 Mcp-Session-Id 標頭。支援 initialize、ping、tools/list、tools/call。 Streamable HTTP: POST /api/mcp. The initialize response carries an Mcp-Session-Id header. Supports initialize, ping, tools/list and tools/call.Streamable HTTP：POST /api/mcp。initialize の応答に Mcp-Session-Id ヘッダが付きます。initialize・ping・tools/list・tools/call に対応します。
• stdio（本機用，例如 Claude Desktop）：python -m app.mcp.stdio_server，權杖放環境變數 JT_IPAM_MCP_TOKEN。 stdio (local, e.g. Claude Desktop): python -m app.mcp.stdio_server, with the token in JT_IPAM_MCP_TOKEN.stdio（ローカル用。Claude Desktop など）：python -m app.mcp.stdio_server。トークンは環境変数 JT_IPAM_MCP_TOKEN に入れます。

認證用 X-Auth-Token 或 Authorization: Bearer，可以是： Authentication uses X-Auth-Token or Authorization: Bearer, with either:認証は X-Auth-Token または Authorization: Bearer で行い、次のいずれかを使えます。

• 對外唯讀 MCP 金鑰（jtmcp_…，admin 在「管理 → LLM／AI」產生並輪替）—— 只看得到唯讀工具，異動類工具會被隱藏並擋下。要先啟用「對外 MCP」才會生效。 A read-only external MCP key (jtmcp_…, generated and rotated by an admin under Admin → LLM/AI) — read-only tools only; mutating tools are hidden and blocked. External MCP must be enabled first.外部向けの読み取り専用 MCP キー（jtmcp_…。admin が「管理 → LLM／AI」で生成・更新します）。読み取り専用のツールだけが見え、変更系のツールは隠され、実行も拒否されます。先に「外部 MCP」を有効にする必要があります。
• 一般 API 權杖（jt_…）—— 依該權杖擁有者的權限。若這把權杖是唯讀 scope，MCP 同樣只給唯讀工具。 A regular API token (jt_…) — scoped to its owner's permissions. If the token is read-only, MCP likewise exposes only read-only tools.通常の API トークン（jt_…）。そのトークンの所有者の権限に従います。読み取り専用スコープのトークンであれば、MCP でも読み取り専用のツールだけが提供されます。

curl -X POST https://ipam.example.com/api/mcp \
  -H "X-Auth-Token: jtmcp_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

14代理協定Agent protocolsエージェントのプロトコル

掃描代理與憑證派送代理有自己的通道，用各自獨立的金鑰（X-Agent-Key 標頭，建立代理時產生、只存雜湊），不是 API 權杖。這些端點是給代理程式用的，一般整合不需要碰。 The scan agent and certificate-distribution agent have their own channel, authenticated by per-agent keys (the X-Agent-Key header, issued when the agent is created and stored only as a hash) rather than API tokens. These endpoints are for the agents themselves; normal integrations don't need them.スキャンエージェントと証明書配布エージェントは専用の経路を持ち、API トークンではなくエージェントごとの鍵で認証します（X-Agent-Key ヘッダ。エージェント作成時に発行され、ハッシュだけが保存されます）。これらのエンドポイントはエージェント自身のためのもので、通常の連携で触る必要はありません。

bundle/raw?part=pkcs12 可帶 X-Pfx-Password 標頭。帶了就回以該密碼加密、且 Windows 匯得進去的 PKCS#12（PBESv1-SHA1-3DES）—— PBESv1 是 Windows CryptoAPI 全版本都吃的形式；函式庫預設的 PBESv2/AES-256 失敗時訊息是誤導的「密碼不正確」。不帶標頭時行為不變（不加密）。Windows 代理每次執行自產一組隨機密碼且只留在記憶體，私鑰不會為了匯入而寫到磁碟。 bundle/raw?part=pkcs12 accepts an X-Pfx-Password header. With it you get a PKCS#12 encrypted with that password using the encryption Windows can actually import (PBESv1-SHA1-3DES) — PBESv1 is the form every version of the Windows CryptoAPI accepts; the library default, PBESv2/AES-256, fails with a misleading "the password is incorrect". Without the header the behaviour is unchanged (unencrypted). The Windows agent generates a random password per run and keeps it in memory, so the private key is never written to disk on the way in.bundle/raw?part=pkcs12 は X-Pfx-Password ヘッダを受け付けます。付けると、そのパスワードで暗号化されかつ Windows が実際に取り込める PKCS#12（PBESv1-SHA1-3DES）が返ります。PBESv1 はどのバージョンの Windows CryptoAPI でも受け付ける形式です。ライブラリの既定である PBESv2/AES-256 は、失敗したときに「パスワードが正しくありません」という誤解を招くメッセージになります。ヘッダを付けない場合の挙動は従来どおり（暗号化なし）です。Windows エージェントは実行のたびにランダムなパスワードを生成してメモリ上にだけ保持するため、取り込みのために秘密鍵がディスクへ書き出されることはありません。

另有兩支完全免認證的健康檢查端點，給負載平衡器用：GET /healthz（存活）與 GET /readyz（就緒，DB／Redis 不通時回 503）。 Two entirely unauthenticated health endpoints exist for load balancers: GET /healthz (liveness) and GET /readyz (readiness, returning 503 when the DB or Redis is unreachable).ロードバランサ向けに、認証がまったく不要なヘルスチェック用エンドポイントが二つあります。GET /healthz（生存確認）と GET /readyz（準備確認。DB や Redis に到達できないときは 503 を返します）。

15速率限制與 CORSRate limits & CORSレート制限と CORS

依來源 IP 分桶限流，超過回 429 並帶 Retry-After（秒）。預設值（可在後端設定調整）： Rate limits are bucketed per source IP; exceeding one returns 429 with Retry-After (seconds). Defaults (configurable in the backend):送信元 IP ごとにバケットを分けて制限し、超過すると Retry-After（秒）を付けて 429 を返します。既定値（バックエンドの設定で変更可）は次のとおりです。

CORS：正式環境只允許明確列出的 HTTPS 來源（不接受 *、不接受 HTTP）。因此瀏覽器端的跨網域呼叫預設不會通 —— 第三方整合請走伺服器對伺服器。 CORS: in production only explicitly-listed HTTPS origins are allowed (no *, no HTTP). So cross-origin browser calls will not work by default — do third-party integrations server-to-server.CORS：本番環境では明示的に列挙された HTTPS のオリジンだけを許可します（* も HTTP も不可）。そのためブラウザからのクロスオリジン呼び出しは既定では通りません。第三者との連携はサーバー間で行ってください。

16OpenAPI

後端是 FastAPI，會自動產生 OpenAPI 規格。但正式環境（APP_ENV=production）一律關閉 /docs、/redoc 與 /openapi.json，避免對外洩漏完整攻擊面。 The backend is FastAPI and generates an OpenAPI spec automatically. However /docs, /redoc and /openapi.json are disabled in production (APP_ENV=production) so the full attack surface isn't published.バックエンドは FastAPI なので OpenAPI 仕様が自動生成されます。ただし本番環境（APP_ENV=production）では /docs・/redoc・/openapi.json をすべて無効化し、攻撃面の全体像が外部に公開されないようにしています。

要拿完整的機器可讀規格（含每個端點的全部欄位），在非正式環境的實例上開一台即可： To get the complete machine-readable spec (every field of every endpoint), run a non-production instance:機械可読の完全な仕様（各エンドポイントの全項目を含む）が必要な場合は、本番以外の環境でインスタンスを一つ起動してください。

APP_ENV=development uvicorn app.main:app
curl http://127.0.0.1:8000/openapi.json > jt-ipam-openapi.json

拿到 openapi.json 之後可以直接餵給 openapi-generator 產出各語言的 client。 Feed that openapi.json to openapi-generator to produce a client in your language of choice.取得した openapi.json を openapi-generator に渡せば、好きな言語のクライアントを生成できます。