DocsAPI ReferenceProjects & Deploys

Projects & Deploys

Create, deploy, and manage projects over the REST API.

Deploy and manage projects programmatically. Authenticate with an API key (X-API-Key: sm_live_...) — a deploy-scoped key is enough for everything here.

The deploy lifecycle

  1. Create a project (from a git repo, a prebuilt image, or an upload)
  2. Set env vars (optional)
  3. Deploy — builds (if needed) and starts the container
  4. Poll the project until status is running or failed

List projects

code
GET /api/v1/projects

Create a project

code
POST /api/v1/projects

From a GitHub repo:

json
{ "name": "api", "subdomain": "api", "repo_url": "https://github.com/you/api.git", "github_repo": "you/api", "branch": "main" }

From a prebuilt image (no build — docker pull + run):

json
{ "name": "proxy", "subdomain": "proxy", "image": "nginx:alpine" }

From an upload: create with "deploy_source": "upload", then POST a .tar.gz build context to /api/v1/projects/:id/upload before deploying.

The response is the project object, including its id.

Set environment variables

code
PUT /api/v1/projects/:id
json
{ "env_vars": { "DATABASE_URL": "postgres://...", "NODE_ENV": "production" } }

Advanced build settings

code
PUT /api/v1/projects/:id/build-config
json
{ "install_cmd": "npm ci", "build_cmd": "npm run build", "start_cmd": "npm start", "root_dir": "apps/web", "port_override": 3000 }

Multiple services (one container)

Deploy several directories of a monorepo as services inside a single container. Pass a services array to the build-config endpoint — the primary app keeps the project's port + subdomain, and each service gets a flat sibling subdomain (<subdomain>-<name>.deployzy.com):

json
{
  "services": [
    { "name": "api", "root_dir": "apps/api", "port": 4000, "install_cmd": "npm ci", "build_cmd": "npm run build", "start_cmd": "npm start", "env_overrides": { "SERVICE_MODE": "api" } },
    { "name": "worker", "root_dir": "worker", "port": 4001, "start_cmd": "node worker.js" }
  ]
}

Names must be lowercase DNS-safe labels, unique, with unique ports (max 5 services). Omit services (or send []) for a single-service project.

Deploy

code
POST /api/v1/projects/:id/deploy

Logs & status

code
GET /api/v1/projects/:id          # { project, logs }
GET /api/v1/projects/:id/logs     # deploy log lines

project.status moves through building → running (or failed).

Stop / delete

code
POST   /api/v1/projects/:id/stop
DELETE /api/v1/projects/:id

End-to-end (curl)

bash

# 1. Create from a repo PID=$(curl -s -X POST https://api.deployzy.com/api/v1/projects \ -H "X-API-Key: $KEY" -H "Content-Type: application/json" \ -d '{"name":"api","subdomain":"api","repo_url":"https://github.com/you/api.git","github_repo":"you/api","branch":"main"}' \ | jq -r .id)

# 2. Deploy curl -s -X POST https://api.deployzy.com/api/v1/projects/$PID/deploy -H "X-API-Key: $KEY"

# 3. Poll status curl -s https://api.deployzy.com/api/v1/projects/$PID -H "X-API-Key: $KEY" | jq -r .project.status ```

Prefer a client library? See the JavaScript and Python SDKs, or the `deployzy deploy` CLI.
PreviousAPI KeysNextInspection