Apps

An app is one deployable service inside a project. Its source is either a GitHub repository or a container image.

Create an app

POST /v1/apps.createApp

Creates an app in a project. Pass git to build from a GitHub repository or oci to run a container image. With git and no repository, you can connect one later. The app gets the environments production and preview.

Permissions: the key needs one of project.*.create_app, project.<project_id>.create_app.

Request

Field	Type	Description
`project`	string, required	The project, by ID or slug. 3 to 255 characters.
`name`	string, required	The app's name, shown in the dashboard. 1 to 256 characters.
`slug`	string, required	The app's slug, unique in the project. It's part of the app's generated URLs. 3 to 255 characters.
`git`	object	Use a GitHub repository as the source. Send an empty object to connect the repository later.
`git.repository`	string	The repository, as `owner/name`. The Teral GitHub App must have access to it. 1 to 255 characters.
`git.defaultBranch`	string	The branch that deploys to production. Defaults to the repository's default branch on GitHub. 1 to 256 characters.
`oci`	object	Use a container image as the source.
`oci.image`	string, required	The image new deployments use, with a tag or digest, such as `ghcr.io/acme/api:v1.4.0`. It must be public. 1 to 256 characters.

curl -X POST https://api.teral.dev/v1/apps.createApp \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "name": "Web",
    "slug": "web",
    "git": {
      "repository": "acme/shop"
    }
  }'

Response

On success the status is 200 OK. The fields in data:

Field	Type	Description
`appId`	string	The new app's ID. 8 to 255 characters.

Error statuses: 400, 401, 403, 404, 409, 429, 500. See Errors for the codes behind them.

List apps

POST /v1/apps.listApps

Returns a project's apps, a page at a time.

Permissions: the key needs app.*.read_app.

Request

Field	Type	Description
`project`	string, required	The project, by ID or slug. 3 to 255 characters.
`limit`	integer	How many results to return in one page. Default `100`. 1 to 100.
`cursor`	string	The `pagination.cursor` of the previous response, to get the next page.
`search`	string	Only return apps whose ID, name or slug contains this text. Not case sensitive. At most 256 characters.

curl -X POST https://api.teral.dev/v1/apps.listApps \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop"
  }'

Response

On success the status is 200 OK. The fields in data:

Field	Type	Description
`id`	string	The app's ID.
`name`	string	The app's name.
`slug`	string	The app's slug.
`sourceType`	string	Where deployments come from: `git` for a repository, `oci` for an image. Missing for a few old apps. One of `git`, `oci`.
`git`	any	The connected repository. Missing when no repository is connected.
`git.repository`	string	The repository, as `owner/name`. 1 to 255 characters.
`git.defaultBranch`	string	The branch that deploys to production. 1 to 256 characters.
`oci`	any	The image source. Only present for image apps.
`oci.image`	string	The image new deployments use. 1 to 256 characters.
`currentDeploymentId`	string	The deployment serving production. Missing before the first production deployment.
`isRolledBack`	boolean	Whether production is on a rolled-back deployment. While it is, new pushes don't take over production until you promote a deployment.
`deleteProtection`	boolean	Whether delete protection is on. A protected app can't be deleted.
`createdAt`	integer	When it was created, in Unix milliseconds. 0 to 9223372036854776000.
`updatedAt`	integer	When it last changed, in Unix milliseconds. Missing if it never changed. 0 to 9223372036854776000.

When pagination.hasMore is true, pass pagination.cursor as cursor to get the next page.

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

Get an app

POST /v1/apps.getApp

Returns one app with its source and live deployment.

Permissions: the key needs one of app.*.read_app, app.<app_id>.read_app.

Request

Field	Type	Description
`project`	string, required	The project, by ID or slug. 3 to 255 characters.
`app`	string, required	The app, by ID (`app_…`) or slug. 3 to 255 characters.

curl -X POST https://api.teral.dev/v1/apps.getApp \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web"
  }'

Response

On success the status is 200 OK. The fields in data:

Field	Type	Description
`id`	string	The app's ID.
`name`	string	The app's name.
`slug`	string	The app's slug.
`sourceType`	string	Where deployments come from: `git` for a repository, `oci` for an image. Missing for a few old apps. One of `git`, `oci`.
`git`	any	The connected repository. Missing when no repository is connected.
`git.repository`	string	The repository, as `owner/name`. 1 to 255 characters.
`git.defaultBranch`	string	The branch that deploys to production. 1 to 256 characters.
`oci`	any	The image source. Only present for image apps.
`oci.image`	string	The image new deployments use. 1 to 256 characters.
`currentDeploymentId`	string	The deployment serving production. Missing before the first production deployment.
`isRolledBack`	boolean	Whether production is on a rolled-back deployment. While it is, new pushes don't take over production until you promote a deployment.
`deleteProtection`	boolean	Whether delete protection is on. A protected app can't be deleted.
`createdAt`	integer	When it was created, in Unix milliseconds. 0 to 9223372036854776000.
`updatedAt`	integer	When it last changed, in Unix milliseconds. Missing if it never changed. 0 to 9223372036854776000.

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

Update an app

POST /v1/apps.updateApp

Changes an app's name, slug, repository, default image or delete protection. Fields you leave out stay as they are. Changing the source type between repository and image isn't possible.

Permissions: the key needs one of app.*.update_app, app.<app_id>.update_app.

Request

Field	Type	Description
`project`	string, required	The project, by ID or slug. 3 to 255 characters.
`app`	string, required	The app, by ID or slug. 3 to 255 characters.
`name`	string	A new name. 1 to 256 characters.
`slug`	string	A new slug. 3 to 255 characters.
`git`	object or null	Changes the connected repository. Send `null` to disconnect it. Send only the field you want to change.
`git.repository`	string	Connects this repository, as `owner/name`, replacing the current one. 1 to 255 characters.
`git.defaultBranch`	string	The branch that deploys to production from now on. 1 to 256 characters.
`oci`	any	Changes the image of an image app. This doesn't deploy anything.
`oci.image`	string, required	The image new deployments use, with a tag or digest. 1 to 256 characters.
`deleteProtection`	boolean	Turns delete protection on or off.

curl -X POST https://api.teral.dev/v1/apps.updateApp \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web",
    "git": {
      "defaultBranch": "release"
    }
  }'

Response

On success the status is 200 OK. The fields in data:

Field	Type	Description
`id`	string	The app's ID.
`name`	string	The app's name.
`slug`	string	The app's slug.
`sourceType`	string	Where deployments come from: `git` for a repository, `oci` for an image. Missing for a few old apps. One of `git`, `oci`.
`git`	any	The connected repository. Missing when no repository is connected.
`git.repository`	string	The repository, as `owner/name`. 1 to 255 characters.
`git.defaultBranch`	string	The branch that deploys to production. 1 to 256 characters.
`oci`	any	The image source. Only present for image apps.
`oci.image`	string	The image new deployments use. 1 to 256 characters.
`currentDeploymentId`	string	The deployment serving production. Missing before the first production deployment.
`isRolledBack`	boolean	Whether production is on a rolled-back deployment. While it is, new pushes don't take over production until you promote a deployment.
`deleteProtection`	boolean	Whether delete protection is on. A protected app can't be deleted.
`createdAt`	integer	When it was created, in Unix milliseconds. 0 to 9223372036854776000.
`updatedAt`	integer	When it last changed, in Unix milliseconds. Missing if it never changed. 0 to 9223372036854776000.

Error statuses: 400, 401, 403, 404, 409, 429, 500. See Errors for the codes behind them.

Delete an app

POST /v1/apps.deleteApp

Deletes an app with its deployments, domains and variables. The response comes right away and the cleanup runs in the background. Fails with 412 while delete protection is on.

Permissions: the key needs one of app.*.delete_app, app.<app_id>.delete_app.

Request

Field	Type	Description
`project`	string, required	The project, by ID or slug. 3 to 255 characters.
`app`	string, required	The app, by ID or slug. 3 to 255 characters.

curl -X POST https://api.teral.dev/v1/apps.deleteApp \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web"
  }'

Response

On success the status is 202 Accepted.

Error statuses: 400, 401, 403, 404, 412, 429, 500. See Errors for the codes behind them.

Create an appCopy Anchor Link

RequestCopy Anchor Link

ResponseCopy Anchor Link

List appsCopy Anchor Link

RequestCopy Anchor Link

ResponseCopy Anchor Link

Get an appCopy Anchor Link

RequestCopy Anchor Link

ResponseCopy Anchor Link

Update an appCopy Anchor Link

RequestCopy Anchor Link

ResponseCopy Anchor Link

Delete an appCopy Anchor Link

RequestCopy Anchor Link

ResponseCopy Anchor Link

On this page

Create an app

Request

Response

List apps

Request

Response

Get an app

Request

Response

Update an app

Request

Response

Delete an app

Request

Response