---
title: "Create scenario"
slug: "devtools-sourcedeploy-scenariocreate"
tags: ["SourceDeploy"]
updated: 2026-09-17T10:05:44Z
published: 2026-09-17T10:05:44Z
canonical: "api.ncloud-docs.com/devtools-sourcedeploy-scenariocreate"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create scenario

Available in Classic and VPC

Create a deployment scenario.

## Request

This section describes the request format. The method and URI are as follows:

| Method | URI |
| --- | --- |
| POST | /api/v1/project/{projectId}/stage/{stageId}/scenario |

### Request headers

For information about the headers common to all SourceDeploy APIs, see [SourceDeploy request headers](/docs/en/devtools-sourcedeploy#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

### Request path parameters

You can use the following path parameters with your request:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | String | Required | Project ID - See [Get project list](/docs/en/devtools-sourcedeploy-projectlist). |
| `stageId` | String | Required | Deployment stage ID - See [Get stage list](/docs/en/devtools-sourcedeploy-stagelist). |

### Request body

You can include the following data in the body of your request:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | String | Required | Deployment scenario name - Enter 1-100 characters by combining English letters, numbers, and special characters "-" and "_". |
| `description` | String | Optional | Deployment scenario description |
| `config` | Object | Required | Deployment target settings - Server: See [TScenarioServer](/docs/en/devtools-sourcedeploy-scenariocreate#TScenarioServer). - AutoScalingGroup: See [TScenarioAutoScalingGroup](/docs/en/devtools-sourcedeploy-scenariocreate#TScenarioAutoScalingGroup). - KubernetesService: See [TScenarioKubernetesService](/docs/en/devtools-sourcedeploy-scenariocreate#TScenarioKubernetesService). - ObjectStorage: See [TScenarioObjectStorage](/docs/en/devtools-sourcedeploy-scenariocreate#TScenarioObjectStorage). |

#### TScenarioServer

The following describes `TScenarioServer`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `strategy` | String | Required | Deployment strategy - `normal`: default (valid value) |
| `sequence` | Boolean | Optional | Sequential deployment - `true` (default) \| `false` - `true`: sequential deployment - `false`: simultaneous deployment |
| `file` | Object | Required | Deployment file information |
| `file.type` | String | Required | Deployment file location - `ObjectStorage` \| `SourceBuild` \| `later` - `ObjectStorage`: Object Storage - `SourceBuild`: SourceBuild - `later`: Set up later. |
| `file.ObjectStorage` | Object | Conditional | Object Storage information - If `file.type` is `ObjectStorage`, it must be entered including sub-information. |
| `file.ObjectStorage.bucket` | String | Conditional | Bucket name - See [Get Object Storage bucket list](/docs/en/devtools-sourcedeploy-objectstoragebucketlist). |
| `file.ObjectStorage.object` | String | Conditional | File name - See [Get Object Storage object list](/docs/en/devtools-sourcedeploy-objectstorageobjectlist). |
| `file.SourceBuild` | Object | Conditional | SourceBuild information - If `file.type` is `SourceBuild`, it must be entered including sub-information. |
| `file.SourceBuild.id` | Number | Conditional | Build project ID - See [Get SourceBuild project list](/docs/en/devtools-sourcedeploy-sourcebuildlist). |
| `rollback` | Boolean | Required | Whether to use rollback upon deployment failure - `true` \| `false` - `true`: use - `false`: not use |
| `cmd.pre` | Array | Optional | List of pre-deployment execution commands: [pre](/docs/en/devtools-sourcedeploy-scenariocreate#pre1) |
| `cmd.deploy` | Array | Optional | List of file deployment paths: [deploy](/docs/en/devtools-sourcedeploy-scenariocreate#deploy1) |
| `cmd.post` | Array | Optional | List of post-deployment execution commands: [post](/docs/en/devtools-sourcedeploy-scenariocreate#post1) |

#### `pre`

The following describes `pre`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user` | String | Optional | Account |
| `cmd` | String | Optional | Execution command |

#### `deploy`

The following describes `deploy`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sourcePath` | String | Optional | Source file path |
| `deployPath` | String | Optional | Deployment path |

#### `post`

The following describes `post`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user` | String | Optional | Account |
| `cmd` | String | Optional | Execution command |

#### TScenarioAutoScalingGroup

The following describes `TScenarioAutoScalingGroup`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `strategy` | String | Required | Deployment strategy - `normal` \| `blueGreen` - `normal`: default - `blueGreen`: blue/green |
| `sequence` | Boolean | Optional | Sequential deployment - `true` (default) \| `false` - `true`: sequential deployment - `false`: simultaneous deployment |
| `file` | Object | Required | Deployment file information |
| `file.type` | String | Required | Deployment file location - `ObjectStorage` \| `SourceBuild` \| `later` - `ObjectStorage`: Object Storage - `SourceBuild`: SourceBuild - `later`: Set up later. |
| `file.ObjectStorage` | Object | Conditional | Object Storage information - If `file.type` is `ObjectStorage`, it must be entered including sub-information. |
| `file.ObjectStorage.bucket` | String | Conditional | Bucket name - See [Get Object Storage bucket list](/docs/en/devtools-sourcedeploy-objectstoragebucketlist). |
| `file.ObjectStorage.object` | String | Conditional | File name - See [Get Object Storage object list](/docs/en/devtools-sourcedeploy-objectstorageobjectlist). |
| `file.SourceBuild` | Object | Conditional | SourceBuild information - If `file.type` is `SourceBuild`, it must be entered including sub-information. |
| `file.SourceBuild.id` | Number | Conditional | Build project ID - See [Get SourceBuild project list](/docs/en/devtools-sourcedeploy-sourcebuildlist). |
| `rollback` | Boolean | Required | Whether to use rollback upon deployment failure - `true` \| `false` - `true`: use - `false`: not use |
| `cmd.pre` | Array | Optional | List of pre-deployment execution commands: [pre](/docs/en/devtools-sourcedeploy-scenariocreate#pre2) |
| `cmd.deploy` | Array | Optional | List of file deployment paths: [deploy](/docs/en/devtools-sourcedeploy-scenariocreate#deploy2) |
| `cmd.post` | Array | Optional | List of post-deployment execution commands: [post](/docs/en/devtools-sourcedeploy-scenariocreate#post2) |
| `loadBalancer` | Object | Conditional | Load balancer information - If `strategy` is `blueGreen`, it must be entered including sub-information. |
| `loadBalancer.loadBalancerTargetGroupNo` | Number | Conditional | Load balancer target group ID - See [Get target group list (VPC)](/docs/en/devtools-sourcedeploy-targetgrouplist). |
| `loadBalancer.deleteAsg` | Boolean | Conditional | Whether to delete existing Auto Scaling group - `true` \| `false` - `true`: delete and terminate - `false`: maintain |
| `loadBalancer.deleteServer` | Boolean | Conditional | Whether to terminate servers in Auto Scaling group - `true` \| `false` - `true`: terminate - `false`: maintain - If `loadBalancer.deleteAsg` is `true`, enter `true`. |

#### `pre`

The following describes `pre`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user` | String | Optional | Account |
| `cmd` | String | Optional | Execution command |

#### `deploy`

The following describes `deploy`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sourcePath` | String | Optional | Source file path |
| `deployPath` | String | Optional | Deployment path |

#### `post`

The following describes `post`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user` | String | Optional | Account |
| `cmd` | String | Optional | Execution command |

#### TScenarioKubernetesService

The following describes `TScenarioKubernetesService`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `strategy` | String | Required | Deployment strategy - `rolling` \| `blueGreen` \| `canary` - `rolling`: rolling - `blueGreen`: blue/green - `canary`: canary |
| `manifest` | Object | Required | Manifest information |
| `manifest.type` | String | Required | Manifest file repository - `SourceCommit` (valid value) |
| `manifest.repository` | String | Required | Repository name - See [Get SourceCommit repository list](/docs/en/devtools-sourcedeploy-sourcecommitrepolist). |
| `manifest.branch` | String | Required | Branch name - See [Get SourceCommit branch list](/docs/en/devtools-sourcedeploy-sourcecommitbranchlist). |
| `manifest.path` | Array | Required | File location list |
| `canaryConfig` | Object | Conditional | Canary analysis settings - If `strategy` is `canary`, it must be entered including sub-information. |
| `canaryConfig.analysisType` | String | Conditional | Canary analysis method - `manual` \| `auto` - `manual`: manual - `auto`: automatic |
| `canaryConfig.canaryCount` | Number | Conditional | Number of baseline and canary pods - 1-10 |
| `canaryConfig.timeout` | Number | Conditional | Timeout (minute) - 1-360 - Maximum decision time for canary deployment/cancellation - Required if `canaryConfig.analysisType` is `manual` |
| `canaryConfig.prometheus` | String | Conditional | Prometheus URL - Required if `canaryConfig.analysisType` is `auto` |
| `canaryConfig.env` | Object | Conditional | Analysis environment variable - If `canaryConfig.analysisType` is `auto`, it must be entered including sub-information. |
| `canaryConfig.env.baseline` | String | Conditional | Analysis environment variable: baseline name - Enter up to 62 characters by combining English letters, numbers, and special characters "-" and "_". |
| `canaryConfig.env.canary` | String | Conditional | Analysis environment variable: canary name - Enter up to 62 characters by combining English letters, numbers, and special characters "-" and "_". |
| `canaryConfig.metrics` | Array | Conditional | Metric settings list: [metrics](/docs/en/devtools-sourcedeploy-scenariocreate#metrics) - If `canaryConfig.analysisType` is `auto`, it must be entered including sub-information. |
| `canaryConfig.analysisConfig` | Object | Conditional | Analysis settings - If `canaryConfig.analysisType` is `auto`, it must be entered including sub-information. |
| `canaryConfig.analysisConfig.duration` | Number | Conditional | Analysis time (minute) - 10-360 |
| `canaryConfig.analysisConfig.delay` | Number | Conditional | Analysis delay time (minute) - 0-60 |
| `canaryConfig.analysisConfig.interval` | Number | Conditional | Analysis cycle (minute) - 1-360 - Must be less than the analysis time. |
| `canaryConfig.analysisConfig.step` | Number | Conditional | Metric collection cycle (second) - 10-360 |
| `canaryConfig.passScore` | Number | Conditional | Analysis success score - 1-100 - Required if `canaryConfig.analysisType` is `auto` |

#### `metrics`

The following describes `metrics`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | String | Conditional | Metric name - Enter 1-100 characters by combining English letters, numbers, and special characters "-" and "_". |
| `successCriteria` | String | Conditional | Success criteria - `base` \| `canary` - `base`: baseline > canary - `canary`: baseline < canary |
| `queryType` | String | Conditional | Query type - `default` \| `promQL` |
| `weight` | Number | Conditional | Metric weight - 1-100 - The weighted sum of the entered metrics must total 100. |
| `metric` | String | Conditional | Metric value - Enter the metric set up in Prometheus. - Required if `queryType` is `default` |
| `filter` | String | Conditional | Filter value - Enter label conditions. - Required if `queryType` is `default` |
| `query` | String | Conditional | Query - Required if `queryType` is `promQL` |

#### TScenarioObjectStorage

The following describes `TScenarioObjectStorage`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | Object | Required | Deployment file information |
| `file.type` | String | Required | Deployment file location - `ObjectStorage` \| `SourceBuild` \| `later` - `ObjectStorage`: Object Storage - `SourceBuild`: SourceBuild - `later`: Set up later. |
| `file.ObjectStorage` | Object | Conditional | Object Storage information - If `file.type` is `ObjectStorage`, it must be entered including sub-information. |
| `file.ObjectStorage.bucket` | String | Conditional | Bucket name - See [Get Object Storage bucket list](/docs/en/devtools-sourcedeploy-objectstoragebucketlist). |
| `file.ObjectStorage.object` | String | Conditional | File name - See [Get Object Storage object list](/docs/en/devtools-sourcedeploy-objectstorageobjectlist). - Only ZIP format is supported. |
| `file.SourceBuild` | Object | Conditional | SourceBuild information - If `file.type` is `SourceBuild`, it must be entered including sub-information. |
| `file.SourceBuild.id` | Number | Conditional | Build project ID - See [Get SourceBuild project list](/docs/en/devtools-sourcedeploy-sourcebuildlist). |
| `path` | Array | Optional | List of file deployment paths: [path](/docs/en/devtools-sourcedeploy-scenariocreate#path) |

#### `path`

The following describes `path`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sourcePath` | String | Optional | Source file path |
| `deployPath` | String | Optional | Deployment path |

### Request example

The request example is as follows:

```
curl --location --request POST 'https://vpcsourcedeploy.apigw.ntruss.com/api/v1/project/2***/stage/3***/scenario' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "testScenario2",
    "description": "test Scenario 2",
    "config": {
        "strategy": "normal",
        "sequence": true,
        "file": {
            "type": "ObjectStorage",
            "ObjectStorage": {
                "bucket": "devtool",
                "object": "/result/build-sample.zip"
            }
        },
        "rollback": true,
        "cmd": {
            "pre": [
                {
                    "user": "root",
                    "cmd": "mv logs/app.log logs/app_$(date +%s).log"
                }
            ],
            "deploy": [
                {
                    "sourcePath": "/main.py",
                    "deployPath": "/home/root/"
                }
            ],
            "post": [
                {
                    "user": "root",
                    "cmd": "nohup python3 main.py > logs/app.log 2>&1 &"
                }
            ]
        }
    }
}'
```

## Response

This section describes the response format.

### Response body

The response body includes the following data:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `result` | Object | - | Response result |
| `result.id` | Number | - | Deployment scenario ID |
| `result.name` | String | - | Deployment scenario name |

### Response status codes

For information about the HTTP status codes common to all SourceDeploy APIs, see [SourceDeploy response status codes](/docs/en/devtools-sourcedeploy#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C).

### Response example

The response example is as follows:

```
{
    "result": {
        "id": 2***,
        "name": "testScenario2"
    }
}
```