Takosumi API

The Takosumi API exposes the control plane that runs OpenTofu / Terraform modules from Git. Terms like Workspace, Capsule, and Run are in the glossary.

Discovering endpoints

Every endpoint exposes the following discovery surfaces.

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

CLI, dashboard, and other clients refer to capabilities, not edition names.

{
  "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 names are snake_case. product is always takosumi; clients check it first. endpoints.api is <origin>/api, not the origin itself.

Authentication

Clients use a session cookie or a bearer token, depending on the endpoint.

Authorization: Bearer <token>

Every endpoint publishes the auth methods its operator enabled as capabilities. A Takosumi Cloud API key is a personal access token. When the protocol itself defines a signature (such as an S3-compatible endpoint), use that signature.

OpenTofu Stack API

The Stack API runs OpenTofu / Terraform modules from Git. Existing providers are used as-is, and every run goes plan → apply. All Stack API endpoints live under /api/v1.

The Cloudflare-specific import/deploy compatibility profile is retired.

Workspace

Method	Path	Description
GET	/api/v1/workspaces	List the workspaces you belong to
POST	/api/v1/workspaces	Create a workspace
GET	/api/v1/workspaces/{workspaceId}	Read a workspace
PATCH	/api/v1/workspaces/{workspaceId}	Update a workspace
GET	/api/v1/workspaces/{workspaceId}/members	List members
POST	/api/v1/workspaces/{workspaceId}/members	Add a member
PATCH	/api/v1/workspaces/{workspaceId}/members/{subject}	Change a member's role
DELETE	/api/v1/workspaces/{workspaceId}/members/{subject}	Remove a member
GET	/api/v1/workspaces/{workspaceId}/graph	Read the Capsule dependency graph
GET	/api/v1/workspaces/{workspaceId}/activity	List activity
GET	/api/v1/workspaces/{workspaceId}/usage	List usage
GET	/api/v1/workspaces/{workspaceId}/billing	Read billing state
GET	/api/v1/workspaces/{workspaceId}/backups	List control-plane exports
POST	/api/v1/workspaces/{workspaceId}/backups	Export control-plane data
POST	/api/v1/workspaces/{workspaceId}/plan-update	Create a workspace-wide update Run
POST	/api/v1/workspaces/{workspaceId}/drift-check	Create a workspace-wide drift-check Run

Create a Workspace

POST /api/v1/workspaces

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"
  }'

Field	Type	Description
name	string	display name
handle	string	unique identifier

On success it returns 201 with the Workspace (including workspaceId).

Read a Workspace

GET /api/v1/workspaces/{workspaceId}

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

Project and Capsule

Method	Path	Description
GET	/api/v1/workspaces/{workspaceId}/projects	List projects
POST	/api/v1/workspaces/{workspaceId}/projects	Create a project
GET	/api/v1/projects/{projectId}	Read a project
GET	/api/v1/workspaces/{workspaceId}/capsules	List capsules
POST	/api/v1/workspaces/{workspaceId}/capsules	Create a capsule
GET	/api/v1/capsules/{capsuleId}	Read a capsule
PATCH	/api/v1/capsules/{capsuleId}	Update a capsule
DELETE	/api/v1/capsules/{capsuleId}	Create a destroy plan
GET	/api/v1/capsules/{capsuleId}/outputs	Read public outputs
GET	/api/v1/capsules/{capsuleId}/usage-summary	Read the usage summary
GET	/api/v1/capsules/{capsuleId}/state-versions	List state versions
GET	/api/v1/capsules/{capsuleId}/dependencies	List dependencies
POST	/api/v1/capsules/{capsuleId}/dependencies	Create a dependency
DELETE	/api/v1/dependencies/{dependencyId}	Delete a dependency
GET	/api/v1/capsules/{capsuleId}/provider-bindings	Read the ProviderBinding selection
PUT	/api/v1/capsules/{capsuleId}/provider-bindings	Replace the ProviderBinding selection
GET	/api/v1/workspaces/{workspaceId}/current-state-versions	Read all current state versions
GET	/api/v1/capsule-configs	List Capsule creation settings
GET	/api/v1/capsule-configs/{capsuleConfigId}	Read a Capsule creation setting
PATCH	/api/v1/capsule-configs/{capsuleConfigId}	Update a Capsule creation setting

A Capsule starts with a plan. Create it, then run plan → apply.

Method	Path	Description
POST	/api/v1/capsules/{capsuleId}/plan	Create a plan Run
POST	/api/v1/capsules/{capsuleId}/destroy-plan	Create a destroy plan Run
POST	/api/v1/capsules/{capsuleId}/drift-check	Create a drift-check Run
POST	/api/v1/capsules/{capsuleId}/backups	Create a Capsule backup

Create a Capsule

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

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"
  }'

Field	Type	Description
name	string	Capsule name, a DNS-style slug ([a-z0-9-]+)
environment	string	environment name (e.g. production)
sourceId	string	the registered Source
installConfigId	string	the Capsule creation settings (variables, bindings)
projectId	string?	a non-default Project
autoUpdate	boolean?	create a plan per new snapshot. Defaults to false

Create a plan

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

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

A Run always starts as a plan. Use the returned Run's id next.

Read a Run

GET /api/v1/runs/{runId}

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

Approve and apply

Approve first when the configuration requires approval.

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

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

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

Cancel

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

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

The cancellation is recorded too.

Destroy

DELETE /api/v1/capsules/{capsuleId}

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

Delete creates a destroy plan. Review it, then apply.

Source

Method	Path	Description
GET	/api/v1/sources	List sources
POST	/api/v1/sources	Create a source
GET	/api/v1/sources/{sourceId}	Read a source
PATCH	/api/v1/sources/{sourceId}	Update source metadata
POST	/api/v1/sources/{sourceId}/sync	Create a sync Run
GET	/api/v1/sources/{sourceId}/snapshots	List source snapshots
POST	/api/v1/sources/{sourceId}/compatibility-check	Create a compatibility report
GET	/api/v1/compatibility-reports/{reportId}	Read a compatibility report

Create a Source

POST /api/v1/sources

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"
  }'

Field	Type	Description
workspaceId	string	the Workspace it belongs to
name	string	name
url	string	the Git repository URL
defaultRef	string?	branch / tag / commit to track. Defaults to HEAD
defaultPath	string?	the module directory. Defaults to .
authConnectionId	string?	a Connection for private repositories
autoSync	boolean?	periodic ref checks. Defaults to false

On success it returns 201 with the Source. The hookSecret in the response is only visible this once — save it now if you set a webhook.

Sync a Source

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

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 is observe (default) or manual_plan. Wait until the sync Run is succeeded and sourceSnapshotId appears under /api/v1/sources/{sourceId}/snapshots before planning.

List SourceSnapshots

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

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

Run and StateVersion

Method	Path	Description
GET	/api/v1/workspaces/{workspaceId}/runs	List runs
GET	/api/v1/runs/{runId}	Read a run
POST	/api/v1/runs/{runId}/approve	Approve a run
POST	/api/v1/runs/{runId}/apply	Apply a reviewed run
POST	/api/v1/runs/{runId}/cancel	Cancel a run
GET	/api/v1/runs/{runId}/logs	Read run logs
GET	/api/v1/runs/{runId}/events	Read run events
GET	/api/v1/runs/{runId}/cost	Read the cost estimate
GET	/api/v1/run-groups/{runGroupId}	Read a batch of runs
POST	/api/v1/run-groups/{runGroupId}/approve	Approve a batch of runs
GET	/api/v1/state-versions/{stateVersionId}	Read a state version
POST	/api/v1/state-versions/{stateVersionId}/rollback-plan	Plan a rollback to a past state

A Run records:

• the source snapshot (which commit ran)
• the OpenTofu version, provider lock digest, and ProviderBinding
• injected env metadata (never the values)
• plan/apply results, state version, outputs, logs, actor, and audit evidence

Connections and output sharing

Method	Path	Description
GET	/api/v1/connections	List connections
POST	/api/v1/connections	Create a write-only connection
POST	/api/v1/connections/{connectionId}/test	Validate a connection
POST	/api/v1/connections/{connectionId}/revoke	Revoke a connection
POST	/api/v1/connections/oauth/{helperId}/start	Start an OAuth helper
GET	/api/v1/connections/oauth/{helperId}/callback	Complete an OAuth helper
GET	/api/v1/provider-connections	List the ProviderConnections a Workspace sees
GET	/api/v1/credential-recipes	List credential recipes
GET	/api/v1/output-shares	List output shares
POST	/api/v1/output-shares	Create an output share
POST	/api/v1/output-shares/{shareId}/approve	Approve an output share
POST	/api/v1/output-shares/{shareId}/revoke	Revoke an output share

Create a Connection

POST /api/v1/connections

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>" }
  }'

Field	Type	Description
provider	string	the fully qualified provider address
recipe	string	the Credential Recipe id
authMode	string	env (inject as environment variables), and others
secretPartition	string	the secret storage partition
values / files	object	the secrets. Not readable after creation

The CLI is convenient too.

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

Test

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

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

Revoke

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

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

Revocation is not deletion. Later Runs cannot use it; past records remain.

Dashboard projections

Method	Path	Description
GET	/api/v1/dashboard/bootstrap	Read everything the first screen needs
GET	/api/v1/dashboard/overview	Read the Workspace overview

OIDC and workload identity

Takosumi Accounts exposes the standard issuer surface for registered OIDC clients.

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

A Capsule's OIDC client can declare the scopes it needs with installExperience.oidc_client.scopes; openid is required. Access tokens issued by Accounts are bound to a single Workspace, and the token is stored encrypted in the consumer's secret store.

Error format

Failed responses return a structured error.

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

Versioning

The current API version is takosumi.dev/v1alpha1.

version	Meaning
v1alpha1	Breaking changes allowed; docs and conformance update together
v1beta1	Mostly fixed; upgrade/conversion guidance required
v1	Backward compatible; fields are never removed