The Apps API from Tower — 12 operation(s) for apps.
openapi: 3.1.0
info:
contact:
email: hello@tower.dev
name: Tower Computing GmbH
url: https://tower.dev
description: REST API to interact with Tower Services.
termsOfService: https://tower.dev/terms
title: Tower Accounts Apps API
version: v0.11.16
servers:
- url: https://api.tower.dev/v1
tags:
- name: Apps
paths:
/apps:
get:
description: Get all the apps for the current account.
operationId: list-apps
parameters:
- description: The page number to fetch.
explode: false
in: query
name: page
schema:
default: 1
description: The page number to fetch.
format: int64
type: integer
- description: The number of records to fetch on each page.
explode: false
in: query
name: page_size
schema:
default: 20
description: The number of records to fetch on each page.
format: int64
type: integer
- description: The tag query to filter apps by. Provide a serialized TagFilter as the value for the parameter.
example: tag_filter={"op":"eq","name":"foo","value":"bar"}
explode: false
in: query
name: tag_filter
schema:
description: The tag query to filter apps by. Provide a serialized TagFilter as the value for the parameter.
examples:
- tag_filter={"op":"eq","name":"foo","value":"bar"}
type: string
- description: The search query to filter apps by.
explode: false
in: query
name: query
schema:
description: The search query to filter apps by.
type: string
- description: Number of recent runs to fetch (-1 for all runs, defaults to 20)
explode: false
in: query
name: num_runs
schema:
default: 20
description: Number of recent runs to fetch (-1 for all runs, defaults to 20)
format: int64
type: integer
- description: Sort order for the results.
explode: false
in: query
name: sort
schema:
default: created_at
description: Sort order for the results.
enum:
- most_recent_run
- a_to_z
- created_at
- updated_at
type: string
- description: Filter to see apps with certain statuses.
explode: false
in: query
name: filter
schema:
description: Filter to see apps with certain statuses.
enum:
- disabled
- running
- withWarning
- healthy
- scheduled
type: string
- description: The environment to filter the apps by. If not provided, apps for all environments will be returned.
explode: false
in: query
name: environment
schema:
description: The environment to filter the apps by. If not provided, apps for all environments will be returned.
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListAppsResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps:read
- APIKeyAuth:
- apps:read
summary: List apps
x-shoulder-tap-events:
- apps.*
- runs.*
tags:
- Apps
post:
description: Create a new app in the current account.
operationId: create-app
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAppParams'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAppResponse'
description: Created
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps:create
- APIKeyAuth:
- apps:create
summary: Create app
tags:
- Apps
/apps/{name}:
delete:
description: Delete one of your apps, the associated code, and all the runs as well.
operationId: delete-app
parameters:
- description: The name of the app to delete.
in: path
name: name
required: true
schema:
description: The name of the app to delete.
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAppResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps:delete
- APIKeyAuth:
- apps:delete
summary: Delete app
tags:
- Apps
get:
description: Get all the runs for the current account.
operationId: describe-app
parameters:
- description: The name of the app to fetch.
in: path
name: name
required: true
schema:
description: The name of the app to fetch.
type: string
- description: The number of recent runs to fetch for the app.
explode: false
in: query
name: runs
schema:
description: The number of recent runs to fetch for the app.
format: int64
type: integer
- description: Filter runs scheduled after this datetime (inclusive). Provide timestamps in ISO-8601 format.
explode: false
in: query
name: start_at
schema:
description: Filter runs scheduled after this datetime (inclusive). Provide timestamps in ISO-8601 format.
format: date-time
type: string
- description: Filter runs scheduled before or at this datetime (inclusive). Provide timestamps in ISO-8601 format.
explode: false
in: query
name: end_at
schema:
description: Filter runs scheduled before or at this datetime (inclusive). Provide timestamps in ISO-8601 format.
format: date-time
type: string
- description: Timezone for the statistics (e.g., 'Europe/Berlin'). Defaults to UTC.
explode: false
in: query
name: timezone
schema:
default: UTC
description: Timezone for the statistics (e.g., 'Europe/Berlin'). Defaults to UTC.
type: string
- description: The environment to resolve the app version against. Defaults to 'default'.
explode: false
in: query
name: environment
schema:
default: default
description: The environment to resolve the app version against. Defaults to 'default'.
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeAppResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps:read
- APIKeyAuth:
- apps:read
summary: Describe app
x-shoulder-tap-events:
- apps.{name}.*
- runs.{name}.*
tags:
- Apps
put:
description: Update an app in the currently authenticated account.
operationId: update-app
parameters:
- description: The name of the App to update.
in: path
name: name
required: true
schema:
description: The name of the App to update.
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAppParams'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAppResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps:update
- APIKeyAuth:
- apps:update
summary: Update app
tags:
- Apps
/apps/{name}/deploy:
post:
description: Deploy a new version of an app. Accepts either a TAR file upload (application/tar) or a JSON body with source_uri (application/json) for deploying from a GitHub repository.
operationId: deploy-app
parameters:
- description: The name of the app to deploy.
in: path
name: name
required: true
schema:
description: The name of the app to deploy.
type: string
- description: The SHA256 hash of the content, used to verify integrity.
in: header
name: X-Tower-Checksum-SHA256
schema:
description: The SHA256 hash of the content, used to verify integrity.
type: string
- description: Optional opaque key (typically a git commit SHA or CI build ID). If a prior deploy for this app supplied the same value, the server reuses that AppVersion instead of creating a new one — letting consecutive deploys to different environments share a single version when the source hasn't changed.
in: header
name: X-Tower-Idempotency-Key
schema:
description: Optional opaque key (typically a git commit SHA or CI build ID). If a prior deploy for this app supplied the same value, the server reuses that AppVersion instead of creating a new one — letting consecutive deploys to different environments share a single version when the source hasn't changed.
type: string
- description: Size of the uploaded bundle in bytes.
in: header
name: Content-Length
schema:
description: Size of the uploaded bundle in bytes.
format: int64
type: integer
- description: The environment to deploy to.
explode: false
in: query
name: environment
schema:
description: The environment to deploy to.
type: string
- description: Whether to deploy to all environments for this app. If true, the 'environment' query parameter is ignored.
explode: false
in: query
name: all_environments
schema:
default: false
description: Whether to deploy to all environments for this app. If true, the 'environment' query parameter is ignored.
type: boolean
requestBody:
content:
application/json:
schema:
examples:
- source_uri: https://github.com/tower/tower-examples/tree/main/01-hello-world
properties:
source_uri:
description: GitHub repository URL for deploying from source
format: uri
type: string
required:
- source_uri
type: object
application/octet-stream:
schema:
contentMediaType: application/octet-stream
description: A .tar or .tar.gz file containing the code to deploy and MANIFEST
examples:
- <binary tar file stream>
format: binary
type: string
description: Deploy app using either a tar file upload or GitHub source URL
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/DeployAppResponse'
description: Created
'400':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Bad Request
'422':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Unprocessable Entity
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal Server Error
security:
- AccessTokenAuth:
- apps:deploy
- APIKeyAuth:
- apps:deploy
summary: Deploy app
tags:
- Apps
/apps/{name}/environments:
get:
description: Generates a list of all the known environments for a given app in the current account.
operationId: list-app-environments
parameters:
- description: The name of the app to get the version for.
in: path
name: name
required: true
schema:
description: The name of the app to get the version for.
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListAppEnvironmentsResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps:read
- APIKeyAuth:
- apps:read
summary: List app environments
x-shoulder-tap-events:
- apps.{name}.*
tags:
- Apps
/apps/{name}/environments/{environment}:
put:
description: Update the configuration of an app in a specific environment, such as which version is deployed.
operationId: update-app-environment
parameters:
- description: The name of the app.
in: path
name: name
required: true
schema:
description: The name of the app.
type: string
- description: The name of the environment.
in: path
name: environment
required: true
schema:
description: The name of the environment.
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAppEnvironmentParams'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAppEnvironmentResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps:deploy
- APIKeyAuth:
- apps:deploy
summary: Update app environment
tags:
- Apps
/apps/{name}/runs:
get:
description: Generates a list of all the runs for a given app. The list is paginated based on the query string parameters passed in.
operationId: list-runs
parameters:
- description: The page number to fetch.
explode: false
in: query
name: page
schema:
default: 1
description: The page number to fetch.
format: int64
type: integer
- description: The number of records to fetch on each page.
explode: false
in: query
name: page_size
schema:
default: 20
description: The number of records to fetch on each page.
format: int64
type: integer
- description: The name of the app to fetch runs for.
in: path
name: name
required: true
schema:
description: The name of the app to fetch runs for.
type: string
- description: Filter runs by status(es). Define multiple with a comma-separated list. Supplying none will return all statuses.
explode: false
in: query
name: status
schema:
default:
- pending
- starting
- running
- crashed
- errored
- exited
- cancelled
- retrying
description: Filter runs by status(es). Define multiple with a comma-separated list. Supplying none will return all statuses.
items:
enum:
- pending
- starting
- running
- crashed
- errored
- exited
- cancelled
- retrying
type: string
type: array
- description: Filter runs scheduled after or at this datetime (inclusive)
explode: false
in: query
name: start_at
schema:
description: Filter runs scheduled after or at this datetime (inclusive)
format: date-time
type: string
- description: Filter runs scheduled before or at this datetime (inclusive)
explode: false
in: query
name: end_at
schema:
description: Filter runs scheduled before or at this datetime (inclusive)
format: date-time
type: string
- description: Filter runs by environment. If not provided, all environments will be included.
explode: false
in: query
name: environment
schema:
description: Filter runs by environment. If not provided, all environments will be included.
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListRunsResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- runs:read
- APIKeyAuth:
- runs:read
summary: List runs
x-shoulder-tap-events:
- runs.*
tags:
- Apps
post:
description: Runs an app with the supplied parameters.
operationId: run-app
parameters:
- description: The name of the app to fetch runs for.
in: path
name: name
required: true
schema:
description: The name of the app to fetch runs for.
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RunAppParams'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/RunAppResponse'
type: object
description: Created
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
type: object
description: Unauthorized
security:
- AccessTokenAuth:
- apps:run
- APIKeyAuth:
- apps:run
summary: Run app
tags:
- Apps
/apps/{name}/runs/{seq}:
get:
description: Describe a run of an app.
operationId: describe-run
parameters:
- description: The name of the app to fetch runs for.
in: path
name: name
required: true
schema:
description: The name of the app to fetch runs for.
type: string
- description: The number of the run to fetch.
in: path
name: seq
required: true
schema:
description: The number of the run to fetch.
format: int64
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeRunResponse'
description: OK
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
type: object
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
type: object
description: Not found
security:
- AccessTokenAuth:
- runs:read
- APIKeyAuth:
- runs:read
summary: Describe run
x-shoulder-tap-events:
- runs.{name}.{seq}.*
tags:
- Apps
post:
description: Cancel a run
operationId: cancel-run
parameters:
- description: The name of the app to fetch runs for.
in: path
name: name
required: true
schema:
description: The name of the app to fetch runs for.
type: string
- description: The number of the run to fetch.
in: path
name: seq
required: true
schema:
description: The number of the run to fetch.
format: int64
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CancelRunResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- runs:cancel
- APIKeyAuth:
- runs:cancel
summary: Cancel run
tags:
- Apps
/apps/{name}/runs/{seq}/graph:
get:
description: Describe the graph that a run belongs to.
operationId: describe-run-graph
parameters:
- description: The name of the app.
in: path
name: name
required: true
schema:
description: The name of the app.
type: string
- description: The number of the run to fetch.
in: path
name: seq
required: true
schema:
description: The number of the run to fetch.
format: int64
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeRunGraphResponse'
description: OK
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
type: object
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
type: object
description: Not found
security:
- AccessTokenAuth:
- runs:read
- APIKeyAuth:
- runs:read
summary: Describe run graph
x-shoulder-tap-events:
- run-graph.{name}.{seq}.updated
tags:
- Apps
/apps/{name}/runs/{seq}/logs:
get:
description: Retrieves the logs associated with a particular run of an app.
operationId: describe-run-logs
parameters:
- description: The name of the app to get logs for.
in: path
name: name
required: true
schema:
description: The name of the app to get logs for.
type: string
- description: The sequence number of the run to get logs for.
in: path
name: seq
required: true
schema:
description: The sequence number of the run to get logs for.
format: int64
type: integer
- description: Fetch logs from this timestamp onwards (inclusive).
explode: false
in: query
name: start_at
schema:
description: Fetch logs from this timestamp onwards (inclusive).
format: date-time
type: string
- description: Return only the first N log lines. Cannot be combined with tail.
explode: false
in: query
name: head
schema:
description: Return only the first N log lines. Cannot be combined with tail.
format: int64
minimum: 1
type: integer
- description: Return only the last N log lines. Cannot be combined with head.
explode: false
in: query
name: tail
schema:
description: Return only the last N log lines. Cannot be combined with head.
format: int64
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeRunLogsResponse'
description: OK
headers:
ContentType:
schema:
type: string
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- runs:read
- APIKeyAuth:
- runs:read
summary: Describe run logs
tags:
- Apps
/apps/{name}/runs/{seq}/logs/stream:
get:
description: Streams the logs associated with a particular run of an app in real-time.
operationId: stream-run-logs
parameters:
- description: The name of the app to get logs for.
in: path
name: name
required: true
schema:
description: The name of the app to get logs for.
type: string
- description: The sequence number of the run to get logs for.
in: path
name: seq
required: true
schema:
description: The sequence number of the run to get logs for.
format: int64
type: integer
responses:
'200':
content:
text/event-stream:
schema:
description: Each oneOf object in the array represents one possible Server Sent Events (SSE) message, serialized as UTF-8 text according to the SSE specification.
items:
oneOf:
- properties:
data:
$ref: '#/components/schemas/RunLogLine'
event:
const: log
description: The event name.
type: string
id:
description: The event ID.
type: integer
retry:
description: The retry time in milliseconds.
type: integer
required:
- data
- event
title: Event log
type: object
- properties:
data:
$ref: '#/components/schemas/SSEWarning'
event:
const: warning
description: The event name.
type: string
id:
description: The event ID.
type: integer
retry:
description: The retry time in milliseconds.
type: integer
required:
- data
- event
title: Event warning
type: object
title: Server Sent Events
type: array
description: SSE log stream
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- runs:read
- APIKeyAuth:
- runs:read
summary: Stream run logs
tags:
- Apps
/apps/{name}/versions:
get:
description: List all versions of an app in the current account, sorted with the most recent first.
operationId: list-app-versions
parameters:
- description: The name of the app to list versions for.
in: path
name: name
required: true
schema:
description: The name of the app to list versions for.
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListAppVersionsResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps:read
- APIKeyAuth:
- apps:read
summary: List app versions
x-shoulder-tap-events:
- apps.{name}.*
tags:
- Apps
/apps/{name}/versions/{num}:
get:
description: Describe an app version for an app in the current account.
operationId: describe-app-version
parameters:
- description: The name of the app to get the version for.
in: path
name: name
required: true
schema:
description: The name of the app to get the version for.
type: string
- description: The version string to get the version for.
in: path
name: num
required: true
schema:
description: The version string to get the version for.
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeAppVersionResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps:read
- APIKeyAuth:
- apps:read
summary: Describe app version
tags:
- Apps
components:
schemas:
SSEWarning:
additionalProperties: false
properties:
content:
description: Contents of the warning.
type: string
end_of_stream:
description: When true, the server has delivered every log line and is closing the stream; clients should stop and not reconnect.
type: boolean
reported_at:
description: Timestamp of the event.
format: date-time
type: string
required:
- reported_at
- content
type: object
RunAppResponse:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://api.tower.dev/v1/schemas/RunAppResponse.json
format: uri
readOnly: true
type: string
run:
$ref: '#/components/schemas/Run'
required:
- run
type: object
ListRunsResponse:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://api.tower.dev/v1/schemas/ListRunsResponse.json
format: uri
readOnly: true
type: string
pages:
$ref: '#/components/schemas/Pagination'
runs:
items:
$ref: '#/components/schemas/Run'
type: array
required:
- pages
- runs
type: object
ListAppsResponse:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://api.tower.dev/v1/schemas/ListAppsResponse.json
format: uri
readOnly: true
type: string
apps:
items:
$ref: '#/components/schemas/AppSummary'
type: array
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tower/refs/heads/main/openapi/tower-apps-api-openapi.yml