Environments

An environment is one deployed copy of a project's gateway, with its own URL. A project has three types:

production: one, for the project's default Git branch.
preview: one for each other branch, for example to try a change before it is merged.
working-copy: one for each person who edits the project in the portal. Each person sees only their own.

An AI Gateway project has only its production environment.

Environments are listed, created and read in their project (/v4/projects/{projectId}/environments/{environmentId}). A project connected to a Git repository creates a branch's environment on the first push to it, and deletes it with the branch. What an environment serves is its live deployment (see Deployments).

An AI Gateway environment has no status (it is null): nothing reliably says that a gateway serves its newest configuration, so v4 does not claim it. Read its deployments instead (see Deployments).

List environments

GET

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

/v4/projects/{projectId}/environments

Lists the project's environments, oldest first. Filter by type to list only its production or preview environments, and by branch to find the environment of a Git branch. Each person sees their own working copies, and nobody else's.

List environments › path Parameters

projectId

string · maxLength: 64 · required

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

List environments › query Parameters

type

EnvironmentType · enum

Only return environments of this type.

The environment of a project. New values may be added.

Enum values:

working-copy

preview

production

branch

string · maxLength: 255

Only return the environment of this Git branch.

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 environments › Responses

A page of environments.

EnvironmentList

Environment[] · required

The environments 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}/environments

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

Example Responses

{
  "data": [
    {
      "id": "4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90",
      "projectId": "prj_Hn4QzW7cVb2LpX9sTe5RgK1m",
      "name": "acme-api-rate-limit-9f628be",
      "type": "working-copy",
      "branch": "rate-limits",
      "userId": "user_Jm5tR8wQz2KcX7vB4nLp9HdS",
      "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
      "status": "provisioning",
      "url": "https://acme-api-rate-limit-9f628be.zuplo.app",
      "liveDeploymentId": "a3c9e5d1-6b2f-4a8e-b7d4-1f0e9c8b2a65",
      "hasCustomDomain": true,
      "createdOn": "2024-08-25T15:00:00Z",
      "updatedOn": "2024-08-25T15:00:00Z"
    }
  ],
  "limit": 0,
  "offset": 0,
  "total": 0,
  "hasMore": true,
  "next": "next"
}

json

application/json

Create an environment

POST

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

/v4/projects/{projectId}/environments

Creates the environment of a Git branch in the project. It is the project's production environment when branch is the project's default branch, and a preview environment otherwise. It has no URL and its status is provisioning until its first deployment succeeds: deploy to it with POST /v4/projects/{projectId}/deployments.

A project connected to a Git repository creates a branch's environment itself, on the first push to the branch, and deploys every push. Create one here to deploy a branch from the CLI or the API. Working copies are created in the portal, for the person who edits the project there.

Fails with 409 when the project already has an environment for branch, and with 400 for an ai-gateway project, which has its production environment only.

Create an environment › path Parameters

projectId

string · maxLength: 64 · required

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

Create an environment › Request Body

A new environment for a Git branch.

CreateEnvironmentRequest

branch

string · minLength: 1 · maxLength: 255 · pattern: ^[^\s~]+$ · required

The Git branch the environment deploys, without refs/heads/. It cannot contain ~ or whitespace, and cannot be changed later.

Example: rate-limits

Create an environment › Responses

The environment was created. Nothing is deployed to it yet.

One deployed copy of a project's gateway, with its own URL: the production environment, a preview environment for a Git branch, or a person's working copy. It serves its live deployment.

Environment

id

string · required

The environment ID.

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

projectId

string · required

The project the environment belongs to.

Example: prj_Hn4QzW7cVb2LpX9sTe5RgK1m

name

string · required

The environment's name, unique across Zuplo and the first label of its URL's host: the project name, the branch and a random suffix. The CLI and logs show it. Not an identifier; address environments by id.

Example: acme-api-rate-limit-9f628be

type

EnvironmentType · enum · required

The environment of a project. New values may be added.

Enum values:

working-copy

preview

production

branch

string | null · required

The Git branch the environment deploys, unique among the project's production and preview environments. The production environment's is the project's default branch. Null for a working copy, which deploys what its person edits in the portal.

Example: rate-limits

required

The person whose working copy this is. Null for production and preview environments.

bucketId

string · required

The bucket the environment keeps its gateway data in, such as consumers and API keys. A project's environments of one type share their bucket: every preview environment uses the project's preview bucket. An AI Gateway keeps its data in its production bucket.

Example: bckt_Y40ypGODCDP3S7iZxNwCAbIe

required

Whether the environment serves a deployment. Null for an AI Gateway environment: nothing reliably says that every edge of an AI Gateway serves its newest configuration, so v4 does not report it. Read the environment's newest deployment (GET /v4/projects/{projectId}/deployments?environmentId=…&limit=1) until it has succeeded instead, and send the gateway a request to know what it serves.

url

string | null · uri · required

The environment's default URL. Null until its first deployment succeeds.

Example: https://acme-api-rate-limit-9f628be.zuplo.app

liveDeploymentId

string | null · required

The deployment the environment serves, the last one that succeeded. Null until one has.

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

hasCustomDomain

boolean · required

Whether a custom domain points at the environment. An environment with one cannot be deleted.

createdOn

string · date-time · required

When the environment was created.

updatedOn

string · date-time · required

When the environment last changed.

POST/v4/projects/{projectId}/environments

curl https://dev-api-v4-main-a471234.zuplo.app/v4/projects/:projectId/environments \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "branch": "rate-limits"
}'

Example Request Body

{
  "branch": "rate-limits"
}

json

application/json

Example Responses

{
  "id": "4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90",
  "projectId": "prj_Hn4QzW7cVb2LpX9sTe5RgK1m",
  "name": "acme-api-rate-limit-9f628be",
  "type": "working-copy",
  "branch": "rate-limits",
  "userId": "user_Jm5tR8wQz2KcX7vB4nLp9HdS",
  "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
  "status": "provisioning",
  "url": "https://acme-api-rate-limit-9f628be.zuplo.app",
  "liveDeploymentId": "a3c9e5d1-6b2f-4a8e-b7d4-1f0e9c8b2a65",
  "hasCustomDomain": true,
  "createdOn": "2024-08-25T15:00:00Z",
  "updatedOn": "2024-08-25T15:00:00Z"
}

json

application/json

Get an environment

GET

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

/v4/projects/{projectId}/environments/{environmentId}

Returns an environment: its type, Git branch, URL, and the deployment it serves. Read it until status is live after its first deployment, or until it is gone (404) after deleting it. An AI Gateway environment has no status (null): read its newest deployment, GET /v4/projects/{projectId}/deployments?environmentId=…&limit=1, until it has succeeded instead.

Get an environment › path Parameters

projectId

string · maxLength: 64 · required

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

environmentId

string · maxLength: 64 · required

The environment ID, a UUID.

Get an environment › Responses

The environment.

One deployed copy of a project's gateway, with its own URL: the production environment, a preview environment for a Git branch, or a person's working copy. It serves its live deployment.

Environment

id

string · required

The environment ID.

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

projectId

string · required

The project the environment belongs to.

Example: prj_Hn4QzW7cVb2LpX9sTe5RgK1m

name

string · required

Example: acme-api-rate-limit-9f628be

type

EnvironmentType · enum · required

The environment of a project. New values may be added.

Enum values:

working-copy

preview

production

branch

string | null · required

Example: rate-limits

required

The person whose working copy this is. Null for production and preview environments.

bucketId

string · required

Example: bckt_Y40ypGODCDP3S7iZxNwCAbIe

required

url

string | null · uri · required

The environment's default URL. Null until its first deployment succeeds.

Example: https://acme-api-rate-limit-9f628be.zuplo.app

liveDeploymentId

string | null · required

The deployment the environment serves, the last one that succeeded. Null until one has.

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

hasCustomDomain

boolean · required

Whether a custom domain points at the environment. An environment with one cannot be deleted.

createdOn

string · date-time · required

When the environment was created.

updatedOn

string · date-time · required

When the environment last changed.

GET/v4/projects/{projectId}/environments/{environmentId}

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

Example Responses

{
  "id": "4f8b6c1e-2d7a-4e3b-9c5f-8a1d2e6b7c90",
  "projectId": "prj_Hn4QzW7cVb2LpX9sTe5RgK1m",
  "name": "acme-api-rate-limit-9f628be",
  "type": "working-copy",
  "branch": "rate-limits",
  "userId": "user_Jm5tR8wQz2KcX7vB4nLp9HdS",
  "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
  "status": "provisioning",
  "url": "https://acme-api-rate-limit-9f628be.zuplo.app",
  "liveDeploymentId": "a3c9e5d1-6b2f-4a8e-b7d4-1f0e9c8b2a65",
  "hasCustomDomain": true,
  "createdOn": "2024-08-25T15:00:00Z",
  "updatedOn": "2024-08-25T15:00:00Z"
}

json

application/json

Delete an environment

DELETE

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

/v4/projects/{projectId}/environments/{environmentId}

Deletes a preview environment and its deployments. Zuplo stops serving its URL and removes what it runs on in the background: until then it is listed with status: deleting, and reads of it return 404 once it is gone. Its bucket is shared by the project's other preview environments and stays.

A project connected to a Git repository deletes a branch's preview environment itself when the branch is deleted. Deleting it here while the branch still exists does not stop the next push from creating it again.

Only preview environments can be deleted: the production environment goes with its project, and working copies are managed in the portal. Fails with 409 for either, and while a custom domain points at the environment (hasCustomDomain). A repeated delete returns 404 once the environment is gone, which clients should treat as success.

Delete an environment › path Parameters

projectId

string · maxLength: 64 · required

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

environmentId

string · maxLength: 64 · required

The environment ID, a UUID.

Delete an environment › Responses

The environment is being deleted.

No data returned

Project Members Deployments