Skip to main content
POST
/
api
/
deployment
Create Deployment
curl --request POST \
  --url https://api.example.com/api/deployment \
  --header 'Content-Type: application/json' \
  --data '
{
  "projectId": "<string>",
  "name": "<string>",
  "codeLink": "<string>",
  "projectType": "<string>",
  "branchname": "<string>",
  "isFolder": true,
  "folderName": "<string>",
  "env": {},
  "buildCommand": "<string>",
  "publishDir": "<string>",
  "startCommand": "<string>",
  "port": 123
}
'
{
  "success": true,
  "buildId": "<string>",
  "status": "<string>",
  "newProject": {
    "_id": "<string>",
    "name": "<string>",
    "owner": "<string>",
    "projectType": "<string>",
    "repoLink": "<string>",
    "status": "<string>",
    "subdomain": "<string>",
    "buildId": "<string>",
    "totalBuilds": 123,
    "env": {},
    "settings": {
      "repoBranchName": "<string>",
      "folder": {
        "enabled": true,
        "name": "<string>"
      }
    },
    "buildCommand": "<string>",
    "publishDir": "<string>",
    "startCommand": "<string>",
    "port": 123,
    "plan": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>"
  },
  "message": "<string>"
}
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

​
projectId
string
required
MongoDB ObjectId of the project to deploy. Must be a valid ObjectId format.
​
name
string
required
Display name for the project.
​
codeLink
string
required
GitHub repository URL. Can end with .git or not. Format: https://github.com/owner/repo or https://github.com/owner/repo.git
​
projectType
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)
​
branchname
string
required
Git branch name to deploy from (e.g., main, develop).
​
isFolder
boolean
required
Indicates if the project is in a monorepo/subfolder. Must be a boolean value.
​
folderName
string
Name of the subfolder containing the project. Required when isFolder is true. Must be a string.
​
env
object
Environment variables as key-value pairs. Must be an object.Example:
{
  "API_KEY": "your-api-key",
  "NODE_ENV": "production"
}

​
Static Project Fields

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

​
Node.js Project Fields

​
startCommand
string
Start command for Node.js projects (e.g., npm start, node index.js). Required when projectType is node.
​
port
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

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

​
Error Responses

​
message
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)

{
  "projectId": "507f1f77bcf86cd799439011",
  "name": "my-react-app",
  "codeLink": "https://github.com/username/react-app.git",
  "projectType": "static",
  "buildCommand": "npm run build",
  "publishDir": "dist",
  "branchname": "main",
  "isFolder": false,
  "env": {
    "VITE_API_URL": "https://api.example.com",
    "NODE_ENV": "production"
  }
}

​
Node.js Application

{
  "projectId": "507f1f77bcf86cd799439012",
  "name": "express-api",
  "codeLink": "https://github.com/username/express-server",
  "projectType": "node",
  "startCommand": "node server.js",
  "port": 3000,
  "branchname": "main",
  "isFolder": false,
  "env": {
    "DATABASE_URL": "postgresql://...",
    "JWT_SECRET": "your-secret-key"
  }
}

​
Monorepo Project

{
  "projectId": "507f1f77bcf86cd799439013",
  "name": "frontend",
  "codeLink": "https://github.com/username/monorepo.git",
  "projectType": "static",
  "buildCommand": "npm run build",
  "publishDir": "build",
  "branchname": "develop",
  "isFolder": true,
  "folderName": "packages/frontend",
  "env": {
    "REACT_APP_API_URL": "https://api.example.com"
  }
}

​
Response Example

{
  "success": true,
  "buildId": "507f1f77bcf86cd799439020",
  "status": "queued",
  "newProject": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "my-react-app",
    "owner": "507f1f77bcf86cd799439000",
    "projectType": "static",
    "repoLink": "https://github.com/username/react-app.git",
    "buildCommand": "npm run build",
    "publishDir": "dist",
    "status": "pending",
    "subdomain": "my-react-app-a3f9k2",
    "buildId": "507f1f77bcf86cd799439020",
    "totalBuilds": 1,
    "env": {
      "VITE_API_URL": "https://api.example.com",
      "NODE_ENV": "production"
    },
    "settings": {
      "repoBranchName": "main",
      "folder": {
        "enabled": false
      }
    },
    "plan": "free",
    "totalRequest": 0,
    "hascustomDomain": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

​
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