github.com/danp/terraform@v0.9.5-0.20170426144147-39d740081351/website/source/docs/enterprise/api/runs.html.md (about)

     1  ---
     2  layout: "enterprise"
     3  page_title: "Runs - API - Terraform Enterprise"
     4  sidebar_current: "docs-enterprise-api-runs"
     5  description: |-
     6    Runs in Terraform Enterprise represents a two step Terraform plan and a subsequent apply.
     7  ---
     8  
     9  # Runs API
    10  
    11  Runs in Terraform Enterprise represents a two step Terraform plan and a
    12  subsequent apply.
    13  
    14  Runs are queued under [environments](/docs/enterprise/api/environments.html)
    15  and require a two-step confirmation workflow. However, environments
    16  can be configured to auto-apply to avoid this.
    17  
    18  ## Queue Run
    19  
    20  Starts a new run (plan) in the environment. Requires a configuration version to
    21  be present on the environment to succeed, but will otherwise 404.
    22  
    23  | Method | Path           |
    24  | :----- | :------------- |
    25  | `POST` | `/environments/:username/:name/plan` |
    26  
    27  ### Parameters
    28  
    29  - `:username` `(string: <required>)` - Specifies the username or organization
    30    name under which to get the latest configuration version. This username must
    31    already exist in the system, and the user must have permission to create new
    32    configuration versions under this namespace. This is specified as part of the
    33    URL.
    34  
    35  - `:name` `(string: <required>)` - Specifies the name of the configuration for
    36    which to get the latest configuration. This is specified as part of the URL.
    37  
    38  - `destroy` `(bool: false)` - Specifies if the plan should be a destroy plan.
    39  
    40  ### Sample Payload
    41  
    42  ```json
    43  {
    44    "destroy": false
    45  }
    46  ```
    47  
    48  ### Sample Request
    49  
    50  ```text
    51  $ curl \
    52      --request POST \
    53      --header "X-Atlas-Token: ..." \
    54      --header "Content-Type: application/json" \
    55      --data @payload.json \
    56      https://atlas.hashicorp.com/api/v1/environments/my-organization/my-environment/plan
    57  ```
    58  
    59  ### Sample Response
    60  
    61  ```json
    62  {
    63    "success": true
    64  }
    65  ```