17. エンドポイント一覧

PlantPulse APIのRESTエンドポイントとクライアントメソッドのマッピングです。ベースパスは /api/v5 です。

認証: APIClient_V5.connect() 呼び出し時に自動的にapi_keyが発行・管理されるため、ユーザーが直接呼び出すべき認証エンドポイントはありません。

17.1 System

HTTP	エンドポイント	メソッド
GET	`/api/v5/ping`	`client.system().ping()`

17.2 ID発行

メソッド	パス	説明
POST	`/api/v5/domain-ids`	ドメインIDを事前に取得します（クライアントメソッドなし） — IDルール

17.3 Site (6個)

HTTP	エンドポイント	メソッド
POST	`/api/v5/site`	`client.site().create(req)`
PUT	`/api/v5/site/{id}`	`client.site().update(id, req)`
DELETE	`/api/v5/site/{id}`	`client.site().delete(id)`
GET	`/api/v5/site/{id}`	`client.site().get(id)`
GET	`/api/v5/site`	`client.site().list()`
GET	`/api/v5/site/{id}/exists`	`client.site().exists(id)`

17.4 OPC (10個)

HTTP	エンドポイント	メソッド
POST	`/api/v5/opc`	`client.opc().create(req)`
PUT	`/api/v5/opc/{id}`	`client.opc().update(id, req)`
DELETE	`/api/v5/opc/{id}`	`client.opc().delete(id)`
GET	`/api/v5/opc/{id}`	`client.opc().get(id)`
GET	`/api/v5/opc`	`client.opc().list()`
GET	`/api/v5/opc?site_id={id}`	`client.opc().listBySite(siteId)`
GET	`/api/v5/opc?opc_source_type={type}`	`client.opc().listByType(sourceType)`
GET	`/api/v5/opc/{id}/exists`	`client.opc().exists(id)`
GET	`/api/v5/opc/count`	`client.opc().count()`
GET	`/api/v5/opc/count?site_id={id}`	`client.opc().countBySite(siteId)`

17.5 Asset (6個)

HTTP	エンドポイント	メソッド
POST	`/api/v5/asset`	`client.asset().create(req)`
PUT	`/api/v5/asset/{id}`	`client.asset().update(id, req)`
DELETE	`/api/v5/asset/{id}`	`client.asset().delete(id)`
GET	`/api/v5/asset/{id}`	`client.asset().get(id)`
GET	`/api/v5/asset`	`client.asset().list()`
GET	`/api/v5/asset/{id}/exists`	`client.asset().exists(id)`

関係オントロジー (4個)

階層（親–子）とは別の方向性を持つ関係です。「この設備が停止した場合、どこまで影響を受けるか」を問う際に使用します。

HTTP	エンドポイント	役割
POST	`/api/v5/assets/{asset_id}/relations`	関係登録 — 本文 `{site_id, to_entity_type, to_entity_id, relation_type, description?}` → 201
GET	`/api/v5/assets/{asset_id}/relations?type=`	直接関係リスト（インバウンド・アウトバウンド）
DELETE	`/api/v5/relations/{relation_id}`	関係削除 → 204
GET	`/api/v5/ontology/graph/{entity_id}?relation=&direction=DOWN&depth=2`	グラフ探索(BFS)

関係	意味	方向
`FEEDS`	工程フロー	資産 → 資産
`DEPENDS_ON`	ユーティリティ依存(電力・エアー・冷却)	資産 → 資産
`PRODUCES`	生産アウトプット	資産 → 製品

direction は UP · DOWN · BOTH(デフォルト DOWN), depth は 1~5(デフォルト 2)です。
自己参照関係は保存されず、同一組み合わせの関係は一度だけ登録されます。
登録・削除は変更にあたるため、ADMIN/APIロールと監査ログが適用されます。
同様の探索をAIアシスタントが呼び出すのが MCP の trace_asset_relations です。

QRラベル

HTTP	エンドポイント	役割
GET	`/api/v5/asset/qr/{token}`	ラベルトークンの設備。トークンではない、または再発行された旧トークンの場合は 404

ラベルに含まれるアドレスは GET /api/v5/asset/{id} 応答の qr_payload です。この呼び出しではトークンを作成しないため、トークンがまだないか PP_UI_CONSOLE_URL がない場合は "" となります。ログイン不要の公開ページは V5 ではなく /qr/{token} です — QRラベルと公開ページ.

17.6 Tag (23個)

CRUD + リスト

HTTP	エンドポイント	メソッド
POST	`/api/v5/tag`	`client.tag().create(req)`
PUT	`/api/v5/tag/{id}`	`client.tag().update(id, req)`
DELETE	`/api/v5/tag/{id}`	`client.tag().delete(id)`
GET	`/api/v5/tag/{id}`	`client.tag().get(id)`
GET	`/api/v5/tag/{id}/exists`	`client.tag().exists(id)`
GET	`/api/v5/tag`	`client.tag().list()`
GET	`/api/v5/tag?site_id={id}`	`client.tag().listBySite(siteId)`
GET	`/api/v5/tag?opc_id={id}`	`client.tag().listByOpc(opcId)`
GET	`/api/v5/tag?asset_id={id}`	`client.tag().listByAsset(assetId)`
GET	`/api/v5/tag/count`	`client.tag().count()`
GET	`/api/v5/tag/count?site_id={id}`	`client.tag().countBySite(siteId)`
GET	`/api/v5/tag/count?opc_id={id}`	`client.tag().countByOpc(opcId)`
GET	`/api/v5/tag/count?asset_id={id}`	`client.tag().countByAsset(assetId)`

PATCH (10個 — タブ別部分修正)

HTTP	エンドポイント	メソッド
PATCH	`/api/v5/tag/{id}/basic`	`patchBasic(id, req)`
PATCH	`/api/v5/tag/{id}/alarm`	`patchAlarm(id, req)`
PATCH	`/api/v5/tag/{id}/metadata`	`patchMetadata(id, req)`
PATCH	`/api/v5/tag/{id}/calculation`	`patchCalculation(id, req)`
PATCH	`/api/v5/tag/{id}/sampling`	`patchSampling(id, req)`
PATCH	`/api/v5/tag/{id}/aggregation`	`patchAggregation(id, req)`
PATCH	`/api/v5/tag/{id}/ai`	`patchAi(id, req)`
PATCH	`/api/v5/tag/{id}/publish`	`patchPublish(id, req)`
PATCH	`/api/v5/tag/{id}/attribute`	`patchAttribute(id, req)`
PATCH	`/api/v5/tag/{id}/link`	`patchLink(id, req)`

17.7 Alarm (3個)

HTTP	エンドポイント	メソッド
GET	`/api/v5/alarm/{seq}`	`client.alarm().get(seq)`
GET	`/api/v5/alarm?limit={n}`	`client.alarm().list(limit)`
GET	`/api/v5/alarm/performance?scope_type=&scope_id=`	アラームシステム性能(クライアントメソッドなし)

/alarm/performance — scope_type は SITE · AREA · LINE, scope_id はサイトID またはエセットID であり、両方必須です。期間は days(1~31, デフォルト 7) または from + to(セットで、31日まで)であり、from/to が days より優先されます。アラーム発生のみをカウントし、非表示・抑制中に発生したものは suppression に別途表示されます。範囲・期間が正しくない場合は 400 となります。同一の値を MCP get_alarm_performance が返します。

17.8 Order (11個)

HTTP	エンドポイント	メソッド
POST	`/api/v5/order`	`client.order().create(req)`
PUT	`/api/v5/order/{id}`	`client.order().update(id, req)`
DELETE	`/api/v5/order/{id}`	`client.order().delete(id)`
GET	`/api/v5/order/{id}`	`client.order().get(id)`
GET	`/api/v5/order`	`client.order().list()`
GET	`/api/v5/order/{id}/exists`	`client.order().exists(id)`
POST	`/api/v5/order/{id}/start`	`client.order().start(id)`
POST	`/api/v5/order/{id}/end`	`client.order().end(id)`
POST	`/api/v5/order/{id}/pause`	`client.order().pause(id)`
POST	`/api/v5/order/{id}/resume`	`client.order().resume(id)`
POST	`/api/v5/order/{id}/abort`	`client.order().abort(id)`

17.8.1 保全オーダー

設備の保全呼び出し・修理・予防保全作業です(ISA-95 maintenance work order)。生産ワークオーダー(/order)とは異なるオブジェクトであり、クライアントメソッドなしで REST 経由で呼び出します。

HTTP	エンドポイント	役割
GET	`/api/v5/maintenance-orders`	リスト。フィルタ `scope`+`scope_id`(`asset` · `line` · `area` · `site`) · `status_code` · `open` · `maintenance_kind_code` · `assignee_employee_id` · `failure_mode_code` · `maintainable_item_code` · `from`/`to` · `period_of` · `overdue` · `external_system` · `external_id`。ページ `page` · `limit`(デフォルト 50, 最大 500) · `sort` · `order`
GET	`/api/v5/asset/{asset_id}/maintenance-orders`	設備単体のリスト
POST	`/api/v5/asset/{asset_id}/maintenance-orders`	保全呼び出し追加
GET	`/api/v5/maintenance-orders/{maintenance_order_id}`	単一案件
PATCH	`/api/v5/maintenance-orders/{maintenance_order_id}`	内容変更
POST	`/api/v5/maintenance-orders/{maintenance_order_id}/transition`	状態遷移(受付・開始・完了・取消)。本文 `status_code` · `version`, 取消は `cancel_reason_code`
GET	`/api/v5/maintenance-orders/{maintenance_order_id}/revisions`	判定履歴
GET	`/api/v5/maintenance-orders/summary`	範囲・期間の保全サマリー
GET	`/api/v5/maintenance-orders/options`	設定可能な種類・状態・コード
GET	`/api/v5/maintenance-orders/board`	範囲の保全ステータスボード
GET	`/api/v5/maintenance-orders/changes`	CMMS同期用変更フィード(カーソル)
GET · PUT	`/api/v5/maintenance-orders/by-external/{system}/{external_id}`	外部(CMMS)番号で検索・べき等書き込み
GET · PUT	`/api/v5/maintenance-orders/by-external?system=&external_id=`	同上。番号に `/` がある場合
POST · GET	`/api/v5/maintenance-orders/{maintenance_order_id}/attachments`	写真アップロード・リスト
GET	`/api/v5/maintenance-orders/{maintenance_order_id}/attachments/{maintenance_attachment_seq}/content`	写真内容

保全オーダー項目

項目名は応答・リクエスト本文・リストクエリで共通です。

項目	タイプ	意味
`maintenance_order_id`	文字	`MAINTENANCE_ORDER_000001`。旧行は数値文字列(`"12"`)
`maintenance_kind_code`	文字	保全種類(`CORRECTIVE` …)
`status_code`	文字	状態(`REQUESTED` · `ACCEPTED` · `IN_PROGRESS` · `COMPLETED` · `CANCELLED`)
`cancel_reason_code`	文字	取消理由
`failure_record_seq`	数値	紐付いた故障記録
`maintenance_plan_id` · `maintenance_plan_name`	文字	予防保全計画。`MAINTENANCE_PLAN_000001` または旧数値文字列
`failure_mode_code` · `failure_mechanism_code` · `failure_cause_code` · `maintainable_item_code`	文字	ISO 14224 コード。表示名は `_code` の代わりに `_name`
`cause_code`	文字	原因辞書コード(アラームと同一の辞書)
`checklist_results[].maintenance_attachment_seq`	数値	点検項目の写真

CMMSウェブフック

設定キー PP_MAINTENANCE_WEBHOOK_URL にアドレスを設定すると、保全オーダーの状態が変わるたびに JSON を一度 POST します（呼び出し・受付・開始・完了・取消）。内容のみを修正した場合は送信されず、空にするとオフになります。失敗すると診断 diagnostic.maintenance.webhook_failed がオンになり、次回の成功時にオフになります。再送は行われません。

キー	値
`text`	導入言語の1行文章
`event`	`maintenance.requested` · `maintenance.accepted` · `maintenance.in_progress` · `maintenance.completed` · `maintenance.cancelled`
`maintenance_order_id`	保全オーダーID(文字)
`asset_id` · `asset_name`	設備
`maintenance_kind_code` · `status_code`	種類 · 状態
`description` · `failure_mode_code`	説明 · 故障モード
`requested_by` · `accepted_by` · `assignee_employee_id`	作業者
`cancel_reason_code`	取消理由
`external_system` · `external_id` · `owner`	外部番号と所有者
`anomaly_found` · `checklist_results`	点検異常有無と回答(`item_id` · `checked` · `value` · `maintenance_attachment_seq` · `out_of_range`)
`maintenance_plan_id` · `plan_due_at`	予防保全計画
`at` · `version`	状態遷移時刻(epoch ms) · 判定

値が不明なキーも省略されず null として含まれます。

17.9 Calendar (6個)

HTTP	エンドポイント	メソッド
POST	`/api/v5/calendar`	`client.calendar().create(req)`
PUT	`/api/v5/calendar/{id}`	`client.calendar().update(id, req)`
DELETE	`/api/v5/calendar/{id}`	`client.calendar().delete(id)`
GET	`/api/v5/calendar/{id}`	`client.calendar().get(id)`
GET	`/api/v5/calendar`	`client.calendar().list()`
GET	`/api/v5/calendar/search?from={iso}&to={iso}`	`client.calendar().search(from, to)`

17.10 Customer (8個)

HTTP	エンドポイント	メソッド
POST	`/api/v5/customer`	`client.customer().create(req)`
PUT	`/api/v5/customer/{id}`	`client.customer().update(id, req)`
DELETE	`/api/v5/customer/{id}`	`client.customer().delete(id)`
GET	`/api/v5/customer/{id}`	`client.customer().get(id)`
GET	`/api/v5/customer`	`client.customer().list()`
GET	`/api/v5/customer?site_id={id}`	`client.customer().listBySite(siteId)`
GET	`/api/v5/customer/{id}/exists`	`client.customer().exists(id)`
GET	`/api/v5/customer/count`	`client.customer().count()`

17.11 Employee (7個)

HTTP	エンドポイント	メソッド
POST	`/api/v5/employee`	`client.employee().create(req)`
PUT	`/api/v5/employee/{id}`	`client.employee().update(id, req)`
DELETE	`/api/v5/employee/{id}`	`client.employee().delete(id)`
GET	`/api/v5/employee/{id}`	`client.employee().get(id)`
GET	`/api/v5/employee`	`client.employee().list()`
GET	`/api/v5/employee/{id}/exists`	`client.employee().exists(id)`
GET	`/api/v5/employee/count`	`client.employee().count()`

17.12 Product (7個)

HTTP	エンドポイント	メソッド
POST	`/api/v5/product`	`client.product().create(req)`
PUT	`/api/v5/product/{id}`	`client.product().update(id, req)`
DELETE	`/api/v5/product/{id}`	`client.product().delete(id)`
GET	`/api/v5/product/{id}`	`client.product().get(id)`
GET	`/api/v5/product`	`client.product().list()`
GET	`/api/v5/product/{id}/exists`	`client.product().exists(id)`
GET	`/api/v5/product/count`	`client.product().count()`

17.13 Path (2個)

HTTP	エンドポイント	メソッド
GET	`/api/v5/path/asset/{id}`	`client.path().getByAsset(assetId)`
GET	`/api/v5/path/tag/{id}`	`client.path().getByTag(tagId)`

17.14 Flow (3個)

HTTP	エンドポイント	メソッド
GET	`/api/v5/flow/{id}`	`client.flow().get(flowId)`
GET	`/api/v5/flow`	`client.flow().list()`
GET	`/api/v5/flow/{id}/node`	`client.flow().listNodes(flowId)`

17.15 統計

以下の数値は plantpulse-api クライアントメソッドが存在するパスのみをカウントしています。

ドメイン	エンドポイント数
System	1
Site	6
OPC	10
Asset	6
Tag	23 (CRUD 5 + リスト 7 + カウント 4 + PATCH 10)
Alarm	2
Order	11 (CRUD 6 + ライフサイクル 5)
Calendar	6
Customer	8
Employee	7
Product	7
Path	2
Flow	3
合計	92 (+認証 1)

17.16 HTTPメソッド分布

HTTP	個数	用途
GET	56	照会 (単一/リスト/存在確認/カウント)
POST	16	登録 + Orderライフサイクル
PUT	10	全体修正
PATCH	10	Tagタブ別部分修正
DELETE	10	削除

17.17 リストの全件読み込み — カーソル

GET /api/v5/site · /product · /customer · /employee はカーソルを用いて継続的に読み込みます。ページサイズ limit はデフォルト 100、上限 1000 であり（それを超える場合は 1000 に制限されます）、初回呼び出しには cursor を含めません。

curl -H "X-API-Key: $TOKEN" "$BASE/api/v5/site?limit=500"
curl -H "X-API-Key: $TOKEN" "$BASE/api/v5/site?limit=500&cursor=<next_cursor>"

{
  "data": [ ],
  "meta": {
    "status": "OK",
    "pagination": { "limit": 500, "total": 1234 },
    "cursor": { "next_cursor": "…", "has_more": true, "limit": 500 }
  },
  "errors": null
}

data は本ページの行配列です。
meta.pagination.total は同一フィルタの全件数です。
meta.cursor.has_more が false になるまで next_cursor をそのまま次回の呼び出しの cursor として渡します。
カーソルはそのリストとフィルタに紐付けられています。別のリストのカーソルや site_id を変更した呼び出しに使用すると 422 E1002 となります。
顧客・製品・従業員は ID 順、サイトは名前・ID 順です。読み取り中に行が修正されても漏れなく取得されます。

Javaクライアントの list() は cursor を渡さないため、最初のページのみを返します。全件を読み込むには REST で呼び出してください。

17.18 変更時のみ取得 — `/tag/export` の ETag

GET /api/v5/tag/export はサイト・接続・プラント全体のタグを一括して出力します。site_id · opc_id でフィルタリングし、include=config の場合は行ごとに設定が含まれます（タグごとに設定を呼び出す必要はありません）。応答は data = {tags: [...], count: N} です。

応答の ETag を保存し、次回の読み取り時に If-None-Match として返します。

curl -i -H "X-API-Key: $TOKEN" "$BASE/api/v5/tag/export?site_id=SITE_000001&include=config"
# ETag: "<SHA-256>"

curl -i -H "X-API-Key: $TOKEN" -H 'If-None-Match: "<SHA-256>"' \
  "$BASE/api/v5/tag/export?site_id=SITE_000001&include=config"
# 304 Not Modified — 본문 없음

ETag は出力される data の SHA-256 です。この応答の内容が変更された場合 — タグや設定の変更、タグの追加・削除、接続が別のサイトに移動した場合など — 誰が変更したかにかかわらず値が異なります。変更されていない場合は、再起動後や別のノードから読み取っても同一の値となります。
プロキシが付与した弱い形式の W/"…" および * も受け入れます。
304は転送とパースを省略するだけであり、読み取り処理自体を省略するものではありません。 サーバーは値を計算するためにすべての行を読み取ります。データが必要な周期よりも頻繁に呼び出さないでください。

17.1 System​

17.2 ID発行​

17.3 Site (6個)​

17.4 OPC (10個)​

17.5 Asset (6個)​

関係オントロジー (4個)​

QRラベル​

17.6 Tag (23個)​

CRUD + リスト​

PATCH (10個 — タブ別部分修正)​

17.7 Alarm (3個)​

17.8 Order (11個)​

17.8.1 保全オーダー​

保全オーダー項目​

CMMSウェブフック​

17.9 Calendar (6個)​

17.10 Customer (8個)​

17.11 Employee (7個)​

17.12 Product (7個)​

17.13 Path (2個)​

17.14 Flow (3個)​

17.15 統計​

17.16 HTTPメソッド分布​

17.17 リストの全件読み込み — カーソル​

17.18 変更時のみ取得 — /tag/export の ETag​