Deployments
Create Deployment
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 viaverifyJWT 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.
string
required
GitHub repository URL. Can end with
.git or not. Format: https://github.com/owner/repo or https://github.com/owner/repo.gitstring
required
Type of project to deploy. Must be one of:
static- Static site (requiresbuildCommandandpublishDir)node- Node.js application (requiresstartCommandandport)
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:projectIdmust be a valid MongoDB ObjectIdprojectTypemust be exactlystaticornodeenvmust be an object if providedisFoldermust be a boolean- For static projects:
buildCommandandpublishDirare mandatory - For node projects:
startCommandandportare mandatory - When
isFolderistrue,folderNameis 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 notpending - 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:- A new
Buildrecord is created with statuspending - A unique subdomain is generated with format
{name}-{6-char-random} - A
Bindingrecord is created linking the subdomain to the project and port - Subdomain data is cached in Redis with port, projectId, and plan
- Build job is added to
buildqueuewith buildId and projectId - 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
githubAccessTokenif available for private repos - Falls back gracefully if fetch fails (continues without commit check)
- Extracted owner and repo from
codeLinkautomatically