定義

定義のマニフェスト・ReleaseBundle・有効なバージョン。apply は dev だけで受け付け、すぐには効かない

説明は公開 API の契約（OpenAPI）から生成しています。

エンドポイント

POST	/v1/definitions/diff
POST	/v1/definitions/apply
GET	/v1/definitions/drafts
GET	/v1/definitions/drafts/{kind}/{name}
GET	/v1/definitions/releases
POST	/v1/definitions/releases
POST	/v1/definitions/releases/import
GET	/v1/definitions/releases/{id}/bundle
GET	/v1/definitions/releases/{id}
DELETE	/v1/definitions/releases/{id}
POST	/v1/definitions/releases/{id}/review
POST	/v1/definitions/releases/{id}/activate
GET	/v1/definitions/active
GET	/v1/definitions/at
POST	/v1/definitions/rollback
POST	/v1/definitions/settings/{kind}/{name}/rollback
POST	/v1/definitions/releases/{id}/canary
POST	/v1/definitions/canary/promote
POST	/v1/definitions/canary/abort
GET	/v1/definitions/git-sources
GET	/v1/definitions/git-sources/{name}
DELETE	/v1/definitions/git-sources/{name}
POST	/v1/definitions/git-sources/{name}/sync
POST	/v1/definitions/git-sources/{name}/webhook
POST	/v1/definitions/git-webhooks/github/{tenant}/{project}/{name}
POST	/v1/definitions/git-sources/{name}/pause
POST	/v1/definitions/git-sources/{name}/resume

diffDefinitions

POST/v1/definitions/diff

リクエストの本文

application/json — ManifestsInput

名前	型	必須	説明
manifests	Manifest[]	はい
prune	boolean
source	object

応答

• 200 — DiffResult: 差分と検証の結果
• default — Problem: RFC 9457 Problem Details

applyDefinitions

POST/v1/definitions/apply

定義は dev だけで受け付け、draft を作る（有効にするのは ReleaseBundle の有効化）。設定（EnvironmentBinding）は どの環境でも受け付け、すぐ効く。EnvironmentBinding の名前は環境の名前にする

パラメーター

名前	場所	型	必須	説明
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json — ManifestsInput

名前	型	必須	説明
manifests	Manifest[]	はい
prune	boolean
source	object

応答

• 200 — object: 適用した差分
• default — Problem: RFC 9457 Problem Details

listDrafts

GET/v1/definitions/drafts

パラメーター

名前	場所	型	必須	説明
kind	query	string

応答

• 200 — object: draft
• default — Problem: RFC 9457 Problem Details

describeDraft

GET/v1/definitions/drafts/{kind}/{name}

パラメーター

名前	場所	型	必須	説明
kind	path	string	はい
name	path	string	はい

応答

• 200 — object: draft と定義のバージョンの履歴
• default — Problem: RFC 9457 Problem Details

listReleases

GET/v1/definitions/releases

応答

• 200 — object: ReleaseBundle
• default — Problem: RFC 9457 Problem Details

createRelease

POST/v1/definitions/releases

パラメーター

名前	場所	型	必須	説明
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
bundle	string	はい
include	object[]

応答

• 201 — CreatedRelease: ReleaseBundle
• default — Problem: RFC 9457 Problem Details

importRelease

POST/v1/definitions/releases/import

definitions:release が必要。昇格。前の環境から取り出したマニフェストを、draft を通さずに ReleaseBundle にする。 stage と prod だけで受け付ける。中身が同じなら前の環境と同じ release_id になる。有効化は別に行う

パラメーター

名前	場所	型	必須	説明
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
bundle	string	はい
manifests	Manifest[]	はい

応答

• 201 — CreatedRelease: 作った ReleaseBundle
• default — Problem: RFC 9457 Problem Details

exportRelease

GET/v1/definitions/releases/{id}/bundle

definitions:read が必要。昇格のために、ReleaseBundle のマニフェストを取り出す

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 200 — object: ReleaseBundle とマニフェスト
• default — Problem: RFC 9457 Problem Details

getRelease

GET/v1/definitions/releases/{id}

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 200 — object: ReleaseBundle と中身
• default — Problem: RFC 9457 Problem Details

deleteRelease

DELETE/v1/definitions/releases/{id}

definitions:release が必要。一度も使っていない ReleaseBundle を消す。有効なもの・戻す先・カナリア・有効化を待つもの・ 一度でも有効にしたもの（切り替えの記録が参照する）・案件やスケジュールやレコードが参照するものは消さず、 CONFLICT と残す理由を返す。R2 の本文は digest のキーで不変なので残す

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 204: 消した
• default — Problem: RFC 9457 Problem Details

reviewRelease

POST/v1/definitions/releases/{id}/review

definitions:release が必要。公開ゲートで人が ReleaseBundle を審査して通す。DeciderPolicy で AI に承認を任せる範囲を 広げる ReleaseBundle と、stage・prod で Agent に新しい外への操作のツールを持たせる ReleaseBundle は、この審査がないと 有効化もカナリアもできない。人の主体だけが審査でき、ReleaseBundle を 作った人は審査できない。審査は環境ごとに行う。同じ ReleaseBundle の 2 回目は前の審査を返す

パラメーター

名前	場所	型	必須	説明
id	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
comment	string	はい	何を確かめたか

応答

• 201 — ReleaseReview: 記録した審査
• default — Problem: RFC 9457 Problem Details

activateRelease

POST/v1/definitions/releases/{id}/activate

パラメーター

名前	場所	型	必須	説明
id	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

応答

• 200 — ActiveRelease: 有効なバージョン
• default — Problem: RFC 9457 Problem Details

getActiveRelease

GET/v1/definitions/active

応答

• 200 — object: 有効なバージョンと履歴
• default — Problem: RFC 9457 Problem Details

getDefinitionsAt

GET/v1/definitions/at

definitions:read が必要。time の時点で有効だった ReleaseBundle と、そのときの設定（EnvironmentBinding）のリビジョンを返す。 障害の調査と監査に使う

パラメーター

名前	場所	型	必須	説明
time	query	string	はい

応答

• 200 — object: その時点の有効なバージョンと設定
• default — Problem: RFC 9457 Problem Details

rollbackRelease

POST/v1/definitions/rollback

パラメーター

名前	場所	型	必須	説明
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

応答

• 200 — ActiveRelease: 有効なバージョン
• default — Problem: RFC 9457 Problem Details

rollbackSetting

POST/v1/definitions/settings/{kind}/{name}/rollback

設定（EnvironmentBinding・RoleBinding・SourcePolicy）を 1 つ前のリビジョンに戻す。apply と同じ確かめを通り、 新しいリビジョンとして残す。Git から同期しているプロジェクトでは受け付けない。

パラメーター

名前	場所	型	必須	説明
kind	path	string	はい
name	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

応答

• 200 — Draft: 戻した設定
• default — Problem: RFC 9457 Problem Details

startCanary

POST/v1/definitions/releases/{id}/canary

definitions:release が必要。有効なバージョンはそのままに、この ReleaseBundle を、始まる Case の percent % に使い始める （対象のレコードの ID のハッシュで決める）。stage と prod では、有効化と同じ確かめ（評価が通ったか）を通す。 データの索引とスケジュールは合わせないので、Workflow・Agent・割り当ての規則の変更を試すためのもの

パラメーター

名前	場所	型	必須	説明
id	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
percent	integer	はい

応答

• 201 — Canary: 始めたカナリア
• default — Problem: RFC 9457 Problem Details

promoteCanary

POST/v1/definitions/canary/promote

definitions:release が必要。カナリアの ReleaseBundle を有効にする（以後はすべての Case が使う）

パラメーター

名前	場所	型	必須	説明
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

応答

• 200 — ActiveRelease: 有効なバージョン
• default — Problem: RFC 9457 Problem Details

abortCanary

POST/v1/definitions/canary/abort

definitions:release が必要。カナリアをやめる。カナリアで始まった Case は、そのバージョンのまま動き続ける

パラメーター

名前	場所	型	必須	説明
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

応答

• 200 — Canary: やめたカナリア
• default — Problem: RFC 9457 Problem Details

listGitSources

GET/v1/definitions/git-sources

definitions:read が必要。pull 型の同期の GitSource と、その同期の状態。GitSource は apply で dev に登録する。 GitSource があるプロジェクトでは、GitSource のほかの apply を受け付けない

応答

• 200 — object: GitSource の一覧
• default — Problem: RFC 9457 Problem Details

getGitSource

GET/v1/definitions/git-sources/{name}

definitions:read が必要

パラメーター

名前	場所	型	必須	説明
name	path	string	はい

応答

• 200 — GitSource: GitSource
• default — Problem: RFC 9457 Problem Details

unregisterGitSource

DELETE/v1/definitions/git-sources/{name}

definitions:apply が必要。登録をやめて push 型に戻す（以後は apply を受け付ける）。反映した定義と ReleaseBundle は残る

パラメーター

名前	場所	型	必須	説明
name	path	string	はい

応答

• 204: 登録をやめた
• default — Problem: RFC 9457 Problem Details

syncGitSource

POST/v1/definitions/git-sources/{name}/sync

definitions:apply と definitions:release が必要。今すぐ ref の先頭のコミットを読んで反映する（Git の通知と同じ）。 検証などで失敗しても 200 で、status の phase が SyncFailed になり、有効な ReleaseBundle は前のまま動く。 一時停止中は 409

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

応答

• 200 — GitSource: 同期した後の状態
• default — Problem: RFC 9457 Problem Details

revealGitSourceWebhook

POST/v1/definitions/git-sources/{name}/webhook

definitions:apply と definitions:release が必要。GitHub の push の webhook に登録する宛先のパスと秘密値を返す。 秘密値は保存せず鍵から導くので、同じ値が返る。見せたことは監査に残る

パラメーター

名前	場所	型	必須	説明
name	path	string	はい

応答

• 200 — object: 宛先と秘密値
• default — Problem: RFC 9457 Problem Details

receiveGitHubWebhook

POST/v1/definitions/git-webhooks/github/{tenant}/{project}/{name}

GitHub だけが呼ぶ。本文の署名（x-hub-signature-256）が、この宛先の秘密値のものであることを確かめる。push が同期する ref のものなら 次の alarm で読みに行くようにする。本文のコミットは使わず、ref の先頭を読み直す。同じ x-github-delivery の再送は保存した応答を返す。 push のほかのイベントと、ほかの ref、一時停止中の GitSource への push は受け流す

パラメーター

名前	場所	型	必須	説明
tenant	path	string	はい
project	path	string	はい
name	path	string	はい
x-hub-signature-256	header	string	はい
x-github-event	header	string	はい
x-github-delivery	header	string	はい

リクエストの本文

application/json

応答

• 200 — object: 受けた結果
• default — Problem: RFC 9457 Problem Details

pauseGitSource

POST/v1/definitions/git-sources/{name}/pause

definitions:apply が必要。同期を止める。止めているあいだは Git を読まず、何も反映しない

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

応答

• 200 — GitSource: 止めた後の状態
• default — Problem: RFC 9457 Problem Details

resumeGitSource

POST/v1/definitions/git-sources/{name}/resume

definitions:apply と definitions:release が必要。同期を再開し、すぐに読みに行く

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

応答

• 200 — GitSource: 再開した後の状態
• default — Problem: RFC 9457 Problem Details