API & MCP

Towbar exposes infrastructure operations through REST and MCP. Manage repositories, apps, resources, servers, deployments, previews, secrets, integration settings, and your current identity using your current workspace permissions.

Interface	Endpoint	Authentication
REST API	`https://YOUR_API_HOST/v1/api`	API key
MCP	`https://YOUR_API_HOST/v1/mcp`	API key
OpenAPI specification	`GET /v1/api/openapi.json`	API key

Reference examples use api.example.com; replace it with the API host for your own Towbar installation. Your control plane shows its MCP endpoint in My Settings → MCP Guide.

Create a key

Open Manage → My Settings → API Keys and create an API key. Name it for its consumer, choose its permissions and expiry, then copy it. Towbar only shows the secret once.

Send a request

Set TOWBAR_API_KEY through your shell or secret manager and replace YOUR_API_HOST below.

curl 'https://YOUR_API_HOST/v1/api/apps' \
  -H "Authorization: Bearer $TOWBAR_API_KEY"

A successful list request contains "apps": [...] and "localization": {...}. An empty inventory contains "apps": [].

Connect your automation

Use the route reference in this section for REST, or follow MCP setup for an AI client.

Route design

The dashboard calls Git connections Repositories. API paths retain the identifier sources. Collections use plural nouns: /sources, /apps, /resources, /servers, and /deployments. Item routes use UUIDs. Related records live under their parent, such as /apps/{appId}/releases. Commands use POST on an /actions/ route, such as /apps/{appId}/actions/deploy. Apps and resources are defined in your Git manifest. To create or change them, update the manifest and sync its repository. The API does not invent a separate configuration model. Read the sync result to inspect validation issues and imported changes. All documented paths are relative to /v1/api. Browser-only login, logout, initial setup, provider webhooks, and signed worker endpoints are separate protocols. They are not exposed as MCP tools. API key management, profile editing, password changes, browser-session management, GitHub installation, and GitLab OAuth handoff are available only in the control plane. Provider credentials and notification routes come only from the API process environment. GET /identity identifies the current actor and team. REST provides individual routes; MCP offers a separate task-oriented tool catalogue, including combined inspections and shared app/resource actions.

Find an operation

The reference is grouped by the thing you manage, with smaller sections for each task:

Category	Sections
Repositories	Overview, Sync & manifest, Auto-deploy, Inventory, Secrets
Apps	Overview, Deployments, Runtime & logs, Previews, Secrets
Resources	Overview, Deployments, Runtime & logs, Backups & restores, Secrets
Servers	Overview, Inventory, Capacity, Checks & preparation, Credentials & trust, Scout Agent, Scout Alerts
Deployments	Overview, Progress & logs, Actions, Security scans, Performance comparisons
Previews	Lifecycle
Manage	Shared secrets, System health, Identity
Integrations	GitHub, GitLab, storage, registry, secrets, platform, notifications, and log forwarding

For common tasks, start with the automation workflows. Expand only the relevant reference section when you need a schema or an individual operation.

Requests and responses

Send JSON with Content-Type: application/json where a request body is documented. Empty-body actions do not need {}.
200 indicates a completed request or replay. 201 indicates a newly created record. 202 accepts asynchronous work. 204 has no response body.
Timestamps use ISO 8601 UTC strings. IDs are UUIDs. Unknown or inaccessible workspace records return 404.
Lists return named arrays; detailed records return named objects. Deployment history and server checks accept page and limit and include pagination metadata. Other inventories are not paginated.
Request bodies are limited to 1 MiB unless a route imposes a smaller bound. Secret and credential mutations allow 300 KiB.
Responses carry X-Request-Id; include it when reporting a failure. API/MCP responses are marked Cache-Control: no-store.

Date and time localization

JSON operation responses preserve their original timestamps and include a localization object. Personal API keys use the current preferences of their owner. Team API keys use the default date and time formats in UTC. MCP tool results include the same object under result.localization, and each deployment stream event includes it alongside deployment, logs, and steps. The timestamps map is keyed by each original ISO timestamp (or calendar date) found in the response. A client can look up a value directly and display the server-rendered label without formatting the timestamp again:

{
  "localization": {
    "dateFormat": "year-month-day",
    "timeFormat": "12-hour-seconds",
    "timeZone": "Asia/Kolkata",
    "timestamps": {
      "2026-09-16T23:30:45.000Z": {
        "date": "2026-09-17",
        "time": "5:00:45 AM",
        "dateTime": "5:00:45 AM, 2026-09-17",
        "timeZone": "Asia/Kolkata",
        "zoneLabel": "GMT+5:30",
        "epochMilliseconds": 1789601445000,
        "inputDateTime": "2026-09-17T05:00"
      }
    }
  }
}

date follows the selected calendar format. time and dateTime follow the selected clock format. timeZone is the effective IANA zone; zoneLabel is the offset or abbreviation at that instant, including daylight-saving changes. epochMilliseconds supports ordering and calculations. inputDateTime is a machine-readable local wall-clock value, not a display label. Calendar-date values retain their original date and have null for time, dateTime, and inputDateTime; changing time zone does not move a daily calendar bucket to a different day. Responses without timestamps have an empty map. A 204 response still has no body. Use the original timestamps for requests, sorting, scheduling, and relative-time calculations. Change account preferences from My Settings → Preferences; API keys cannot edit account settings.

Asynchronous actions and retries

Deployment, rollback, runtime operations, preparation, checks, and sync actions may queue background work. Acceptance is not completion. Poll the returned deployment, operation, check, or sync ID until its state becomes terminal. The workflows guide includes examples. Where shown in the route reference, supply Idempotency-Key. Use one unique value per intended action and reuse it only when retrying that same action. Replays return the existing result; a conflicting payload can return 409. Do not automatically retry a mutation with a new key after an ambiguous timeout.

Errors and limits

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Provide a valid, unexpired Towbar API key",
    "requestId": "e3dd2776-e07d-486c-9d9f-e3708be31274"
  }
}

Status	Meaning	Next step
`400`	Malformed JSON, invalid field, or invalid UUID	Correct the request using its route schema.
`401`	Missing, expired, revoked, or invalid key	Create or supply a valid key.
`403`	Read-only mutation or insufficient role	Check permissions and workspace role.
`404`	Missing or inaccessible record or route	Check the ID and your workspace.
`409`	Revision, state, or idempotency conflict	Read current state before retrying.
`413`	Request body exceeds its bound	Reduce the payload.
`422`	Semantically invalid configuration	Correct the manifest or configuration.
`429`	Shared IP rate limit exceeded	Wait for the `Retry-After` number of seconds.
`500`	Unexpected server failure	Preserve the request ID and inspect server logs.

The default is 60 requests per minute per IP, shared between REST and MCP. Unauthenticated attempts count too. MCP initialization, discovery, and tool calls each count as requests. Limits are stored in PostgreSQL and remain consistent across API processes. Responses expose X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds). A blocked request adds Retry-After in seconds. See authentication and rate limits for operator settings.

Get started

Repositories

Apps

Resources

Servers

Deployments

Previews

Workspace

Integrations

Route design

Find an operation

Requests and responses

Date and time localization

Asynchronous actions and retries

Errors and limits

​Route design

​Find an operation

​Requests and responses

​Date and time localization

​Asynchronous actions and retries

​Errors and limits

Route design

Find an operation

Requests and responses

Date and time localization

Asynchronous actions and retries

Errors and limits