> ## Documentation Index
> Fetch the complete documentation index at: https://www.towbar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Automation workflows

> Deploy and roll back apps, reconcile repositories, manage secrets, and follow asynchronous Towbar operations.

All examples use your own API host and a Bearer API key. Use an Edit key for permitted mutations. Deployment and infrastructure operations require administrative grants. Personal keys remain bounded by the owner’s current team role; team keys retain their explicit service grants.

## Deploy an app

List `/apps` to find an app UUID, then request a deployment:

```bash theme={"system"}
curl -X POST "https://YOUR_API_HOST/v1/api/apps/$APP_ID/actions/deploy" \
  -H "Authorization: Bearer $TOWBAR_API_KEY" \
  -H "Idempotency-Key: $ACTION_ID"
```

Set `ACTION_ID` to a unique value for this intended deployment. The response includes a deployment and whether the request was replayed. Poll `GET /deployments/{deploymentId}` and `GET /deployments/{deploymentId}/steps`. Fetch incremental logs with `GET /deployments/{deploymentId}/logs?after=42`; use the last returned sequence in the next call.

Terminal deployment states are `succeeded`, `succeeded_with_warnings`, `failed`, `cancelled`, and `skipped`. Do not treat `202`, a queued state, or an HTTP success as a successful deployment.

To stream deployment updates:

```bash theme={"system"}
curl -N "https://YOUR_API_HOST/v1/api/deployments/$DEPLOYMENT_ID/events" \
  -H "Authorization: Bearer $TOWBAR_API_KEY" \
  -H 'Accept: text/event-stream'
```

Each `deployment` event contains the deployment, logs, and steps. Streams end after a terminal state or a bounded polling period. Reconnect with `Last-Event-ID` from the last event, or `after` containing the last log sequence. Use `?snapshot=true` for one finite snapshot; MCP always uses this mode.

## Roll back or cancel

Read `/apps/{appId}/releases`, then `POST /apps/{appId}/actions/rollback` with an `Idempotency-Key` and body `{"releaseId":"RELEASE_UUID"}`. An empty object selects the previous release when available. Resource rollback follows the corresponding `/resources` route.

`POST /deployments/{deploymentId}/actions/cancel` requests cancellation. Poll the deployment to see the final result. A retry uses `/deployments/{deploymentId}/actions/retry` and a fresh idempotency key for the new attempt.

## Reconcile a repository

Optionally discover declared environments with `POST /sources/discover`, using repository details from `/github/repositories` and the repository default branch as `discoveryBranch`. Discovery is only a suggestion step; connection does not require it. Connect the repository with `POST /sources/connect`, mapping each selected environment to its branch. Initial sync imports configuration without deploying. For later reconciliation, call `POST /sources/{sourceId}/environments/{environmentId}/syncs`, or `/sources/{sourceId}/environments/syncs` for all connected environments. These explicit syncs import configuration without deploying. Mapped-branch push events can queue opted-in deployments. Inspect each queue outcome and read `/sources/{sourceId}/syncs/{syncId}` for completion and validation errors.

Automatic deployment controls can be read or changed at `/sources/{sourceId}/auto-deploy-control`, `/apps/{appId}/auto-deploy-control`, and `/resources/{resourceId}/auto-deploy-control`. Repository-level and workload-level controls combine as they do in the UI.

## Update secrets safely

Read `/settings/secrets` for workspace bindings and their revisions. Repository, app, and resource secret routes use the same model. Reads expose names and revision metadata, never plaintext values.

```bash theme={"system"}
curl -X PATCH 'https://YOUR_API_HOST/v1/api/settings/secrets/production/deployment' \
  -H "Authorization: Bearer $TOWBAR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @secret-change.json
```

The local `secret-change.json` contains:

```json theme={"system"}
{
  "expectedRevision": null,
  "set": { "EXAMPLE_VARIABLE": "example-value" },
  "delete": []
}
```

Use `null` only when creating a previously empty secret slot. For an existing slot, send its current revision UUID. A stale revision returns `409`; read the latest metadata and reconcile changes. A request changes 1–200 keys, and cannot set and delete the same key. Keep real secret files outside source control.

Workspace values use the `production` storage path and are shared across environments when explicitly referenced. For repository and workload values, use the connected environment name, such as `production` or `staging`. Preview scopes use `preview:<environment>`, such as `preview:staging`. Stages are `build`, `deployment`, `pre_deploy`, and `post_deploy`. Server Cloudflare tokens use `/servers/{serverId}/credentials`. Select an existing stored SSH key with `/servers/{serverId}/credentials/actions/verify-private-key`, passing `privateKeyId` and `expectedRevision`. Creating or revealing private keys requires the Admin dashboard.

## Servers, backups, and previews

Create a server with `POST /servers`, select its stored SSH key for verification, compare a discovered host-key fingerprint independently, and trust the matching key. Use `/servers/{serverId}/actions/prepare` and follow `/preparations` until ready. `/actions/check` refreshes runtime health and capacity; inspect `/checks` for the outcome.

For resource backups, use `/resources/{resourceId}/actions/backup`. Read `/operations` and `/backup-assurance`. Restore and cleanup operations have explicit request schemas and state constraints in the reference. Restores can overwrite database contents; inspect the backup, target, and required confirmation fields before invoking them.

Preview deployment and cleanup use `/previews/{previewEnvironmentId}/actions/deploy` and `/actions/delete`. Preview inventories are available under the parent app or source. Cleanup is asynchronous and must be checked for failures.