Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nayalsaurav/deploy-your-app/llms.txt

Use this file to discover all available pages before exploring further.

The Trigger Deploy endpoint lets you manually kick off a new deployment for any existing project without pushing a commit to GitHub. The platform creates a fresh deployment record, decrypts the project’s stored environment variables, and adds a build job to the queue using the project’s defaultBranch and current build configuration. This is useful for re-deploying after updating environment variables, recovering from a failed deployment, or deploying on demand without a code change. POST /api/v1/projects/:id/deploy

​
Authentication

This endpoint requires an active session and a connected GitHub account. Your GitHub OAuth access token is used to clone the repository during the build. See Authentication for details on obtaining a session token.

​
Request

​
Path Parameters

​
id
string
required
The unique project ID (cuid) of the project to deploy.
This endpoint requires no request body.
The deployment always uses the project’s configured defaultBranch. To deploy a different branch, first update the project’s defaultBranch via the Update Project endpoint, then trigger a new deployment.

​
Response

A successful 201 Created response returns the newly queued deployment record: 
{
  "message": "Deployment queued successfully",
  "data": {
    "deployment": Deployment
  }
}

​
Response Fields

​
message
string
Human-readable status message — "Deployment queued successfully".
​
data
object
Wrapper object containing the new deployment record.

​
Deployment Lifecycle

After this endpoint returns 201, the deployment progresses asynchronously through the following stages:
StatusDescription
PENDINGQueued and waiting for a worker to pick it up.
CLONINGCloning the repository from GitHub.
DETECTINGAuto-detecting the framework (Next.js, Vite, Node.js, etc.).
ALLOCATINGReserving a container port for the application.
BUILDINGRunning the build command inside a Docker container.
DEPLOYINGStarting the container and routing traffic.
SUCCESSApplication is live and accessible.
FAILEDBuild or start encountered an unrecoverable error.
Poll the Get Project endpoint to track the deployment’s status, logs, and url fields as it progresses.

​
Example

curl -X POST https://your-domain.com/api/v1/projects/clx4z2k0e0000abc123def456/deploy \
  -H 'Content-Type: application/json' \
  -b 'better-auth.session_token=YOUR_SESSION_TOKEN'
Example response (201 Created): 
{
  "message": "Deployment queued successfully",
  "data": {
    "deployment": {
      "id": "clx6b4c2d0003uvw901jkl234",
      "projectId": "clx4z2k0e0000abc123def456",
      "branch": "main",
      "commitHash": null,
      "status": "PENDING",
      "url": null,
      "port": null,
      "logs": null,
      "error": null,
      "createdAt": "2024-06-11T15:00:00.000Z",
      "updatedAt": "2024-06-11T15:00:00.000Z",
      "completedAt": null
    }
  }
}

​
Error Responses

StatusError MessageDescription
401"Unauthorized"No valid session cookie was provided.
401"No GitHub access token found"The authenticated user has not connected a GitHub account or the token has expired.
404"Project not found or unauthorized"No project with the given ID exists, or it belongs to another user.
500"Internal server error"An unexpected server-side error occurred, such as a queue connection failure.

Build docs developers (and LLMs) love

Get started for freeTalk to us