Takosumi API

Takosumi API は、OpenTofu / Terraform module を Git から実行する control plane を公開します。Workspace / Capsule / Run などの用語は用語集を参照してください。

エンドポイントの探索

すべての endpoint は次の discovery を公開します。

http

GET /.well-known/takosumi
GET /v1/capabilities

CLI、dashboard、その他の client は edition 名ではなく capability を参照します。

json

{
  "product": "takosumi",
  "apiBaseUrl": "https://takosumi.example.com/api/v1",
  "api_versions": ["takosumi.dev/v1alpha1"],
  "features": {
    "stacks": true,
    "opentofu_runner": true,
    "oidc": true
  },
  "endpoints": {
    "api": "https://takosumi.example.com/api",
    "capabilities": "https://takosumi.example.com/v1/capabilities",
    "oidc_issuer": "https://takosumi.example.com"
  }
}

field 名は snake_case です。product は常に takosumi で、client は最初にこれを確認します。endpoints.api は origin そのものではなく <origin>/api です。

認証

API client は endpoint の設定に応じて session cookie または bearer token を使います。

http

Authorization: Bearer <token>

どの endpoint も、operator が有効化した方式を capability として公開します。 Takosumi Cloud の API key は personal access token です。S3-compatible endpoint のように標準 protocol 自体が署名方式を持つ場合は、その署名を使います。

OpenTofu Stack API

Stack API は OpenTofu / Terraform module を Git から実行します。既存 provider をそのまま使い、実行は plan → apply の順です。Stack API のエンドポイントはすべて /api/v1 の下にあります。

Cloudflare 固有の import/deploy compatibility profile は廃止済みです。

Workspace

メソッド	パス	説明
GET	`/api/v1/workspaces`	自分が参加している Workspace を一覧する
POST	`/api/v1/workspaces`	Workspace を作る
GET	`/api/v1/workspaces/{workspaceId}`	Workspace を読む
PATCH	`/api/v1/workspaces/{workspaceId}`	Workspace を更新する
GET	`/api/v1/workspaces/{workspaceId}/members`	メンバーを一覧する
POST	`/api/v1/workspaces/{workspaceId}/members`	メンバーを追加する
PATCH	`/api/v1/workspaces/{workspaceId}/members/{subject}`	メンバーの役割を変える
DELETE	`/api/v1/workspaces/{workspaceId}/members/{subject}`	メンバーを外す
GET	`/api/v1/workspaces/{workspaceId}/graph`	Capsule の依存グラフを読む
GET	`/api/v1/workspaces/{workspaceId}/activity`	操作履歴を一覧する
GET	`/api/v1/workspaces/{workspaceId}/usage`	利用量を一覧する
GET	`/api/v1/workspaces/{workspaceId}/billing`	課金状態を読む
GET	`/api/v1/workspaces/{workspaceId}/backups`	制御情報の書き出しを一覧する
POST	`/api/v1/workspaces/{workspaceId}/backups`	制御情報を書き出す
POST	`/api/v1/workspaces/{workspaceId}/plan-update`	Workspace 全体の更新 Run を作る
POST	`/api/v1/workspaces/{workspaceId}/drift-check`	Workspace 全体の差分確認 Run を作る

Workspace を作る

POST /api/v1/workspaces

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/workspaces" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "name": "production",
    "handle": "prod"
  }'

引数	型	説明
`name`	string	表示名
`handle`	string	一意な識別子

成功すると 201 で Workspace (workspaceId を含む) が返ります。

Workspace を読む

GET /api/v1/workspaces/{workspaceId}

bash

curl -s "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/workspaces/ws_example" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

Project と Capsule

メソッド	パス	説明
GET	`/api/v1/workspaces/{workspaceId}/projects`	Project を一覧する
POST	`/api/v1/workspaces/{workspaceId}/projects`	Project を作る
GET	`/api/v1/projects/{projectId}`	Project を読む
GET	`/api/v1/workspaces/{workspaceId}/capsules`	Capsule を一覧する
POST	`/api/v1/workspaces/{workspaceId}/capsules`	Capsule を作る
GET	`/api/v1/capsules/{capsuleId}`	Capsule を読む
PATCH	`/api/v1/capsules/{capsuleId}`	Capsule を更新する
DELETE	`/api/v1/capsules/{capsuleId}`	破棄計画を作る
GET	`/api/v1/capsules/{capsuleId}/outputs`	公開 Output を読む
GET	`/api/v1/capsules/{capsuleId}/usage-summary`	利用量の集計を読む
GET	`/api/v1/capsules/{capsuleId}/state-versions`	StateVersion を一覧する
GET	`/api/v1/capsules/{capsuleId}/dependencies`	依存を一覧する
POST	`/api/v1/capsules/{capsuleId}/dependencies`	依存を作る
DELETE	`/api/v1/dependencies/{dependencyId}`	依存を削除する
GET	`/api/v1/capsules/{capsuleId}/provider-bindings`	ProviderBinding の選択を読む
PUT	`/api/v1/capsules/{capsuleId}/provider-bindings`	ProviderBinding の選択を置き換える
GET	`/api/v1/workspaces/{workspaceId}/current-state-versions`	現在の StateVersion をまとめて読む
GET	`/api/v1/capsule-configs`	Capsule 作成設定を一覧する
GET	`/api/v1/capsule-configs/{capsuleConfigId}`	Capsule 作成設定を読む
PATCH	`/api/v1/capsule-configs/{capsuleConfigId}`	Capsule 作成設定を更新する

Capsule は計画から始まります。作成してから plan → apply の順で実行します。

メソッド	パス	説明
POST	`/api/v1/capsules/{capsuleId}/plan`	計画 Run を作る
POST	`/api/v1/capsules/{capsuleId}/destroy-plan`	破棄計画 Run を作る
POST	`/api/v1/capsules/{capsuleId}/drift-check`	差分確認 Run を作る
POST	`/api/v1/capsules/{capsuleId}/backups`	Capsule のバックアップを作る

Capsule を作る

POST /api/v1/workspaces/{workspaceId}/capsules

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/workspaces/ws_example/capsules" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "name": "example-app",
    "environment": "production",
    "sourceId": "src_example",
    "installConfigId": "capcfg_example"
  }'

引数	型	説明
`name`	string	Capsule 名。DNS 風の slug (`[a-z0-9-]+`)
`environment`	string	環境名 (例: `production`)
`sourceId`	string	登録済み Source
`installConfigId`	string	Capsule 作成設定 (変数・binding の入った設定)
`projectId`	string?	既定以外の Project
`autoUpdate`	boolean?	新しい snapshot ごとに plan を作るか。既定は `false`

plan を作る

POST /api/v1/capsules/{capsuleId}/plan

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/capsules/cap_example/plan" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

Run は必ず計画から始まります。返る Run の id を次の操作で使います。

Run を読む

GET /api/v1/runs/{runId}

bash

curl -s "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/runs/run_example" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

takosumi status run_example
takosumi logs run_example

承認して適用する

承認が必要な設定では、適用の前に承認します。

POST /api/v1/runs/{runId}/approve

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/runs/run_example/approve" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

POST /api/v1/runs/{runId}/apply

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/runs/run_example/apply" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

取り消す

POST /api/v1/runs/{runId}/cancel

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/runs/run_example/cancel" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

取り消したことも記録に残ります。

破棄する

DELETE /api/v1/capsules/{capsuleId}

bash

curl -X DELETE "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/capsules/cap_example" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

削除は破棄計画を作る操作です。内容を確認してから apply します。

Source

メソッド	パス	説明
GET	`/api/v1/sources`	Source を一覧する
POST	`/api/v1/sources`	Source を作る
GET	`/api/v1/sources/{sourceId}`	Source を読む
PATCH	`/api/v1/sources/{sourceId}`	Source のメタ情報を更新する
POST	`/api/v1/sources/{sourceId}/sync`	同期 Run を作る
GET	`/api/v1/sources/{sourceId}/snapshots`	SourceSnapshot を一覧する
POST	`/api/v1/sources/{sourceId}/compatibility-check`	互換性レポートを作る
GET	`/api/v1/compatibility-reports/{reportId}`	互換性レポートを読む

Source を作る

POST /api/v1/sources

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/sources" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "workspaceId": "ws_example",
    "name": "example-app",
    "url": "https://github.com/example/example-app.git",
    "defaultRef": "v1.2.0",
    "defaultPath": "deploy/opentofu"
  }'

引数	型	説明
`workspaceId`	string	所属する Workspace
`name`	string	名前
`url`	string	Git リポジトリの URL
`defaultRef`	string?	追跡する branch / tag / commit。省略時は `HEAD`
`defaultPath`	string?	module ディレクトリ。省略時は `.`
`authConnectionId`	string?	非公開リポジトリを読むための Connection
`autoSync`	boolean?	ref の定期確認を有効にするか。既定は `false`

成功すると 201 で Source が返ります。応答の hookSecret はこのときだけ平文で返ります。webhook に設定するならここで控えます。

Source を同期する

POST /api/v1/sources/{sourceId}/sync

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/sources/src_example/sync" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ "intent": "manual_plan" }'

intent は observe (省略時) または manual_plan です。同期 Run が succeeded になり、sourceSnapshotId が /api/v1/sources/{sourceId}/snapshots に現れてから plan に進みます。

SourceSnapshot を一覧する

GET /api/v1/sources/{sourceId}/snapshots

bash

curl -s "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/sources/src_example/snapshots" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

Run と StateVersion

メソッド	パス	説明
GET	`/api/v1/workspaces/{workspaceId}/runs`	Run を一覧する
GET	`/api/v1/runs/{runId}`	Run を読む
POST	`/api/v1/runs/{runId}/approve`	Run を承認する
POST	`/api/v1/runs/{runId}/apply`	確認済みの Run を適用する
POST	`/api/v1/runs/{runId}/cancel`	Run を取り消す
GET	`/api/v1/runs/{runId}/logs`	Run のログを読む
GET	`/api/v1/runs/{runId}/events`	Run のイベントを読む
GET	`/api/v1/runs/{runId}/cost`	Run の費用見込みを読む
GET	`/api/v1/run-groups/{runGroupId}`	まとめて実行した Run を読む
POST	`/api/v1/run-groups/{runGroupId}/approve`	まとめて実行した Run を承認する
GET	`/api/v1/state-versions/{stateVersionId}`	StateVersion を読む
POST	`/api/v1/state-versions/{stateVersionId}/rollback-plan`	以前の状態に戻す計画を作る

Run には次のものを保存します。

source snapshot (どの commit を実行したか)
OpenTofu version、provider lock digest、ProviderBinding
注入した env の metadata (値は保存しません)
plan / apply の結果、state version、outputs、logs、actor、audit evidence

認証情報と Output の共有

メソッド	パス	説明
GET	`/api/v1/connections`	Connection を一覧する
POST	`/api/v1/connections`	書き込み専用の Connection を作る
POST	`/api/v1/connections/{connectionId}/test`	Connection を検証する
POST	`/api/v1/connections/{connectionId}/revoke`	Connection を失効させる
POST	`/api/v1/connections/oauth/{helperId}/start`	OAuth 補助を開始する
GET	`/api/v1/connections/oauth/{helperId}/callback`	OAuth 補助を完了する
GET	`/api/v1/provider-connections`	Workspace から見える ProviderConnection を一覧する
GET	`/api/v1/credential-recipes`	Credential Recipe を一覧する
GET	`/api/v1/output-shares`	OutputShare を一覧する
POST	`/api/v1/output-shares`	OutputShare を作る
POST	`/api/v1/output-shares/{shareId}/approve`	OutputShare を承認する
POST	`/api/v1/output-shares/{shareId}/revoke`	OutputShare を失効させる

Connection を作る

POST /api/v1/connections

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/connections" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "provider": "registry.opentofu.org/example/example",
    "recipe": "generic-env",
    "authMode": "env",
    "secretPartition": "provider-credentials",
    "values": { "EXAMPLE_API_KEY": "<secret>" }
  }'

引数	型	説明
`provider`	string	完全修飾の provider アドレス
`recipe`	string	使う Credential Recipe の id
`authMode`	string	`env` (環境変数として注入) など
`secretPartition`	string	秘密の保存区画
`values` / `files`	object	渡す秘密。保存後は読み戻せません

CLI の方が楽な場合もあります。

bash

takosumi connections create \
  --provider registry.opentofu.org/example/example \
  --recipe generic-env --auth-mode env \
  --secret-partition provider-credentials \
  --values-file ./provider-credentials.json

検証する

POST /api/v1/connections/{connectionId}/test

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/connections/conn_123/test" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

takosumi connections test conn_123

失効させる

POST /api/v1/connections/{connectionId}/revoke

bash

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/connections/conn_123/revoke" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

takosumi connections revoke conn_123

失効は削除ではありません。以降の Run で使えなくなり、過去の記録は残ります。

dashboard 用の投影

メソッド	パス	説明
GET	`/api/v1/dashboard/bootstrap`	画面の初期表示に必要な情報をまとめて読む
GET	`/api/v1/dashboard/overview`	Workspace の概況を読む

OIDC と workload identity

Takosumi Accounts は登録済み OIDC client のための標準 issuer surface を公開します。

http

GET  /.well-known/openid-configuration
GET  /oauth/jwks
GET  /oauth/authorize
POST /oauth/token

Capsule が公開する OIDC client は installExperience.oidc_client.scopes で必要な scope を宣言できます。openid は必須です。Accounts が発行する access token は単一 Workspace に束縛され、token の実体は利用側の secret store に暗号化して保存します。

エラーの形式

失敗した response は structured error を返します。

json

{
  "error": {
    "code": "capability_not_available",
    "message": "requested capability is not enabled for this endpoint",
    "requestId": "req_123"
  }
}

バージョン

現在の API version は takosumi.dev/v1alpha1 です。

version	位置づけ
`v1alpha1`	破壊的変更あり。docs と conformance を同時に更新する
`v1beta1`	大枠は固定。upgrade / conversion guidance を必須とする
`v1`	後方互換を維持。field は削除しない

Takosumi API ​

エンドポイントの探索 ​

認証 ​

OpenTofu Stack API ​

Workspace ​

Workspace を作る ​

Workspace を読む ​

Project と Capsule ​

Capsule を作る ​

plan を作る ​

Run を読む ​

承認して適用する ​

取り消す ​

破棄する ​

Source ​

Source を作る ​

Source を同期する ​

SourceSnapshot を一覧する ​

Run と StateVersion ​

認証情報と Output の共有 ​

Connection を作る ​

検証する ​

失効させる ​

dashboard 用の投影 ​

OIDC と workload identity ​

エラーの形式 ​

バージョン ​

関連 ​

Takosumi API

エンドポイントの探索

認証

OpenTofu Stack API

Workspace

Workspace を作る

Workspace を読む

Project と Capsule

Capsule を作る

plan を作る

Run を読む

承認して適用する

取り消す

破棄する

Source

Source を作る

Source を同期する

SourceSnapshot を一覧する

Run と StateVersion

認証情報と Output の共有

Connection を作る

検証する

失効させる

dashboard 用の投影

OIDC と workload identity

エラーの形式

バージョン

関連