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 Update Project endpoint allows you to modify one or more settings on an existing project without touching unspecified fields. You can rename the project, change build and start commands, adjust the root directory, switch the default branch, or attach and remove a custom domain — all in a single request by including only the fields you want to change. PATCH /api/v1/projects/:id

​
Authentication

This endpoint requires an active session. Include your session cookie with every request. See Authentication for details on obtaining a session token.

​
Request

​
Path Parameters

​
id
string
required
The unique project ID (cuid) of the project to update.

​
Body Parameters

All body fields are optional. Include only the fields you wish to change.
​
name
string
New display name for the project.
​
rootDirectory
string
Path to the application root within the repository, relative to the repo root (e.g. "apps/web"). Omit or set to null to use the repository root.
​
buildCommand
string
Custom build command that overrides auto-detection (e.g. "npm run build:prod"). Set to null to revert to auto-detection.
​
startCommand
string
Custom start command that overrides auto-detection (e.g. "node dist/server.js"). Set to null to revert to auto-detection.
​
defaultBranch
string
Git branch to use for future production deployments (e.g. "develop").
​
customDomain
string | null
A custom hostname to attach to this project (e.g. "app.example.com"). Pass null or an empty string to remove an existing custom domain.
Domain validation rules: The value must be a valid hostname — no wildcards (*), no path segments (/), and no protocol prefix (https://). For example, "app.example.com" is valid while "*.example.com" or "example.com/app" are not. The domain is also normalised to lowercase and must be unique across all projects on the platform. Setting a new custom domain resets customDomainVerified to false until DNS propagation is confirmed.

​
Response

A successful 200 OK response returns the fully updated project object: 
{
  "message": "Project updated successfully",
  "data": {
    "project": Project
  }
}

​
Response Fields

​
message
string
Human-readable status message — "Project updated successfully".
​
data
object
Wrapper object containing the updated project.

​
Example

curl -X PATCH https://your-domain.com/api/v1/projects/clx4z2k0e0000abc123def456 \
  -H 'Content-Type: application/json' \
  -b 'better-auth.session_token=YOUR_SESSION_TOKEN' \
  -d '{
    "name": "My Renamed App",
    "defaultBranch": "production",
    "buildCommand": "npm run build:prod",
    "customDomain": "app.example.com"
  }'
Example response: 
{
  "message": "Project updated successfully",
  "data": {
    "project": {
      "id": "clx4z2k0e0000abc123def456",
      "userId": "user_01hxyz",
      "name": "My Renamed App",
      "repositoryFullName": "acme/my-nextjs-app",
      "defaultBranch": "production",
      "buildCommand": "npm run build:prod",
      "startCommand": null,
      "rootDirectory": null,
      "deploymentUrl": "https://my-nextjs-app.your-domain.com",
      "customDomain": "app.example.com",
      "customDomainVerified": false,
      "createdAt": "2024-06-01T12:00:00.000Z",
      "updatedAt": "2024-06-11T14:22:00.000Z"
    }
  }
}

​
Error Responses

StatusError MessageDescription
400"Invalid domain format. Please provide a valid hostname (e.g., app.example.com)."The supplied customDomain value failed hostname validation.
400"Domain is already in use by another project."The normalised domain is already attached to a different project.
401"Unauthorized"No valid session cookie was provided.
404"Project not found"No project with the given ID exists, or it belongs to another user.
500"Failed to update project"An unexpected server-side error occurred.

Build docs developers (and LLMs) love

Get started for freeTalk to us