API リファレンス
MATCHA サーバーは、HTTPS で JSON をやりとりする REST API を提供しています。MATCHA Manager とコマンドツールもこの API を使っており、同じ操作をお客様のシステムから自動化できます。
はじめに
このページは、workload automation MATCHA のサーバーが提供する API の仕様です。製品の全体像は 概要、構成や動作環境は 技術仕様、Manager の画面操作は 操作マニュアル をご覧ください。
| ベース URL | https://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)を返します。
サインインしてセッショントークンを受け取ります。本文:{"username", "password"}。応答:{"session_token", "user_id", "username", "role", "lang"}。
権限:不要
現在のセッションを終了します。トークンが無い・すでに無効な場合もエラーにはなりません。
権限:不要
サインイン中のユーザーが自分のパスワードを変更します。本文:{"current_password", "new_password"}。新しいパスワードは 8 文字以上です。現在のパスワードが違う場合は 403 INVALID_CREDENTIALS。
権限:すべてのロール
ロールと権限
ユーザーには 3 段階のロールのいずれかを設定します。上位のロールは下位のロールの権限をすべて持ちます。権限が足りない操作は 403 FORBIDDEN になります。各エンドポイントの「権限」は、必要な最低のロールを示しています。
| role | できること |
|---|---|
viewer | 実行状況・実行ログ・定義の参照 |
operator | viewer の権限に加えて、ジョブネットの手動起動・強制中断・保留ジョブのリリース、ワークスペースの配布、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)は、クエリ文字列でページングできます。
| パラメーター | 内容 |
|---|---|
limit | 1 回に返す件数。初期値 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 で省略した場合は、今の値をそのまま残します。
エラーコード
| HTTP | code | 意味 |
|---|---|---|
| 400 | VALIDATION_ERROR | 必須項目の不足、値の形式・範囲の誤り、JSON として読めない本文など |
| 400 | INVALID_LICENSE | ライセンスファイルの形式・署名が正しくない |
| 400 | LICENSE_OTHER_SERVER | 別のサーバー向けに発行されたライセンス |
| 400 | PACKAGE_INVALID / PACKAGE_UNSUPPORTED | パッケージの内容が正しくない/対応していない形式の版 |
| 400 | PARAMETER_UNMAPPED | インポートで、割り当てが必要なホスト・実行ユーザーが未指定 |
| 400 | CONFLICT_UNRESOLVED | インポートで、同じ ID の定義があるのに扱い(skip・overwrite・rename)が未指定 |
| 400 | HOST_NOT_FOUND | インポートの割り当て先ホストが登録されていない |
| 401 | AUTH_REQUIRED | トークンが無い、不正、または期限切れ |
| 401 | INVALID_CREDENTIALS | サインインのユーザー名またはパスワードが違う(PUT /me/password では 403) |
| 403 | FORBIDDEN | ロールの権限が足りない |
| 403 | LICENSE_LIMIT | エディションの上限(ホスト数・ユーザー数など)を超える操作 |
| 404 | NOT_FOUND | 対象が存在しない、または見る権限が無い。存在しないパス |
| 409 | ALREADY_EXISTS | 同じ ID・名前がすでにある |
| 409 | ALREADY_TERMINAL | 終了済みの実行を中断しようとした |
| 409 | LAST_ADMIN | 有効な admin が 1 人もいなくなる変更 |
| 409 | IN_USE | ジョブが使っている AI ひな型を削除しようとした |
| 409 | HOST_IN_OTHER_WORKSPACE | そのホストは別のワークスペースの配布先になっている |
| 409 | DEPLOY_RUNNING | そのワークスペースは配布中 |
| 409 | OFFSET_MISMATCH | 分割アップロードの位置が、受け取り済みの大きさと合わない |
| 409 | UPLOAD_INCOMPLETE | パッケージのアップロードが終わっていない |
| 409 | CA_UNAVAILABLE | エージェント用証明書を発行する CA を使えない |
| 409 | NAME_CONFLICT | サーバー自身の証明書と同じ名前のホストには証明書を発行できない |
| 409 | OVER_LIMIT | AI 接続の 1 日のトークン上限に達している |
| 413 | PACKAGE_TOO_LARGE | パッケージがサーバーの上限(初期値 64 MB)を超える |
| 500 | INTERNAL_ERROR | サーバー内部のエラー(データベースのエラーなど) |
| 502 | AGENT_UNREACHABLE | エージェントに接続できない |
| 503 | UNAVAILABLE | 一時的に受け付けられない(同時に実行できる件数の超過など) |
ジョブネット 提供中
ジョブネットは、ジョブとその実行順(フロー)をまとめた定義です。jobnet_id は作成時にクライアントが指定する識別子です。
ジョブネットの一覧(ジョブ・フローは含まない要約)。ページング対応。
権限:viewer 以上
ジョブネットの詳細。ジョブ・フロー・画面上の配置を含みます。
権限:viewer 以上
ジョブネットを作成します。本文は詳細と同じ形です。
権限:admin
ジョブネット全体を置き換えます(新しい版として保存)。group_ids を省略すると、公開範囲のグループは変更しません。
権限:admin
ジョブネットを削除します(論理削除)。
権限: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 | ジョブネットを終了します | 提供中 |
llm | AI 問い合わせ。指示文を 1 回送り、答えを変数やファイルに受け取ります。type_config:host_name・connection(AI 接続の名前)・prompt が必須。任意で model・template・system・examples・inputs・references・output・temperature・max_output_tokens・timeout・retries | 提供中 |
ai_agent | AI エージェント。目的を渡すと、AI が許可された道具(ファイルの読み書き・許可したコマンド)を使って作業します。定義として保存はできますが、現在のサーバーはこの種類のジョブをエージェントへ送りません。 | 開発中 |
file_copy | ホスト間のファイル転送。種類としては予約済みですが、処理は未実装です。 | 予定 |
llm ジョブの $変数 はサーバーが実行時に置き換えて送ります。答えは output の指定に従って変数(初期値 AI_ANSWER)に入り、後続の condition ジョブで分岐に使えます。AI 接続の API キーはサーバーが管理し、各エージェントに配る必要はありません。
カレンダー 提供中
カレンダーは稼働日の一覧です。スケジュールが起動する日を決めます。
カレンダーの一覧。ページング対応。
権限:viewer 以上
カレンダーの詳細。
権限:viewer 以上
カレンダーを作成します。
権限:admin
カレンダーを更新します(新しい版として保存)。
権限:admin
カレンダーを削除します(論理削除)。
権限: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 になります。
スケジュール 提供中
スケジュールは、カレンダーと起動時刻の組み合わせで、ジョブネットを自動起動します。
スケジュールの一覧。ページング対応。
権限:viewer 以上
スケジュールの詳細。
権限:viewer 以上
スケジュールを作成します。
権限:admin
スケジュールを更新します(新しい版として保存)。enabled を省略すると直前の版の値を引き継ぎます。
権限:admin
スケジュールを削除します(論理削除)。
権限: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 で識別します。
ホストの一覧。ページング対応。
権限:viewer 以上
ホストの詳細。
権限:viewer 以上
ホストを登録します。エディションのホスト数上限を超える場合は 403 LICENSE_LIMIT。
権限:admin
ホストを更新します(上書き)。
権限:admin
ホストを削除します(論理削除)。そのホストに発行した証明書はすべて失効します。
権限:admin
サーバーが収集した最新の CPU・メモリ・ディスク使用量と疎通状況。
権限:viewer 以上
エージェント用の鍵と証明書を発行し、エージェントの設定に必要な値(接続先ポート、サーバー証明書の名前、証明書、秘密鍵、CA 証明書、serial)を返します。本文 {"revoke_previous": true} で、それまでの証明書を同時に失効できます。
権限:admin
そのホストに発行した証明書の一覧(新しい順)。[{serial, issued_at, issued_by, revoked_at, revoked_by, revoked}]
権限:admin
証明書を失効させます。失効した証明書による接続は、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 になります。
ワークスペース 提供中
ワークスペースは、ジョブが使うスクリプトなどのファイルを、サーバー(またはマスタのエージェント)から複数のホストへ配布する仕組みです。ジョブの出力ファイルの回収も扱います。
ワークスペースの一覧。ページング対応。
権限:viewer 以上
ワークスペースの詳細。
権限:viewer 以上
ワークスペースを作成します。1 つのホストは 1 つのワークスペースにしか入れられません(重なると 409 HOST_IN_OTHER_WORKSPACE)。
権限:admin
ワークスペースを更新します(上書き)。
権限:admin
ワークスペースを削除します(論理削除)。
権限:admin
マスタ(サーバー側)のファイルの一覧。[{path, size, modified_at, sha256}]
権限:viewer 以上
ファイルを分割してアップロードします。本文:{"path", "offset", "data"}(data は base64、1 回 48 KB まで)。offset 0 でファイルを作り直し、それ以外は受け取り済みの大きさと一致するときだけ追記します。
権限:admin
ファイル、またはフォルダごと削除します。
権限:admin
ファイルを分割して取得します(1 回 1 MB まで)。応答:{path, size, offset, length, eof, data}
権限:viewer 以上
配布を開始します(202)。本文 {"host_names": [...]} は任意で、省略すると配布先ホストすべてに配布します。変更の無いファイルは送りません。
権限:operator 以上
ホストごとの最新の配布結果。[{host_name, status, message, started_at, finished_at}]、status は running/ok/error。meta.running で配布中かどうかが分かります。
権限:viewer 以上
エージェントから回収した出力ファイルの一覧。[{host_name, path, size, modified_at}]
権限:viewer 以上
回収した出力ファイルを分割して取得します。
権限:viewer 以上
回収した出力ファイルを削除します。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(整数)で識別します。
実行中・実行済みのジョブネットの一覧(新しい順)。ページング対応。
権限:viewer 以上
ジョブネットを手動で起動します(201)。本文:{"jobnet_id", "scheduled_time"?, "env"?}。scheduled_time を省略すると即時に起動します。env で、この実行で使う変数の初期値を渡せます。応答:{"inner_jobnet_id"}
権限:operator 以上
実行の詳細。各ジョブの状態・開始/終了時刻・フローを含みます。
権限:viewer 以上
実行を強制中断します。終了済みの実行は 409 ALREADY_TERMINAL。
権限:operator 以上
保留中のジョブをリリースします。前のジョブがすべて終わっていれば、すぐに実行されます。保留されていないジョブを指定しても何も起きません。
権限: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" }
| 項目 | 値 |
|---|---|
status | begin(起動待ち)・ready(実行待ち)・run(実行中)・end(正常終了)・runerr(実行エラー)・enderr(異常終了)・abort(中断)・interrupted(サーバー再起動などで結果不明)。ジョブネットとジョブで共通です。 |
job_status | normal・timeout・error・unknown |
詳細(GET /executions/{inner_jobnet_id})は、ジョブネットの詳細と同じ構造に、実行時の status・時刻・timeout_flag を加えたものです。各ジョブの held は保留中かどうか、jobnet_call・jobnet_submit のジョブの child_inner_jobnet_id は起動した子ジョブネットの実行 ID です。ジョブの設定は実行した時点のものを返します。
実行ログ 提供中
実行ログを検索します(新しい順)。ページング対応。
権限:viewer 以上
| パラメーター | 内容 |
|---|---|
jobnet_id / job_id / inner_jobnet_id | 対象で絞り込みます |
from / to | 期間(ISO 8601 UTC、例 2026-08-06T00:00:00Z) |
errors_only | 1 で、正常終了以外(エラー・中断・タイムアウト・ユーザーによる中断)だけにします |
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 で参照するため、名前は後から変えられません。
AI 接続の一覧。
権限:admin
AI 接続の詳細。
権限:admin
AI 接続を作成します(201)。同じ名前があると 409 ALREADY_EXISTS。
権限:admin
送った項目だけを変更します。
権限:admin
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 日の上限にも数えます。
llm ジョブの設定で 1 回だけ問い合わせます(ジョブネットは動かしません)。本文:{"type_config": {...}, "values": {"MAIL_BODY": "見本の値"}}。応答(202):{"try_id", "status": "running"}
権限:operator 以上
試しに実行の結果。{"status", "result", "message", "values", "usage", "transcript"}、status は running/done/failed。他のユーザーの試しは admin だけが参照できます。
権限:operator 以上
指定したエージェントから短い質問を送り、AI 接続の疎通を確認します。本文:{"host_name", "model"?}。結果は GET /ai/try/{try_id} で取得します。
権限:admin
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 で参照できます。ジョブ側に書いた項目は、ひな型の同じ項目より優先されます。
ひな型の一覧(内容を含む、名前順)。
権限:viewer 以上
ひな型の詳細と、そのひな型を使っているジョブの一覧 used_by([{"jobnet_id", "job_id"}])。
権限:viewer 以上
ひな型を作成します(201)。同じ名前があると 409 ALREADY_EXISTS。
権限:admin
送った項目だけを変更します。名前は変えられません。
権限:admin
ひな型を削除します。ジョブが使っている間は 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 形式です。
ユーザー・グループ 提供中
ユーザーの一覧。ページング対応。
権限:admin
ユーザーの詳細。
権限:admin
ユーザーを作成します。エディションのユーザー数上限を超える場合は 403 LICENSE_LIMIT。
権限:admin
ユーザーを更新します(上書き)。password を省略すると今のパスワードを残します。
権限:admin
ユーザーを削除します(論理削除)。
権限:admin
グループの一覧。ページング対応。
権限:admin
グループの詳細。
権限:admin
グループを作成します。
権限:admin
グループを更新します。member_user_ids を送ると、メンバーをその内容で置き換えます(省略時は変更しません)。
権限:admin
グループを削除します(論理削除)。
権限: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)以上の重大度のメッセージだけを送ります。
通知チャネルの一覧。ページング対応。
権限:admin
通知チャネルの詳細。
権限:admin
通知チャネルを作成します。
権限:admin
通知チャネルを更新します(上書き)。smtp_password を省略すると今の値を残します。
権限:admin
通知チャネルを削除します(論理削除)。
権限:admin
テスト通知を実際に送信します。失敗した場合は、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 形式)にまとめて別のサーバーへ移せます。パスワード、秘密情報らしい名前の環境変数の値、グループの指定、実行履歴は含めません。
エクスポート
パッケージを作成します(201)。本文:{jobnet_ids[], calendar_ids[], schedule_ids[], include_dependencies, include_files, title, description}。呼び出し先ジョブネットやカレンダーなど、依存する定義も自動で含めます。応答:{export_id, size, sha256, contents, warnings}
権限:admin
パッケージを分割して取得します(1 回 1 MB まで)。応答:{offset, length, eof, data}
権限:admin
作成したパッケージを削除します。削除しなくても 1 時間で自動的に削除されます。
権限:admin
インポート
インポートを開始します(201)。本文:{size, sha256}。応答:{import_id}
権限:admin
パッケージを分割してアップロードします。本文:{offset, data}(base64、1 回 48 KB まで。リクエスト全体の上限があるため 36 KB 程度ずつの送信を推奨します)。
権限:admin
取り込む内容を確認します(何も書き込みません)。定義ごとの新規/既存、割り当てが必要なホスト・実行ユーザー、実行されるコマンドの一覧、ファイル、警告を返します。
権限:admin
取り込みます。すべて取り込むか、何も取り込まないかのどちらかです(1 トランザクション)。
権限:admin
インポートを破棄します。破棄しなくても 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)。
ライセンス 提供中
現在のエディション、上限と使用数、ライセンス情報、このサーバーのサーバー ID を返します。
権限:viewer 以上
ライセンスを適用します。本文:{"license": "<ライセンスファイルの内容>"}。形式・署名が正しくない場合は 400 INVALID_LICENSE、別のサーバー向けの場合は 400 LICENSE_OTHER_SERVER。
権限:admin
ライセンスを削除し、Community Edition に戻します。
権限:admin
実行履歴を残す日数を設定します(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日