Plus Blocks

Deployments

Create a deployment

POSThttps://api.rivetlane.dev/v1/deployments

Builds a commit of a linked project and deploys it to a preview or to production. Returns immediately with status: building; the deployment moves to ready or failed when the build ends. A newer deployment to the same branch cancels an older one that is still building.

Requires a token with the deployments:write scope in Authorization: Bearer. Limited to 60 requests per minute per project.

Body parameters

Parameter	Required	Description
`project`string	Required	Project name or ID, as in `[project] name` of `rivetlane.toml`.
`branch`string	Required	Git branch to build. The latest commit is used unless `commit` is set.
`target`enum	Optional	Where the deployment receives traffic once it is ready.`preview` (default) · `production`
`commit`string	Optional	Full or short SHA to build instead of the branch head.
`force`boolean	Optional	Skip the build cache. Needed after changing a `PUBLIC_` variable.Default: `false`
`meta`object	Optional	Up to 16 string pairs stored with the deployment and returned in webhooks.

Headers

Parameter	Required	Description
`Idempotency-Key`string	Optional	Retries with the same key within 24 hours return the original deployment.

Request

$ curl https://api.rivetlane.dev/v1/deployments \    -H "Authorization: Bearer $RIVET_TOKEN" \    -H "Content-Type: application/json" \    -d '{      "project": "storefront",      "branch": "main",      "target": "production"    }'

const deployment = await rivet.deployments.create({  project: "storefront",  branch: "main",  target: "production",})

deployment = rivet.deployments.create(    project="storefront",    branch="main",    target="production",)

Response

201 Created

{  "id": "dpl_7Hq2xKfR",  "project": "storefront",  "branch": "main",  "commit": "a41c9e2",  "target": "production",  "status": "building",  "url": "https://storefront-a41c9e2.rivetlane.app",  "created_at": "2026-10-09T14:02:11Z"}

404 Not found

{  "error": {    "code": "branch_not_found",    "message": "Branch 'mian' does not exist in quillon/storefront.",    "param": "branch"  }}

422 Unprocessable

{  "error": {    "code": "secret_in_config",    "message": "rivetlane.toml defines a credential-like key: TALLYBIRD_SECRET_KEY.",    "doc_url": "https://rivetlane.dev/docs/env#defaults-in-rivetlane-toml"  }}

429 Rate limited

{  "error": {    "code": "rate_limited",    "message": "60 requests per minute per project. Retry after 12s.",    "retry_after": 12  }}