Deployments

A deployment is one build of a project's source, rolled out to one environment. An environment keeps its deployments, and serves the last one that succeeded (liveDeploymentId).

A deployment takes minutes, so it is created, then read until it is done: POST /v4/projects/{projectId}/deployments returns it pending, and GET …/deployments/{deploymentId} shows it running, then succeeded or failed. There are no actions: redeploying and rolling back are deployments too, whose source is an earlier deployment.

Deployments are listed, created and read in their project (/v4/projects/{projectId}/deployments/{deploymentId}), next to its environments. The environment is a property, and a filter on the list (…/deployments?environmentId=…).

An AI Gateway deploys itself when one of its provider assignments is added, changed or deleted: Zuplo creates a deployment (source.type zuplo) of the production environment. Nothing links the change to its deployment: to wait for it, list the environment's deployments (newest first) and read the newest zuplo deployment created after the change until it has succeeded or failed. succeeded means the rollout finished, not that every edge serves it yet: an update never takes the gateway offline, but an edge may serve the previous version for a while. Only a request to the gateway shows what it serves. Other changes to an AI Gateway (pools, apps, policies, budgets, keys) need no deployment, are not tracked, and apply within about a minute.

List deployments

GET

https://dev-api-v4-main-a471234.zuplo.app

/v4/projects/{projectId}/deployments

Lists the deployments to the project's environments, newest first. Filter by environmentId for one environment's history, and by status to find the deployments that are still running. An environment keeps its deployments until it is deleted.

List deployments › path Parameters

projectId

string · maxLength: 64 · required

The project ID (prj_…). Its members, environments and deployments are addressed under it.

List deployments › query Parameters

environmentId

string · maxLength: 64

Only return the deployments to this environment.

status

DeploymentStatus · enum

Only return deployments with this status.

Where a deployment is. pending: it waits for its source to be uploaded, or to start. running: it is building and rolling out. succeeded: its environment served it once it was done; the environment's liveDeploymentId says whether it still does. For an AI Gateway, succeeded means the rollout finished, not that every edge serves it yet: an edge may serve the previous version for a while. failed: it did not build or roll out, and its environment kept serving what it served before. succeeded and failed are final. New values may be added.

Enum values:

pending

running

succeeded

failed

limit

integer · min: 1 · max: 100

The maximum number of items to return.

Default: 10

offset

integer · min: 0

The number of items to skip before the first item returned.

Default: 0

List deployments › Responses

A page of deployments.

DeploymentList

Deployment[] · required

The deployments on this page.

limit

integer · required

The page size that was applied.

offset

integer · required

The number of items skipped before this page.

total

integer · required

The number of items in the whole collection.

hasMore

boolean · required

Whether there are more items after this page.

next

string | null · required

The relative URL of the next page, or null on the last page.

GET/v4/projects/{projectId}/deployments

curl https://dev-api-v4-main-a471234.zuplo.app/v4/projects/:projectId/deployments \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "a3c9e5d1-6b2f-4a8e-b7d4-1f0e9c8b2a65",
      "projectId": "prj_Hn4QzW7cVb2LpX9sTe5RgK1m",
      "environmentId": "4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90",
      "status": "pending",
      "source": {
        "type": "git",
        "deploymentId": "7e1d4b9a-3c6f-4d2e-8a5b-0f9c2e7d1b34",
        "rebuild": true,
        "commit": {
          "sha": "3f9c2a7e1b4d8f6a0c5e9b2d7a1f4c8e6b0d3a5f",
          "message": "Add rate limits to the orders API",
          "authorName": "Jane Doe",
          "committedOn": "2024-08-25T15:00:00Z"
        }
      },
      "createdOn": "2024-08-25T15:00:00Z",
      "finishedOn": "2024-08-25T15:00:00Z"
    }
  ],
  "limit": 0,
  "offset": 0,
  "total": 0,
  "hasMore": true,
  "next": "next"
}

json

application/json

Deploy to an environment

POST

https://dev-api-v4-main-a471234.zuplo.app

/v4/projects/{projectId}/deployments

Deploys to the project's environment given by environmentId. The deployment starts as pending: read it with GET /v4/projects/{projectId}/deployments/{deploymentId} until its status is succeeded or failed. Once it succeeds, the environment serves it at the environment's url. Until then, and if it fails, the environment keeps serving its previous deployment.

source says what to deploy:

upload: source code you upload, as zuplo deploy does. The response's upload says where: PUT a gzipped tar archive of the project to upload.url with upload.headers, before upload.expiresOn. The deployment starts when the archive arrives, and fails if it does not arrive in time. The upload URL works like a password, so it is returned only in this response.
deployment: an earlier deployment of the same environment, deployed again, for example to roll back, or to apply changed environment variables. It deploys that deployment's build as it is, or builds its source again with rebuild: true. During the preview, deploying a build as it is works only for the environment's live deployment, which applies changed environment variables. For an earlier one it answers 501: roll back with rebuild: true.

A project connected to a Git repository deploys every push to a branch itself (source.type: git). Zuplo deploys AI Gateway projects itself when their provider assignments change (source.type: zuplo), so creating a deployment for one fails with 400. Projects on managed dedicated hosting can only rebuild an earlier deployment (rebuild: true); deploying its build as it is fails with 400.

Fails with 400 when environmentId is not an environment of the project, or source.deploymentId is not a deployment of that environment. Fails with 409 while the environment is being deleted.

Deploy to an environment › path Parameters

projectId

string · maxLength: 64 · required

The project ID (prj_…). Its members, environments and deployments are addressed under it.

Deploy to an environment › Request Body

A new deployment.

CreateDeploymentRequest

environmentId

string · maxLength: 64 · required

The project's environment to deploy to.

Example: 4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90

DeploymentSourceInput · required

What to deploy. type says where it comes from.

Deploy to an environment › Responses

The deployment was created. For an upload source, upload says where to send the source.

A newly created deployment, with where to upload its source when `source.type` is `upload`.

DeploymentWithUpload

id

string · required

The deployment ID.

Example: a3c9e5d1-6b2f-4a8e-b7d4-1f0e9c8b2a65

projectId

string · required

The project the deployment belongs to.

Example: prj_Hn4QzW7cVb2LpX9sTe5RgK1m

environmentId

string · required

The environment it deploys to.

Example: 4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90

status

DeploymentStatus · enum · required

Enum values:

pending

running

succeeded

failed

DeploymentSource · required

What a deployment deployed.

createdOn

string · date-time · required

When the deployment was created.

finishedOn

string | null · date-time · required

When it succeeded or failed. Null while it is pending or running.

required

Where to upload the source, which is shown only once. Null unless source.type is upload.

POST/v4/projects/{projectId}/deployments

curl https://dev-api-v4-main-a471234.zuplo.app/v4/projects/:projectId/deployments \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "environmentId": "4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90",
  "source": {
    "type": "upload",
    "commitSha": "3f9c2a7e1b4d8f6a0c5e9b2d7a1f4c8e6b0d3a5f"
  }
}'

Example Request Body

{
  "environmentId": "4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90",
  "source": {
    "type": "upload",
    "commitSha": "3f9c2a7e1b4d8f6a0c5e9b2d7a1f4c8e6b0d3a5f"
  }
}

json

application/json

Example Responses

{
  "id": "a3c9e5d1-6b2f-4a8e-b7d4-1f0e9c8b2a65",
  "projectId": "prj_Hn4QzW7cVb2LpX9sTe5RgK1m",
  "environmentId": "4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90",
  "status": "pending",
  "source": {
    "type": "git",
    "deploymentId": "7e1d4b9a-3c6f-4d2e-8a5b-0f9c2e7d1b34",
    "rebuild": true,
    "commit": {
      "sha": "3f9c2a7e1b4d8f6a0c5e9b2d7a1f4c8e6b0d3a5f",
      "message": "Add rate limits to the orders API",
      "authorName": "Jane Doe",
      "committedOn": "2024-08-25T15:00:00Z"
    }
  },
  "createdOn": "2024-08-25T15:00:00Z",
  "finishedOn": "2024-08-25T15:00:00Z",
  "upload": {
    "url": "https://storage.googleapis.com/…",
    "headers": {
      "key": "string"
    },
    "expiresOn": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Get a deployment

GET

https://dev-api-v4-main-a471234.zuplo.app

/v4/projects/{projectId}/deployments/{deploymentId}

Returns a deployment, what it deployed and its status. After creating a deployment, read it until status is succeeded or failed.

Get a deployment › path Parameters

projectId

string · maxLength: 64 · required

The project ID (prj_…). Its members, environments and deployments are addressed under it.

deploymentId

string · maxLength: 64 · required

The deployment ID, a UUID.

Get a deployment › Responses

The deployment.

One build of a project's source, rolled out to one environment. Created, then read until its `status` is `succeeded` or `failed`.

Deployment

id

string · required

The deployment ID.

Example: a3c9e5d1-6b2f-4a8e-b7d4-1f0e9c8b2a65

projectId

string · required

The project the deployment belongs to.

Example: prj_Hn4QzW7cVb2LpX9sTe5RgK1m

environmentId

string · required

The environment it deploys to.

Example: 4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90

status

DeploymentStatus · enum · required

Enum values:

pending

running

succeeded

failed

DeploymentSource · required

What a deployment deployed.

createdOn

string · date-time · required

When the deployment was created.

finishedOn

string | null · date-time · required

When it succeeded or failed. Null while it is pending or running.

GET/v4/projects/{projectId}/deployments/{deploymentId}

curl https://dev-api-v4-main-a471234.zuplo.app/v4/projects/:projectId/deployments/:deploymentId \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "a3c9e5d1-6b2f-4a8e-b7d4-1f0e9c8b2a65",
  "projectId": "prj_Hn4QzW7cVb2LpX9sTe5RgK1m",
  "environmentId": "4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90",
  "status": "pending",
  "source": {
    "type": "git",
    "deploymentId": "7e1d4b9a-3c6f-4d2e-8a5b-0f9c2e7d1b34",
    "rebuild": true,
    "commit": {
      "sha": "3f9c2a7e1b4d8f6a0c5e9b2d7a1f4c8e6b0d3a5f",
      "message": "Add rate limits to the orders API",
      "authorName": "Jane Doe",
      "committedOn": "2024-08-25T15:00:00Z"
    }
  },
  "createdOn": "2024-08-25T15:00:00Z",
  "finishedOn": "2024-08-25T15:00:00Z"
}

json

application/json

Environments Buckets