API Reference

API リファレンス

MATCHA サーバーは、HTTPS で JSON をやりとりする REST API を提供しています。MATCHA Manager とコマンドツールもこの API を使っており、同じ操作をお客様のシステムから自動化できます。

はじめに

このページは、workload automation MATCHA のサーバーが提供する API の仕様です。製品の全体像は 概要、構成や動作環境は 技術仕様、Manager の画面操作は 操作マニュアル をご覧ください。

ベース URLhttps://matcha.example.com:10057(ホスト名はお使いのサーバーに置き換えてください)。ポート番号の初期値は 10057 で、サーバー設定 QueryApiListenPort で変更できます。パスはこのベース URL の直下に続きます(例:https://matcha.example.com:10057/jobnets)。
通信HTTPS(TLS)のみです。平文の HTTP では接続できません。サーバー証明書は通常、サーバー作成時に作られた証明書です。クライアントはその証明書(または発行元の CA 証明書)を信頼するよう設定してください。
形式リクエスト・レスポンスの本文は JSON です。検索条件などは URL のクエリ文字列で渡します。
文字コードUTF-8 です。レスポンスの Content-Type は application/json です。
接続HTTP/1.1。1 回のリクエストごとに接続を閉じます(Keep-Alive は使いません)。
リクエストの大きさヘッダーと本文を合わせて 64 KB までです。超えたリクエストは処理されず、接続が閉じられます。大きなファイルは、ワークスペースのファイルやインポートのように分割して送る API を使います。
バージョン現在の API は第 1 版です。パスにバージョン番号は含みません。
呼び出し回数の制限現在、レート制限は設けていません。AI の呼び出しには、AI 接続ごとに 1 日のトークン上限を設定できます(AI 接続)。

認証 提供中

API を使うには、まず POST /login でサインインし、受け取ったセッショントークンを以後のリクエストの Authorization ヘッダーに付けます。

Authorization: Bearer <session_token>
  • Bearer の接頭辞は必須です。接頭辞の無いヘッダーは、トークンが無いものとして扱われます。
  • セッショントークンは 64 文字の 16 進文字列で、サーバー側で管理する不透明なトークンです(JWT のように中身を読み取れる形式ではありません)。
  • 有効期限はサインインから 24 時間です。期限切れ・不正なトークン・無効にされたユーザーのトークンは 401 AUTH_REQUIRED になります。もう一度サインインしてください。
  • ユーザーのパスワードが変更されると、そのユーザーのほかのセッションはすべて無効になります。
  • ユーザー名が存在しない場合とパスワードが違う場合は、同じ応答(401 INVALID_CREDENTIALS)を返します。
POST/login

サインインしてセッショントークンを受け取ります。本文:{"username", "password"}。応答:{"session_token", "user_id", "username", "role", "lang"}。
権限:不要

POST/logout

現在のセッションを終了します。トークンが無い・すでに無効な場合もエラーにはなりません。
権限:不要

PUT/me/password

サインイン中のユーザーが自分のパスワードを変更します。本文:{"current_password", "new_password"}。新しいパスワードは 8 文字以上です。現在のパスワードが違う場合は 403 INVALID_CREDENTIALS。
権限:すべてのロール

ロールと権限

ユーザーには 3 段階のロールのいずれかを設定します。上位のロールは下位のロールの権限をすべて持ちます。権限が足りない操作は 403 FORBIDDEN になります。各エンドポイントの「権限」は、必要な最低のロールを示しています。

roleできること
viewer実行状況・実行ログ・定義の参照
operatorviewer の権限に加えて、ジョブネットの手動起動・強制中断・保留ジョブのリリース、ワークスペースの配布、AI の試しに実行
adminすべての操作。ジョブネット・カレンダー・スケジュール・ホスト・ワークスペースの編集、ユーザー・グループ・通知チャネル・AI 接続・ライセンスの管理、エクスポート/インポート

ジョブネットの公開範囲:public_flag が false のジョブネットは、admin と、そのジョブネットの group_ids に含まれる有効なグループのメンバーだけが参照・実行できます。見る権限の無いジョブネットは「存在しない」ものとして扱われ(404、または一覧から除外)、その実行・実行ログも同様に見えません。

共通仕様

レスポンスの形式

すべてのレスポンスは同じ形の JSON で返ります。成功したかどうかは ok で判定できます。

// 成功
{ "ok": true, "data": { ... } }

// 一覧(ページング情報付き)
{ "ok": true, "data": [ ... ], "meta": { "total_count": 4821, "limit": 100, "offset": 0 } }

// 失敗
{ "ok": false, "error": { "code": "VALIDATION_ERROR", "message": "..." } }
  • error.code はプログラムで判定するための識別子です。error.message は原因を人が読むための説明で、現在は英語です。表示や分岐には code を使ってください。
  • 成功時の HTTP ステータスは通常 200 です。作成は 201、受け付けて後で処理するもの(配布、AI の試しに実行)は 202 を返します。
  • 存在しないパスやメソッドは 404 NOT_FOUND です。

ページング

一覧を返すエンドポイント(/jobnets・/calendars・/schedules・/executions・/logs・/hosts・/users・/user-groups・/notification-channels・/workspaces)は、クエリ文字列でページングできます。

パラメーター内容
limit1 回に返す件数。初期値 100、1〜1000。範囲外の値は初期値の 100 として扱います。
offset先頭から読み飛ばす件数。初期値 0。

レスポンスの meta.total_count は、条件に合う全件数です(公開範囲で見えないものは含みません)。AI 接続と AI ひな型の一覧はページングせず全件を返し、meta.total_count だけを付けます。

日時と日付の形式

  • 日時は ISO 8601 の UTC 表記です(例:2026-08-06T22:00:03Z)。/logs の from・to もこの形式で指定します。
  • カレンダーの稼働日は YYYY-MM-DD、スケジュールの起動時刻 boot_time はサーバーのローカル時刻の HH:MM です。
  • ライセンスの日付は YYYY-MM-DD、AI 使用量の date はサーバーのローカル日付です。
  • ワークスペースのファイル・配布結果の時刻(modified_at・started_at・finished_at)は UNIX 時間(秒)の整数です。

定義の版と削除

  • ジョブネット・カレンダー・スケジュールは版で管理します。PUT は上書きではなく新しい版を追加し、過去の実行は実行した時点の定義のまま残ります。DELETE は現在の版を無効にする論理削除です。
  • ホスト・ユーザー・グループ・通知チャネル・ワークスペースは版を持たず、PUT は上書き、DELETE は valid_flag=false にする論理削除です。これらの一覧には削除済みの行も含まれるため、必要に応じて valid_flag で絞り込んでください。

秘密情報の扱い

パスワードや API キーは書き込み専用です。POST・PUT の本文で受け付けますが、GET の応答には含めず、設定済みかどうかだけを has_password・has_run_user_password・has_smtp_password・has_api_key で返します。PUT で省略した場合は、今の値をそのまま残します。

エラーコード

HTTPcode意味
400VALIDATION_ERROR必須項目の不足、値の形式・範囲の誤り、JSON として読めない本文など
400INVALID_LICENSEライセンスファイルの形式・署名が正しくない
400LICENSE_OTHER_SERVER別のサーバー向けに発行されたライセンス
400PACKAGE_INVALID / PACKAGE_UNSUPPORTEDパッケージの内容が正しくない/対応していない形式の版
400PARAMETER_UNMAPPEDインポートで、割り当てが必要なホスト・実行ユーザーが未指定
400CONFLICT_UNRESOLVEDインポートで、同じ ID の定義があるのに扱い(skip・overwrite・rename)が未指定
400HOST_NOT_FOUNDインポートの割り当て先ホストが登録されていない
401AUTH_REQUIREDトークンが無い、不正、または期限切れ
401INVALID_CREDENTIALSサインインのユーザー名またはパスワードが違う(PUT /me/password では 403)
403FORBIDDENロールの権限が足りない
403LICENSE_LIMITエディションの上限(ホスト数・ユーザー数など)を超える操作
404NOT_FOUND対象が存在しない、または見る権限が無い。存在しないパス
409ALREADY_EXISTS同じ ID・名前がすでにある
409ALREADY_TERMINAL終了済みの実行を中断しようとした
409LAST_ADMIN有効な admin が 1 人もいなくなる変更
409IN_USEジョブが使っている AI ひな型を削除しようとした
409HOST_IN_OTHER_WORKSPACEそのホストは別のワークスペースの配布先になっている
409DEPLOY_RUNNINGそのワークスペースは配布中
409OFFSET_MISMATCH分割アップロードの位置が、受け取り済みの大きさと合わない
409UPLOAD_INCOMPLETEパッケージのアップロードが終わっていない
409CA_UNAVAILABLEエージェント用証明書を発行する CA を使えない
409NAME_CONFLICTサーバー自身の証明書と同じ名前のホストには証明書を発行できない
409OVER_LIMITAI 接続の 1 日のトークン上限に達している
413PACKAGE_TOO_LARGEパッケージがサーバーの上限(初期値 64 MB)を超える
500INTERNAL_ERRORサーバー内部のエラー(データベースのエラーなど)
502AGENT_UNREACHABLEエージェントに接続できない
503UNAVAILABLE一時的に受け付けられない(同時に実行できる件数の超過など)

ジョブネット 提供中

ジョブネットは、ジョブとその実行順(フロー)をまとめた定義です。jobnet_id は作成時にクライアントが指定する識別子です。

GET/jobnets

ジョブネットの一覧(ジョブ・フローは含まない要約)。ページング対応。
権限:viewer 以上

GET/jobnets/{jobnet_id}

ジョブネットの詳細。ジョブ・フロー・画面上の配置を含みます。
権限:viewer 以上

POST/jobnets

ジョブネットを作成します。本文は詳細と同じ形です。
権限:admin

PUT/jobnets/{jobnet_id}

ジョブネット全体を置き換えます(新しい版として保存)。group_ids を省略すると、公開範囲のグループは変更しません。
権限:admin

DELETE/jobnets/{jobnet_id}

ジョブネットを削除します(論理削除)。
権限:admin

詳細の形:

{ "ok": true, "data": {
  "jobnet_id": "JN0001", "jobnet_name": "夜間バッチ",
  "valid_flag": true, "public_flag": true, "group_ids": [],
  "multiple_start_up": "allow",
  "memo": "",
  "timeout": { "seconds": 3600, "on_timeout": "warn" },
  "jobs": [
    { "job_id": "J001", "job_name": "集計処理", "job_type": "dispatch",
      "method_flag": 0, "force_flag": false, "continue_flag": false,
      "run_user": "batchuser", "has_run_user_password": true,
      "type_config": { "host_name": "app01", "command": "run_batch.sh", "timeout": 600, "timeout_run_type": 0 },
      "env_config": { "values": { "ENV": "prod" }, "refs": [] },
      "use_workspace": false,
      "position": { "x": 100, "y": 200 } }
  ],
  "flows": [
    { "start_job_id": "J001", "end_job_id": "J002", "flow_type": "default", "width": 2 }
  ]
} }
  • multiple_start_up:同じジョブネットが実行中のときに起動されたときの扱い。allow(同時に実行)/skip(起動しない)/delay(前の実行が終わるまで待つ)。
  • run_user_password:ジョブを実行する OS ユーザーのパスワード。書き込み専用です。
  • method_flag が 1 のジョブは保留状態で始まり、リリースされるまで実行されません。
  • type_config の中身は job_type ごとに異なります。

ジョブの種類(job_type)

job_type内容状態
dispatchエージェントのホストでコマンドを実行します。type_config:host_name・command・timeout・timeout_run_type提供中
condition変数の値で後続の流れを分けます提供中
calc計算結果を変数に入れます提供中
value_set変数に値を設定します提供中
jobnet_call / jobnet_submit別のジョブネットを起動します(終了を待つ/待たない)提供中
release保留中のジョブをリリースします提供中
endジョブネットを終了します提供中
llmAI 問い合わせ。指示文を 1 回送り、答えを変数やファイルに受け取ります。type_config:host_name・connection(AI 接続の名前)・prompt が必須。任意で model・template・system・examples・inputs・references・output・temperature・max_output_tokens・timeout・retries提供中
ai_agentAI エージェント。目的を渡すと、AI が許可された道具(ファイルの読み書き・許可したコマンド)を使って作業します。定義として保存はできますが、現在のサーバーはこの種類のジョブをエージェントへ送りません。開発中
file_copyホスト間のファイル転送。種類としては予約済みですが、処理は未実装です。予定

llm ジョブの $変数 はサーバーが実行時に置き換えて送ります。答えは output の指定に従って変数(初期値 AI_ANSWER)に入り、後続の condition ジョブで分岐に使えます。AI 接続の API キーはサーバーが管理し、各エージェントに配る必要はありません。

カレンダー 提供中

カレンダーは稼働日の一覧です。スケジュールが起動する日を決めます。

GET/calendars

カレンダーの一覧。ページング対応。
権限:viewer 以上

GET/calendars/{calendar_id}

カレンダーの詳細。
権限:viewer 以上

POST/calendars

カレンダーを作成します。
権限:admin

PUT/calendars/{calendar_id}

カレンダーを更新します(新しい版として保存)。
権限:admin

DELETE/calendars/{calendar_id}

カレンダーを削除します(論理削除)。
権限:admin

{ "calendar_id": "CAL01", "calendar_name": "標準営業日", "valid_flag": true, "public_flag": true,
  "memo": "", "operating_dates": ["2026-01-05", "2026-01-06", "2026-01-07"] }

実在しない日付は 400 VALIDATION_ERROR になります。

スケジュール 提供中

スケジュールは、カレンダーと起動時刻の組み合わせで、ジョブネットを自動起動します。

GET/schedules

スケジュールの一覧。ページング対応。
権限:viewer 以上

GET/schedules/{schedule_id}

スケジュールの詳細。
権限:viewer 以上

POST/schedules

スケジュールを作成します。
権限:admin

PUT/schedules/{schedule_id}

スケジュールを更新します(新しい版として保存)。enabled を省略すると直前の版の値を引き継ぎます。
権限:admin

DELETE/schedules/{schedule_id}

スケジュールを削除します(論理削除)。
権限:admin

{ "schedule_id": "SCH01", "schedule_name": "夜間バッチ用", "valid_flag": true, "public_flag": true,
  "memo": "", "enabled": true,
  "triggers": [ { "calendar_id": "CAL01", "boot_time": "22:00" } ],
  "jobnet_ids": ["JN0001", "JN0002"] }
  • boot_time はサーバーのローカル時刻の HH:MM(00:00〜23:59)です。
  • スケジュールは保存した時刻より後の起動だけを行います。過去の日付を含むカレンダーを指定しても、過去の分は起動しません。サーバー停止中に過ぎた分は、再起動後に起動します。
  • enabled を false にすると一時停止します(定義は残ります)。再開すると新しい版になり、停止中の分は後から起動しません。

ホスト 提供中

ホストは、ジョブを実行するエージェントの接続先です。ホストは host_name で識別します。

GET/hosts

ホストの一覧。ページング対応。
権限:viewer 以上

GET/hosts/{host_name}

ホストの詳細。
権限:viewer 以上

POST/hosts

ホストを登録します。エディションのホスト数上限を超える場合は 403 LICENSE_LIMIT。
権限:admin

PUT/hosts/{host_name}

ホストを更新します(上書き)。
権限:admin

DELETE/hosts/{host_name}

ホストを削除します(論理削除)。そのホストに発行した証明書はすべて失効します。
権限:admin

GET/hosts/{host_name}/metrics

サーバーが収集した最新の CPU・メモリ・ディスク使用量と疎通状況。
権限:viewer 以上

POST/hosts/{host_name}/agent-setup

エージェント用の鍵と証明書を発行し、エージェントの設定に必要な値(接続先ポート、サーバー証明書の名前、証明書、秘密鍵、CA 証明書、serial)を返します。本文 {"revoke_previous": true} で、それまでの証明書を同時に失効できます。
権限:admin

GET/hosts/{host_name}/certificates

そのホストに発行した証明書の一覧(新しい順)。[{serial, issued_at, issued_by, revoked_at, revoked_by, revoked}]
権限:admin

POST/hosts/{host_name}/certificates/{serial}/revoke

証明書を失効させます。失効した証明書による接続は、TLS の段階で切断されます。
権限:admin

// GET /hosts/{host_name}
{ "host_name": "app01", "dns_name": "app01.example.com", "ip_address": null,
  "agent_port": 10055, "metrics_port": 9443, "valid_flag": true }

// GET /hosts/{host_name}/metrics
{ "host_name": "app01", "collected_at": "2026-08-06T22:10:00Z", "reachable": true,
  "cpu_usage_percent": 12.3,
  "mem_used_bytes": 1048576000, "mem_total_bytes": 8589934592,
  "disk_used_bytes": 21474836480, "disk_total_bytes": 107374182400 }

reachable が false のときの collected_at は、最後に値を取得できた時刻です。まだ一度も取得していないホストは、各値が null になります。

ワークスペース 提供中

ワークスペースは、ジョブが使うスクリプトなどのファイルを、サーバー(またはマスタのエージェント)から複数のホストへ配布する仕組みです。ジョブの出力ファイルの回収も扱います。

GET/workspaces

ワークスペースの一覧。ページング対応。
権限:viewer 以上

GET/workspaces/{workspace_id}

ワークスペースの詳細。
権限:viewer 以上

POST/workspaces

ワークスペースを作成します。1 つのホストは 1 つのワークスペースにしか入れられません(重なると 409 HOST_IN_OTHER_WORKSPACE)。
権限:admin

PUT/workspaces/{workspace_id}

ワークスペースを更新します(上書き)。
権限:admin

DELETE/workspaces/{workspace_id}

ワークスペースを削除します(論理削除)。
権限:admin

GET/workspaces/{workspace_id}/files

マスタ(サーバー側)のファイルの一覧。[{path, size, modified_at, sha256}]
権限:viewer 以上

PUT/workspaces/{workspace_id}/files

ファイルを分割してアップロードします。本文:{"path", "offset", "data"}(data は base64、1 回 48 KB まで)。offset 0 でファイルを作り直し、それ以外は受け取り済みの大きさと一致するときだけ追記します。
権限:admin

DELETE/workspaces/{workspace_id}/files?path=

ファイル、またはフォルダごと削除します。
権限:admin

GET/workspaces/{workspace_id}/files/content?path=&offset=

ファイルを分割して取得します(1 回 1 MB まで)。応答:{path, size, offset, length, eof, data}
権限:viewer 以上

POST/workspaces/{workspace_id}/deploy

配布を開始します(202)。本文 {"host_names": [...]} は任意で、省略すると配布先ホストすべてに配布します。変更の無いファイルは送りません。
権限:operator 以上

GET/workspaces/{workspace_id}/deployments

ホストごとの最新の配布結果。[{host_name, status, message, started_at, finished_at}]、status は running/ok/error。meta.running で配布中かどうかが分かります。
権限:viewer 以上

GET/workspace-outputs?host_name=

エージェントから回収した出力ファイルの一覧。[{host_name, path, size, modified_at}]
権限:viewer 以上

GET/workspace-outputs/content?host_name=&path=&offset=

回収した出力ファイルを分割して取得します。
権限:viewer 以上

DELETE/workspace-outputs?host_name=&path=

回収した出力ファイルを削除します。path を省略すると、そのホストの分をすべて削除します。
権限:admin

{ "workspace_id": 1, "workspace_name": "夜間バッチ用スクリプト", "valid_flag": true,
  "master": { "type": "server" },
  "exclude_patterns": ["*.tmp", "*.log"],
  "output_destination": { "target": "server" },
  "update_mode": "auto",
  "target_hosts": ["app01", "app02"] }
  • master:{"type": "server"} または {"type": "agent", "host_name": "..."}。
  • output_destination:{"target": "server"} または {"target": "agent", "host_name": "..."}。
  • update_mode:auto はジョブの実行直前にそのホストへ自動で配布します。manual は配布せず、エージェント側のファイルが古い場合に警告します。
  • パスに ..・絶対パス・.mcha_ で始まる要素は使えません(400)。配布中のファイル変更は 409 DEPLOY_RUNNING です。
  • マスタから削除したファイルは、エージェント側では削除されません。

実行 提供中

ジョブネットの実行状況の参照と、手動起動・中断・保留ジョブのリリースを行います。実行は inner_jobnet_id(整数)で識別します。

GET/executions

実行中・実行済みのジョブネットの一覧(新しい順)。ページング対応。
権限:viewer 以上

POST/executions

ジョブネットを手動で起動します(201)。本文:{"jobnet_id", "scheduled_time"?, "env"?}。scheduled_time を省略すると即時に起動します。env で、この実行で使う変数の初期値を渡せます。応答:{"inner_jobnet_id"}
権限:operator 以上

GET/executions/{inner_jobnet_id}

実行の詳細。各ジョブの状態・開始/終了時刻・フローを含みます。
権限:viewer 以上

POST/executions/{inner_jobnet_id}/abort

実行を強制中断します。終了済みの実行は 409 ALREADY_TERMINAL。
権限:operator 以上

POST/executions/{inner_jobnet_id}/jobs/{job_id}/release

保留中のジョブをリリースします。前のジョブがすべて終わっていれば、すぐに実行されます。保留されていないジョブを指定しても何も起きません。
権限:operator 以上

// GET /executions の 1 行
{ "inner_jobnet_id": 12345, "jobnet_id": "JN0001", "jobnet_name": "夜間バッチ",
  "status": "run", "job_status": "normal",
  "scheduled_time": "2026-08-06T22:00:00Z", "start_time": "2026-08-06T22:00:03Z", "end_time": null,
  "running_job_id": "J003", "running_job_name": "集計処理",
  "schedule_id": "SCH01" }
項目値
statusbegin(起動待ち)・ready(実行待ち)・run(実行中)・end(正常終了)・runerr(実行エラー)・enderr(異常終了)・abort(中断)・interrupted(サーバー再起動などで結果不明)。ジョブネットとジョブで共通です。
job_statusnormal・timeout・error・unknown

詳細(GET /executions/{inner_jobnet_id})は、ジョブネットの詳細と同じ構造に、実行時の status・時刻・timeout_flag を加えたものです。各ジョブの held は保留中かどうか、jobnet_call・jobnet_submit のジョブの child_inner_jobnet_id は起動した子ジョブネットの実行 ID です。ジョブの設定は実行した時点のものを返します。

実行ログ 提供中

GET/logs

実行ログを検索します(新しい順)。ページング対応。
権限:viewer 以上

パラメーター内容
jobnet_id / job_id / inner_jobnet_id対象で絞り込みます
from / to期間(ISO 8601 UTC、例 2026-08-06T00:00:00Z)
errors_only1 で、正常終了以外(エラー・中断・タイムアウト・ユーザーによる中断)だけにします
qジョブネット ID・名前、ジョブ ID・名前の部分一致
limit / offsetページング
{ "ok": true, "data": [
  { "log_date": "2026-08-06T22:03:10Z",
    "inner_jobnet_id": 12345, "jobnet_id": "JN0001", "jobnet_name": "夜間バッチ",
    "inner_job_id": 1001, "job_id": "J001", "job_name": "集計処理",
    "user_name": "batchuser",
    "jobnet_status": "run", "job_status": "end",
    "return_code": "0", "std_out": "...", "std_err": null,
    "message_id": "job.end", "message": "job.end" }
], "meta": { "total_count": 4821, "limit": 100, "offset": 0 } }
  • job_id などジョブの項目が null の行は、ジョブネット全体に関するログです。
  • std_out はエージェントが返した標準出力と標準エラーを合わせたもの(約 8 KB まで)です。std_err は現在は常に null です。
  • message は現在 message_id と同じ値です。表示する文言はクライアント側で message_id から作ってください。

AI 接続 提供中

AI 接続は、AI ジョブが指示文を送る先(Claude、OpenAI、OpenAI 互換のローカル LLM)です。ジョブは connection_name で参照するため、名前は後から変えられません。

GET/ai/connections

AI 接続の一覧。
権限:admin

GET/ai/connections/{connection_name}

AI 接続の詳細。
権限:admin

POST/ai/connections

AI 接続を作成します(201)。同じ名前があると 409 ALREADY_EXISTS。
権限:admin

PUT/ai/connections/{connection_name}

送った項目だけを変更します。
権限:admin

DELETE/ai/connections/{connection_name}

AI 接続を削除します。
権限:admin

{ "connection_name": "local-llm", "provider": "openai_compatible",
  "base_url": "http://gpu01.example.com:11434/v1",
  "effective_base_url": "http://gpu01.example.com:11434/v1",
  "default_model": "qwen2.5:14b",
  "has_api_key": false, "api_key_env": null, "is_online": true,
  "defaults": { "temperature": 0, "max_output_tokens": 2000, "timeout": 300 },
  "daily_token_limit": 500000 }
  • provider:anthropic・openai・openai_compatible。openai_compatible は base_url が必須で、API キーは任意です。ほかの 2 つは api_key か api_key_env が必須です。
  • api_key:書き込み専用です。サーバーで AES-256-GCM により暗号化して保存します。PUT で省略すると今のキーを残し、"" を送ると削除します。
  • api_key_env:キーをサーバーに置かず、エージェントのホストの環境変数から読みます。api_key と同時には指定できません。
  • is_online:接続先が社外のアドレスかどうか(localhost・プライベートアドレス・社内向けの名前以外なら true)。
  • daily_token_limit:1 日に使えるトークン数。null または 0 で上限なし。上限に達すると、その接続を使う AI ジョブは AI に問い合わせずに異常終了(終了コード 4)になります。

試しに実行・疎通確認・使用量

AI の応答には時間がかかるため、「開始」と「結果の取得」を分けています。開始すると 202 と try_id が返り、結果は GET /ai/try/{try_id} で取得します。試しに実行の記録は、終了後 1 時間保持します(サーバーを再起動すると消えます)。使ったトークンは 1 日の上限にも数えます。

POST/ai/try

llm ジョブの設定で 1 回だけ問い合わせます(ジョブネットは動かしません)。本文:{"type_config": {...}, "values": {"MAIL_BODY": "見本の値"}}。応答(202):{"try_id", "status": "running"}
権限:operator 以上

GET/ai/try/{try_id}

試しに実行の結果。{"status", "result", "message", "values", "usage", "transcript"}、status は running/done/failed。他のユーザーの試しは admin だけが参照できます。
権限:operator 以上

POST/ai/connections/{connection_name}/test

指定したエージェントから短い質問を送り、AI 接続の疎通を確認します。本文:{"host_name", "model"?}。結果は GET /ai/try/{try_id} で取得します。
権限:admin

GET/ai/usage?days=30

AI 接続ごと・日ごとの使用量(新しい日から)。[{date, connection_name, input_tokens, output_tokens, requests}]。days は 1〜366、初期値 30。
権限:admin

開始時のエラー:400(設定の誤り、接続・ホストが無い)、409 OVER_LIMIT(1 日の上限)、502 AGENT_UNREACHABLE(エージェントに届かない)、503 UNAVAILABLE(同時に 32 件を超えるなど)。

指示文のひな型 提供中

よく使う指示文・お手本・答えの形式をひな型として保存し、複数の AI ジョブから template で参照できます。ジョブ側に書いた項目は、ひな型の同じ項目より優先されます。

GET/ai/templates

ひな型の一覧(内容を含む、名前順)。
権限:viewer 以上

GET/ai/templates/{template_name}

ひな型の詳細と、そのひな型を使っているジョブの一覧 used_by([{"jobnet_id", "job_id"}])。
権限:viewer 以上

POST/ai/templates

ひな型を作成します(201)。同じ名前があると 409 ALREADY_EXISTS。
権限:admin

PUT/ai/templates/{template_name}

送った項目だけを変更します。名前は変えられません。
権限:admin

DELETE/ai/templates/{template_name}

ひな型を削除します。ジョブが使っている間は 409 IN_USE。
権限:admin

{ "template_name": "mail-classify", "description": "問い合わせメールの分類",
  "system": "あなたは問い合わせ窓口の担当者です。",
  "prompt": "次のメールを分類してください。\n$MAIL_BODY",
  "goal": null,
  "examples": [ { "input": "請求書の再発行をお願いします", "output": "{\"category\":\"請求\"}" } ],
  "output": { "format": "json", "fields": { "category": "CATEGORY" } },
  "variables": [ { "name": "MAIL_BODY", "description": "メール本文", "sample": "サーバーが止まっています" } ],
  "update_date": "2026-10-26 07:00:00" }

名前は英数字と _・-・. で 64 文字まで、system・prompt・goal は各 64 KB までです。variables は変数の説明と見本の値で、試しに実行の初期値に使います。update_date は UTC の YYYY-MM-DD HH:MM:SS 形式です。

ユーザー・グループ 提供中

GET/users

ユーザーの一覧。ページング対応。
権限:admin

GET/users/{user_id}

ユーザーの詳細。
権限:admin

POST/users

ユーザーを作成します。エディションのユーザー数上限を超える場合は 403 LICENSE_LIMIT。
権限:admin

PUT/users/{user_id}

ユーザーを更新します(上書き)。password を省略すると今のパスワードを残します。
権限:admin

DELETE/users/{user_id}

ユーザーを削除します(論理削除)。
権限:admin

GET/user-groups

グループの一覧。ページング対応。
権限:admin

GET/user-groups/{group_id}

グループの詳細。
権限:admin

POST/user-groups

グループを作成します。
権限:admin

PUT/user-groups/{group_id}

グループを更新します。member_user_ids を送ると、メンバーをその内容で置き換えます(省略時は変更しません)。
権限:admin

DELETE/user-groups/{group_id}

グループを削除します(論理削除)。
権限:admin

// ユーザー
{ "user_id": 1, "username": "admin", "lang": "ja", "role": "admin", "valid_flag": true,
  "has_password": true, "group_ids": [1] }

// グループ(jobnet_ids は参照のみ:このグループに公開範囲を限定したジョブネット)
{ "group_id": 1, "group_name": "運用チーム", "valid_flag": true,
  "member_user_ids": [2, 3], "jobnet_ids": ["JN0001"] }
  • username は 1〜63 バイト、role は admin・operator・viewer、lang は ja・en、password は 8 文字以上です。
  • 有効な admin が 1 人もいなくなる変更(最後の admin のロール変更・無効化・削除)は 409 LAST_ADMIN になります。
  • パスワードはそのまま保存せず、ハッシュとして保存します。

通知チャネル 提供中

ジョブの異常終了などをメールまたは Webhook で通知します。各チャネルは min_severity(info・warn・error・crit)以上の重大度のメッセージだけを送ります。

GET/notification-channels

通知チャネルの一覧。ページング対応。
権限:admin

GET/notification-channels/{channel_id}

通知チャネルの詳細。
権限:admin

POST/notification-channels

通知チャネルを作成します。
権限:admin

PUT/notification-channels/{channel_id}

通知チャネルを更新します(上書き)。smtp_password を省略すると今の値を残します。
権限:admin

DELETE/notification-channels/{channel_id}

通知チャネルを削除します(論理削除)。
権限:admin

POST/notification-channels/{channel_id}/test

テスト通知を実際に送信します。失敗した場合は、message に理由(英語)が入ります。
権限:admin

// メール
{ "channel_id": 1, "channel_name": "運用チーム宛メール", "channel_type": "email", "valid_flag": true,
  "min_severity": "warn",
  "config": { "smtp_host": "smtp.example.com", "smtp_port": 587, "smtp_security": "starttls",
              "smtp_username": "notifier@example.com", "has_smtp_password": true,
              "from_address": "notifier@example.com", "to_addresses": ["ops@example.com"] } }

// Webhook
{ "channel_id": 2, "channel_name": "チャット通知", "channel_type": "webhook", "valid_flag": true,
  "min_severity": "error",
  "config": { "webhook_url": "https://hooks.example.com/services/..." } }
  • smtp_security:starttls(587 番など)・ssl(465 番など、接続直後から TLS)・none(平文)。
  • メールの宛先は 1〜8 件です。件名・本文は UTF-8 で送るため、日本語のジョブネット名も文字化けしません。
  • 現在、メール・Webhook の送信先サーバーの証明書は検証していません(通信は暗号化されます)。

エクスポート/インポート 提供中

ジョブネット・カレンダー・スケジュールと、ジョブが使うワークスペースのファイルを、1 つのパッケージファイル(.matcha、JSON 形式)にまとめて別のサーバーへ移せます。パスワード、秘密情報らしい名前の環境変数の値、グループの指定、実行履歴は含めません。

エクスポート

POST/exports

パッケージを作成します(201)。本文:{jobnet_ids[], calendar_ids[], schedule_ids[], include_dependencies, include_files, title, description}。呼び出し先ジョブネットやカレンダーなど、依存する定義も自動で含めます。応答:{export_id, size, sha256, contents, warnings}
権限:admin

GET/exports/{export_id}/content?offset=

パッケージを分割して取得します(1 回 1 MB まで)。応答:{offset, length, eof, data}
権限:admin

DELETE/exports/{export_id}

作成したパッケージを削除します。削除しなくても 1 時間で自動的に削除されます。
権限:admin

インポート

POST/imports

インポートを開始します(201)。本文:{size, sha256}。応答:{import_id}
権限:admin

PUT/imports/{import_id}/content

パッケージを分割してアップロードします。本文:{offset, data}(base64、1 回 48 KB まで。リクエスト全体の上限があるため 36 KB 程度ずつの送信を推奨します)。
権限:admin

POST/imports/{import_id}/preview

取り込む内容を確認します(何も書き込みません)。定義ごとの新規/既存、割り当てが必要なホスト・実行ユーザー、実行されるコマンドの一覧、ファイル、警告を返します。
権限:admin

POST/imports/{import_id}/apply

取り込みます。すべて取り込むか、何も取り込まないかのどちらかです(1 トランザクション)。
権限:admin

DELETE/imports/{import_id}

インポートを破棄します。破棄しなくても 1 時間で自動的に削除されます。
権限:admin

// POST /imports/{import_id}/apply の本文
{ "host_map":     { "app01": "prod-app01" },
  "run_user_map": { "batch": "batch" },
  "jobnets":   { "NIGHTLY": "overwrite", "SUB01": "skip", "SUB02": { "rename": "SUB02_B" } },
  "calendars": { "BANK": "overwrite" },
  "schedules": { "NIGHT": "skip" },
  "workspaces": { "ws1": { "into": "new" } } }
  • 同じ ID がある定義は、skip・overwrite(新しい版として保存)・{"rename": "新しいID"} のいずれかを指定します。指定が無いと 400 CONFLICT_UNRESOLVED です。
  • パッケージ内のホスト名・実行ユーザーは、取り込み先の値への割り当てがすべて必要です。割り当て先のホストは登録済みである必要があります。
  • スケジュールは必ず停止状態(enabled=false)で取り込まれます。パスワードは取り込まれないため、必要なジョブは取り込み後に設定してください。
  • パッケージの上限は初期値 64 MB です(サーバー設定 PackageMaxBytes)。

ライセンス 提供中

GET/license

現在のエディション、上限と使用数、ライセンス情報、このサーバーのサーバー ID を返します。
権限:viewer 以上

PUT/license

ライセンスを適用します。本文:{"license": "<ライセンスファイルの内容>"}。形式・署名が正しくない場合は 400 INVALID_LICENSE、別のサーバー向けの場合は 400 LICENSE_OTHER_SERVER。
権限:admin

DELETE/license

ライセンスを削除し、Community Edition に戻します。
権限:admin

PUT/license/history

実行履歴を残す日数を設定します(PRO Edition のみ。Community Edition では 403 LICENSE_LIMIT)。本文:{"history_days": 0〜36500}、0 はすべて保存します。
権限:admin

GET /license の主な項目:edition(community/pro)、max_agents・max_users(上限)、agents_used・users_used(使用数)、history_days(実行履歴の保存日数、null はすべて保存)、license_id・licensee・issued_at・support_until・valid_until、server_id(このサーバー)、license_server_id(ライセンスの紐づけ先、null はどのサーバーでも有効)。ライセンスが無い場合は Community Edition(ホスト 5・ユーザー 1・実行履歴 30 日)として動作します。

curl での呼び出し例

以下の例では、サーバー証明書を matcha-server.crt として保存し、--cacert で信頼させています。ホスト名・パスワードはお使いの環境に置き換えてください。

サインイン

curl --cacert matcha-server.crt \
  -X POST https://matcha.example.com:10057/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "<パスワード>"}'

{ "ok": true, "data": { "session_token": "3f9c...e1a7", "user_id": 1,
  "username": "admin", "role": "admin", "lang": "ja" } }

実行状況の一覧を取得(GET)

TOKEN="3f9c...e1a7"
curl --cacert matcha-server.crt \
  "https://matcha.example.com:10057/executions?limit=20" \
  -H "Authorization: Bearer $TOKEN"

{ "ok": true, "data": [ { "inner_jobnet_id": 12345, "jobnet_id": "JN0001", "status": "run", ... } ],
  "meta": { "total_count": 128, "limit": 20, "offset": 0 } }

ジョブネットを手動で起動(POST)

curl --cacert matcha-server.crt \
  -X POST https://matcha.example.com:10057/executions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jobnet_id": "JN0001", "env": {"BASE_DATE": "20261028"}}'

{ "ok": true, "data": { "inner_jobnet_id": 12401 } }

起動した実行の状況は GET /executions/12401 で確認できます。

最終更新: 2026年10月28日