Skip to main content
POST
Create Deployment
Creates a new deployment for a project. This endpoint initializes the deployment process by:
  • Validating project ownership and configuration
  • Fetching the latest commit SHA from GitHub
  • Generating a unique subdomain
  • Creating a build record
  • Adding the deployment to the build queue

Authentication

Requires JWT authentication via verifyJWT middleware.

Request Body

string
required
MongoDB ObjectId of the project to deploy. Must be a valid ObjectId format.
string
required
Display name for the project.
GitHub repository URL. Can end with .git or not. Format: https://github.com/owner/repo or https://github.com/owner/repo.git
string
required
Type of project to deploy. Must be one of:
  • static - Static site (requires buildCommand and publishDir)
  • node - Node.js application (requires startCommand and port)
string
required
Git branch name to deploy from (e.g., main, develop).
boolean
required
Indicates if the project is in a monorepo/subfolder. Must be a boolean value.
string
Name of the subfolder containing the project. Required when isFolder is true. Must be a string.
object
Environment variables as key-value pairs. Must be an object.Example:

Static Project Fields

string
Build command for static projects (e.g., npm run build, yarn build). Required when projectType is static.
string
Output directory after build (e.g., dist, build, out). Required when projectType is static. Sets internal port to 80.

Node.js Project Fields

string
Start command for Node.js projects (e.g., npm start, node index.js). Required when projectType is node.
number
Port number the Node.js application listens on (e.g., 3000, 8080). Required when projectType is node. Used as internal port for routing.

Validation Rules

The endpoint validates:
  • projectId must be a valid MongoDB ObjectId
  • projectType must be exactly static or node
  • env must be an object if provided
  • isFolder must be a boolean
  • For static projects: buildCommand and publishDir are mandatory
  • For node projects: startCommand and port are mandatory
  • When isFolder is true, folderName is mandatory and must be a string
  • Project must exist and be owned by authenticated user
  • Project status must be pending (no reconfiguration allowed)

Response

boolean
Indicates if the deployment was initiated successfully.
string
MongoDB ObjectId of the created build record.
string
Build status. Always returns queued on successful creation.
object
Complete project object with updated configuration.

Error Responses

string
Error message describing what went wrong.

Common Errors

  • 400 Bad Request: Validation errors (invalid projectId format, missing required fields, invalid projectType)
  • 400 Bad Request: "Invalid ProjectId" - Project not found
  • 400 Bad Request: "reconfig not" - Project status is not pending
  • 403 Forbidden: "You are not authorized to deploy this project" - User doesn’t own the project
  • 500 Internal Server Error: "Internal server Error" - Server processing error

Build Queue Integration

On successful deployment creation:
  1. A new Build record is created with status pending
  2. A unique subdomain is generated with format {name}-{6-char-random}
  3. A Binding record is created linking the subdomain to the project and port
  4. Subdomain data is cached in Redis with port, projectId, and plan
  5. Build job is added to buildqueue with buildId and projectId
  6. Project status remains in original state until build worker processes it

Request Examples

Static Project (React App)

Node.js Application

Monorepo Project

Response Example

Commit SHA Fetching

The endpoint attempts to fetch the latest commit SHA from GitHub:
  • Uses the GitHub API: GET /repos/{owner}/{repo}/git/ref/heads/{branch}
  • Includes user’s githubAccessToken if available for private repos
  • Falls back gracefully if fetch fails (continues without commit check)
  • Extracted owner and repo from codeLink automatically