Deployments

Deployments are asynchronous: starting one enqueues a background job and returns immediately with an id. You then poll the detail endpoint for status transitions, logs, and — on success — the live frontend and backend URLs.

Deployment statuses#

The status field on every deployment moves through this state machine (see the deployment lifecycle for the full walkthrough):

Status	Meaning
PENDING	Queued, waiting for a worker.
ANALYZING	Reading the repo tree and detecting the stack.
WAITING_FOR_ENV	Paused — required env vars are missing. Provide them via `POST /deployments/:id/env` to resume.
DEPLOYING_BACKEND	Creating/deploying the Render web service.
BACKEND_READY	Backend is live; its URL is being wired into the frontend build.
DEPLOYING_FRONTEND	Building and deploying the frontend to Vercel.
COMPLETED	Success — `frontendUrl` / `backendUrl` are live.
FAILED	Terminal failure — `error` is set and the log tail includes an AI diagnosis.
CANCELLED	Cancelled by the user.

Polling

Poll GET /deployments/:id until status is COMPLETED, FAILED, or CANCELLED — or until it parks at WAITING_FOR_ENV, which needs your input. The deplo CLI polls every 2.5 seconds; that cadence fits well within the rate limit.

GET/api/v1/deploymentsBearer token

Lists all deployments for the authenticated user as a JSON array, newest first. Logs and env metadata are omitted here — fetch the detail endpoint for those.

Field	Type	Description
id	string	Deployment id (cuid).
repositoryId	string	The deployed repository's id.
repositoryName	string	Repository name.
repositoryFullName	string	`owner/name`.
status	string	One of the statuses above.
branch	string	Deployed branch.
frontendUrl	string \| null	Live Vercel URL once the frontend is deployed.
backendUrl	string \| null	Live Render URL once the backend is deployed.
detectedStack	object \| null	`{ frontend, backend }` as human-readable labels (e.g. “Next.js”, “Express.js”), each nullable. Null until analysis completes.
createdAt / updatedAt	string	ISO timestamps.
duration	number \| null	Total seconds from creation to completion; null while in progress.

request

curl https://www.deplo.in/api/v1/deployments \
  -H "Authorization: Bearer $DEPLO_TOKEN"

response · 200

[
  {
    "id": "cm5xc4d5e0003njk8t8u9v0w1",
    "repositoryId": "cm5xb2c3d0002njk8p4q5r6s7",
    "repositoryName": "acme-shop",
    "repositoryFullName": "adalovelace/acme-shop",
    "status": "COMPLETED",
    "branch": "main",
    "frontendUrl": "https://deplo-acme-shop-web.vercel.app",
    "backendUrl": "https://deplo-acme-shop-api.onrender.com",
    "detectedStack": { "frontend": "Next.js", "backend": "Express.js" },
    "createdAt": "2026-08-06T18:30:02.000Z",
    "updatedAt": "2026-08-06T18:33:11.000Z",
    "duration": 189
  }
]

POST/api/v1/deploymentsBearer token

Starts a deployment for a repository: creates the deployment record, enqueues the orchestration job, and returns 201 immediately. Pass envVars up front to avoid a WAITING_FOR_ENV pause when you already know the values.

Field	Type	Description
repositoryId	string	Required. A repository id from GET /repos.
envVars	array	Optional. Pre-filled variables as `[{ key, value }]`.

request

curl -X POST https://www.deplo.in/api/v1/deployments \
  -H "Authorization: Bearer $DEPLO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repositoryId":"cm5xb2c3d0002njk8p4q5r6s7","envVars":[{"key":"DATABASE_URL","value":"postgres://…"}]}'

response · 201

{
  "deploymentId": "cm5xc4d5e0003njk8t8u9v0w1",
  "status": "PENDING"
}

response · 400

{
  "error": {
    "message": "Invalid request body",
    "details": {
      "formErrors": [],
      "fieldErrors": { "repositoryId": ["String must contain at least 1 character(s)"] }
    }
  }
}

GET/api/v1/deployments/:idBearer token

Fetches a single deployment with its full log stream, error (if any), and detected env variable metadata. This is the endpoint to poll while a deployment runs.

Field	Type	Description
envVariables[]	array	Detected variables as `[{ key, isRequired }]` — values are never returned.
logs	string[]	Ordered log lines, appended live as the deployment progresses.
error	string \| null	Failure summary when `status` is `FAILED`.

All other fields match the list shape above.

request

curl https://www.deplo.in/api/v1/deployments/cm5xc4d5e0003njk8t8u9v0w1 \
  -H "Authorization: Bearer $DEPLO_TOKEN"

response · 200

{
  "id": "cm5xc4d5e0003njk8t8u9v0w1",
  "repositoryId": "cm5xb2c3d0002njk8p4q5r6s7",
  "repositoryName": "acme-shop",
  "repositoryFullName": "adalovelace/acme-shop",
  "status": "WAITING_FOR_ENV",
  "branch": "main",
  "frontendUrl": null,
  "backendUrl": null,
  "detectedStack": { "frontend": "Next.js", "backend": "Express.js" },
  "envVariables": [
    { "key": "DATABASE_URL", "isRequired": true },
    { "key": "STRIPE_SECRET_KEY", "isRequired": true }
  ],
  "logs": [
    "Analyzing repository…",
    "Detected: frontend=Next.js (client/) · backend=Express (server/)",
    "Waiting for required environment variables: DATABASE_URL, STRIPE_SECRET_KEY"
  ],
  "error": null,
  "createdAt": "2026-08-06T18:30:02.000Z",
  "updatedAt": "2026-08-06T18:30:19.000Z",
  "duration": null
}

POST/api/v1/deployments/:id/envBearer token

Provides environment variable values for a deployment paused in WAITING_FOR_ENV, then resumes it. Returns the deployment id and its new status.

Field	Type	Description
envVars	array	Required. `[{ key, value }]` for the missing variables.

request

curl -X POST https://www.deplo.in/api/v1/deployments/cm5xc4d5e0003njk8t8u9v0w1/env \
  -H "Authorization: Bearer $DEPLO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"envVars":[{"key":"DATABASE_URL","value":"postgres://…"},{"key":"STRIPE_SECRET_KEY","value":"sk_live_…"}]}'

response · 200

{
  "deploymentId": "cm5xc4d5e0003njk8t8u9v0w1",
  "status": "PENDING"
}

DELETE/api/v1/deployments/:idBearer token

Cancels an in-progress deployment. Returns the deployment id and its resulting status. Cancelling a deployment that already reached a terminal state returns 409 CONFLICT.

request

curl -X DELETE https://www.deplo.in/api/v1/deployments/cm5xc4d5e0003njk8t8u9v0w1 \
  -H "Authorization: Bearer $DEPLO_TOKEN"

response · 200

{
  "deploymentId": "cm5xc4d5e0003njk8t8u9v0w1",
  "status": "CANCELLED"
}