POST/v2/projects/{project_id}/deploymentsStable

Create a deployment

Queue a new build for a project and deploy the result to a preview or production domain. The call returns as soon as the build is queued — subscribe to deployment.ready or poll the deployment object to follow progress.

Bearer tokendeployments:write60 req/minUpdated Nov 2, 2026

Deployments are immutable. To change a build, create a new deployment. Rollbacks reuse this endpoint with a previous commit SHA — read the rollback guide.

Base URLhttps://api.ingot.dev/v2

AuthenticationAuthorization: Bearer $INGOT_API_KEYManage keys

Path parameters

Path parameters for creating a deployment
Parameter	Type	Description
`project_id`*	`string` required	Project identifier. Accepts the project slug or its prj_ prefixed ID. Example `prj_7Hq2`

Query parameters

Query parameters for creating a deployment
Parameter	Type	Description
`dry_run`	`boolean` optional	Validate the payload and return a preview without queueing a build. Default `false`
`force`	`boolean` optional	Queue a new build even when the same commit already has an active deployment. Default `false`

Body parameters

application/json

Request body parameters for creating a deployment
Parameter	Type	Description
`ref`*	`string` required	Git ref to build. Branch, tag or full commit SHA. Short SHAs are rejected. Example `main`
`environment`*	`enum` required	Target environment for the deployment. `productionpreviewdevelopment`Default `production`
`region`	`string` optional	Build region. Defaults to the project primary region when omitted. Example `fra1`
`build`	`object` optional	Per-deployment build overrides. Omitted keys inherit the project settings.
`env`	`object` optional	Environment variables merged over project defaults. Values are encrypted at rest. Example `{ "FEATURE_FLAGS": "checkout-v3" }`
`metadata`	`object` optional	Up to 20 key-value pairs stored with the deployment for tracing and search.
`auto_assign_domains`	`boolean` optional	Attach the project production domain or preview pattern after a successful build. Default `true`

Fields marked with * are required. Unknown fields are rejected with a 422 rather than ignored.

Request example

Pick your runtime

Every sample sends the same payload. Swap the project ID and ref for your own, and keep the key server-side.

shell

curl --request POST \

--url https://api.ingot.dev/v2/projects/prj_7Hq2/deployments \

--header 'Authorization: Bearer $INGOT_API_KEY' \

--header 'Content-Type: application/json' \

--data '{

"ref": "main",

"environment": "production",

"build": {

"command": "pnpm build",

"node_version": "22"

},

"metadata": {

"commit": "9f3c1a2",

"actor": "ci"

}

}'

Response

JSON · charset=utf-8

A successful request returns 201 with the deployment object and a Location header. Errors always return a single error object with a stable code.

application/json

The deployment is queued. Follow the Location header to poll its status.

{

"id": "dep_8mQ1rT",

"object": "deployment",

"status": "queued",

"environment": "production",

"project_id": "prj_7Hq2",

"ref": "main",

"url": "https://acme-storefront.ingot.dev",

"region": "fra1",

"created_at": "2026-11-06T09:41:12Z",

"build": {

"command": "pnpm build",

"node_version": "22",

"duration_ms": null

},

"metadata": {

"commit": "9f3c1a2",

"actor": "ci"

}

Response fields

deployment object

Fields returned on the deployment object
Parameter	Type	Description
`id`	`string` optional	Unique deployment identifier. Example `dep_8mQ1rT`
`status`	`enum` optional	Current lifecycle state. Poll until a terminal state is reached. `queuedbuildingreadyfailedcanceled`
`url`	`string` optional	Stable preview URL. Becomes the production URL once the deployment is promoted.
`created_at`	`string` optional	ISO 8601 timestamp of when the deployment was queued.
`build.duration_ms`	`number` optional	Build duration in milliseconds. Null until the build completes.
`metadata`	`object` optional	The metadata object you supplied with the request, echoed back.

Errors

RFC 9457-inspired

Error status codes returned by the create deployment endpoint
Status	Code	What it means
400	`invalid_request`	Malformed JSON or an unsupported field in the request body.
401	`invalid_api_key`	Missing, revoked or malformed bearer token.
403	`insufficient_scope`	The key lacks the deployments:write scope for this project.
404	`project_not_found`	No project matches the supplied ID in this workspace.
422	`validation_error`	A field failed validation. The failing param is included.
429	`rate_limited`	More than 60 requests per minute. Retry after the reset header.

Include the request_id when contacting support — it resolves the full trace in seconds.Contact support

Was this page helpful?