--- title: update-the-active-rolling-release-to-the-next-stage-for-a-project product: vercel url: /docs/rest-api/rolling-release/update-the-active-rolling-release-to-the-next-stage-for-a-project canonical_url: "https://vercel.com/docs/rest-api/rolling-release/update-the-active-rolling-release-to-the-next-stage-for-a-project" last_updated: 2026-08-28 type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about update-the-active-rolling-release-to-the-next-stage-for-a-project on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Update the active rolling release to the next stage for a project ```http POST /v1/projects/{idOrName}/rolling-release/approve-stage ``` Advance a rollout to the next stage. This is only needed when rolling releases is configured to require manual approval. ## Authentication **bearerToken**: HTTP bearer ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `idOrName` | string | Yes | Project ID or project name (URL-encoded) | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `teamId` | string | No | The Team identifier to perform the request on behalf of. | | `slug` | string | No | The Team slug to perform the request on behalf of. | ## Request body Required: No Content-Type: `application/json` ```json { "type": "object", "required": [ "nextStageIndex", "canaryDeploymentId" ], "properties": { "nextStageIndex": { "type": "number", "description": "The index of the stage to transition to" }, "canaryDeploymentId": { "type": "string", "description": "The id of the canary deployment to approve for the next stage" } } } ``` ## Example request ### TypeScript ```typescript const response = await fetch('https://api.vercel.com/v1/projects/idOrName/rolling-release/approve-stage?teamId=string&slug=string', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ "nextStageIndex": "123", "canaryDeploymentId": "example_id" }), }); const data = await response.json(); console.log(data); ``` ### Next.js ```typescript 'use server'; export async function callEndpoint() { const response = await fetch('https://api.vercel.com/v1/projects/idOrName/rolling-release/approve-stage?teamId=string&slug=string', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.VERCEL_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "nextStageIndex": "123", "canaryDeploymentId": "example_id" }), next: { revalidate: 3600 } }); if (!response.ok) { throw new Error('Request failed'); } return response.json(); } ``` ### cURL ```bash curl -X POST 'https://api.vercel.com/v1/projects/idOrName/rolling-release/approve-stage?teamId=string&slug=string' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d "{ \"nextStageIndex\": \"123\", \"canaryDeploymentId\": \"example_id\" }" ``` ## Example response ```json { "rollingRelease": { "state": "ACTIVE", "substate": "PAUSED", "currentDeployment": { "name": "my-project", "createdAt": "1540257589405", "readyState": "READY", "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ", "target": "null", "readyStateAt": "123", "source": "cli", "url": "my-instant-deployment-3ij3cxz9qr.now.sh" }, "canaryDeployment": { "name": "my-project", "createdAt": "1540257589405", "readyState": "READY", "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ", "target": "null", "readyStateAt": "123", "source": "cli", "url": "my-instant-deployment-3ij3cxz9qr.now.sh" }, "queuedDeploymentId": "dpl_ghi789", "advancementType": "manual-approval", "stages": [ { "index": "0", "isFinalStage": "false", "targetPercentage": "25", "requireApproval": "false", "duration": "null", "linearShift": "false" } ], "activeStage": { "index": "0", "isFinalStage": "false", "targetPercentage": "25", "requireApproval": "false", "duration": "null", "linearShift": "false" }, "nextStage": { "index": "0", "isFinalStage": "false", "targetPercentage": "25", "requireApproval": "false", "duration": "null", "linearShift": "false" }, "startedAt": "1716210500000", "updatedAt": "1716210600000", "currentCanaryPercentage": "123" } } ``` ## Responses ### 200: No description Content-Type: `application/json` ```json { "type": "object", "description": "The response format for rolling release endpoints that return rolling release information", "required": [ "rollingRelease" ], "properties": { "rollingRelease": { "type": "object", "description": "Rolling release information including configuration and document details, or null if no rolling release exists", "nullable": true, "required": [ "activeStage", "advancementType", "canaryDeployment", "currentDeployment", "nextStage", "queuedDeploymentId", "stages", "startedAt", "state", "substate", "updatedAt" ], "properties": { "state": { "type": "string", "description": "The current state of the rolling release", "enum": [ "ABORTED", "ACTIVE", "COMPLETE" ] }, "substate": { "type": "string", "description": "When set to `PAUSED`, the rollout is frozen at the current percentage until continued.", "enum": [ "PAUSED", null ], "nullable": true }, "currentDeployment": { "type": "object", "description": "The current deployment receiving production traffic", "nullable": true, "required": [ "createdAt", "id", "name", "readyState", "url" ], "properties": { "name": { "type": "string", "description": "The name of the project associated with the deployment at the time that the deployment was created" }, "createdAt": { "type": "number", "description": "A number containing the date when the deployment was created in milliseconds" }, "readyState": { "type": "string", "description": "The state of the deployment depending on the process of deploying, or if it is ready or in an error state", "enum": [ "BLOCKED", "BUILDING", "CANCELED", "ERROR", "INITIALIZING", "QUEUED", "READY" ] }, "id": { "type": "string", "description": "A string holding the unique ID of the deployment" }, "target": { "type": "string", "description": "If defined, either `staging` if a staging alias in the format `..now.sh` was assigned upon creation, or `production` if the aliases from `alias` were assigned. `null` value indicates the \"preview\" deployment.", "enum": [ "production", "staging", null ], "nullable": true }, "readyStateAt": { "type": "number" }, "source": { "type": "string", "description": "Where was the deployment created from. Best-effort guess for metrics only — not authoritative; do not gate behavior on it.", "enum": [ "api-trigger-git-deploy", "cli", "clone/repo", "drop", "git", "git-deploy-hook", "import", "import/repo", "redeploy", "v0-web" ] }, "url": { "type": "string", "description": "A string with the unique URL of the deployment" } } }, "canaryDeployment": { "type": "object", "description": "The canary deployment being rolled out", "nullable": true, "required": [ "createdAt", "id", "name", "readyState", "url" ], "properties": { "name": { "type": "string", "description": "The name of the project associated with the deployment at the time that the deployment was created" }, "createdAt": { "type": "number", "description": "A number containing the date when the deployment was created in milliseconds" }, "readyState": { "type": "string", "description": "The state of the deployment depending on the process of deploying, or if it is ready or in an error state", "enum": [ "BLOCKED", "BUILDING", "CANCELED", "ERROR", "INITIALIZING", "QUEUED", "READY" ] }, "id": { "type": "string", "description": "A string holding the unique ID of the deployment" }, "target": { "type": "string", "description": "If defined, either `staging` if a staging alias in the format `..now.sh` was assigned upon creation, or `production` if the aliases from `alias` were assigned. `null` value indicates the \"preview\" deployment.", "enum": [ "production", "staging", null ], "nullable": true }, "readyStateAt": { "type": "number" }, "source": { "type": "string", "description": "Where was the deployment created from. Best-effort guess for metrics only — not authoritative; do not gate behavior on it.", "enum": [ "api-trigger-git-deploy", "cli", "clone/repo", "drop", "git", "git-deploy-hook", "import", "import/repo", "redeploy", "v0-web" ] }, "url": { "type": "string", "description": "A string with the unique URL of the deployment" } } }, "queuedDeploymentId": { "type": "string", "description": "The ID of a deployment queued for the next rolling release", "nullable": true }, "advancementType": { "type": "string", "description": "The advancement type of the rolling release", "enum": [ "automatic", "manual-approval" ] }, "stages": { "type": "array", "description": "All stages configured for this rolling release", "items": { "type": "object", "description": "All stages configured for this rolling release", "required": [ "duration", "index", "isFinalStage", "requireApproval", "targetPercentage" ] } }, "activeStage": { "type": "object", "description": "The currently active stage, null if the rollout is aborted", "nullable": true, "required": [ "duration", "index", "isFinalStage", "requireApproval", "targetPercentage" ], "properties": { "index": { "type": "number", "description": "The zero-based index of the stage" }, "isFinalStage": { "type": "boolean", "description": "Whether or not this stage is the final stage (targetPercentage === 100)", "enum": [ false, true ] }, "targetPercentage": { "type": "number", "description": "The percentage of traffic to serve to the canary deployment (0-100)" }, "requireApproval": { "type": "boolean", "description": "Whether or not this stage requires manual approval to proceed", "enum": [ false, true ] }, "duration": { "type": "number", "description": "Duration in seconds for automatic advancement, null for manual stages or the final stage", "nullable": true }, "linearShift": { "type": "boolean", "description": "Whether to linearly shift traffic over the duration of this stage", "enum": [ false, true ] } } }, "nextStage": { "type": "object", "description": "The next stage to be activated, null if not in ACTIVE state", "nullable": true, "required": [ "duration", "index", "isFinalStage", "requireApproval", "targetPercentage" ], "properties": { "index": { "type": "number", "description": "The zero-based index of the stage" }, "isFinalStage": { "type": "boolean", "description": "Whether or not this stage is the final stage (targetPercentage === 100)", "enum": [ false, true ] }, "targetPercentage": { "type": "number", "description": "The percentage of traffic to serve to the canary deployment (0-100)" }, "requireApproval": { "type": "boolean", "description": "Whether or not this stage requires manual approval to proceed", "enum": [ false, true ] }, "duration": { "type": "number", "description": "Duration in seconds for automatic advancement, null for manual stages or the final stage", "nullable": true }, "linearShift": { "type": "boolean", "description": "Whether to linearly shift traffic over the duration of this stage", "enum": [ false, true ] } } }, "startedAt": { "type": "number", "description": "Unix timestamp in milliseconds when the rolling release started" }, "updatedAt": { "type": "number", "description": "Unix timestamp in milliseconds when the rolling release was last updated" }, "currentCanaryPercentage": { "type": "number", "description": "When set (for example while {@link substate} is `PAUSED`), the canary traffic percentage persisted on the rollout document — use for dashboard display when linear shift is active." } } } } } ``` ### 400: One of the provided values in the request body is invalid. One of the provided values in the request query is invalid. ### 401: The request is not authorized. ### 403: You do not have permission to access this resource. ### 404: No description ### 410: No description ### 500: No description --- ## Related - [rolling-release endpoints](/docs/rest-api#rolling-release) - [REST API overview](/docs/rest-api) - [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints) --- [View full sitemap](/docs/sitemap)