---
title: "Plan configuration file changes (v2)"
method: POST
path: "/org/{orgId}/config-file/plan"
tags: ["org"]
---

# Plan configuration file changes (v2)

`POST /org/{orgId}/config-file/plan`

## Request

- Base URL: `https://api.runway.team`
- URL: `https://api.runway.team/org/{orgId}/config-file/plan`
- Auth: API key in header `X-API-Key`

Compares a Configuration as Code (v2) YAML file with its app and lists every change applying it would make, without changing anything. The file's `app.id` picks the app; a file without one creates a new app in the organization. Pass the returned `planId` to `applyConfigFile`. A file that already matches its app returns a plan with status `unchanged`, which has nothing to apply. Requires an admin API key. See [Configuration as Code](https://docs.runway.team/api/configuration-as-code) for the file format.

## Path parameters

- `orgId` string, required

## Request body `application/yaml`

- string, binary

## Response `200`

The plan, with status `planned`, or `unchanged` when the file matches its app.

- ConfigFilePlan: The changes a configuration file makes to its app, and the result of applying them.
  - `planId` string: Pass this to `applyConfigFile`. Empty when the status is `unchanged`.
  - `orgId` string
  - `appId` string: The app the file changes. For a file that creates an app, it's set once the apply starts.
  - `status` 'planned' | 'queued' | 'applying' | 'applied' | 'failed' | 'unchanged': `planned`: not applied yet. `queued`: waiting to apply. `applying`: being applied. `applied`: done. `failed`: stopped partway; see `error` and `failedEntry`, and apply the plan again to continue. `unchanged`: the file matches its app, so there's nothing to apply.
  - `changes` ConfigFileChange[]: Every change the plan makes. A plan that creates an app lists just the app's creation.
    - `path` string: Where the change is in the file, like `notifications.BUILD_AVAIL.enabled`.
    - `action` 'create' | 'update' | 'delete'
    - `from` unknown
    - `to` unknown
    - `line` integer: The change's line in the file, when it has one.
  - `summary` object: The number of changes in each section of the file, by action, like `{"notifications": {"update": 2}}`. Once applied, it counts the changes that were actually made.
  - `createdBy` string
  - `createdAt` string, date-time
  - `appliedBy` string
  - `startedAt` string, date-time
  - `finishedAt` string, date-time
  - `succeededAt` string, date-time
  - `failedAt` string, date-time
  - `failedEntry` string: The entry that failed to apply, like `flightpath.steps.$beta`. Changes before it were already made.
  - `error` string: Why the apply failed.

## Other responses

- `400`: The file is invalid. Lists every problem at once.
- `403`: The API key does not have permission to perform this action
- `404`: Resource not found response

---

[API](https://skmtc.dev/runway/apis/runway-rest-api.md) - [All operations](https://skmtc.dev/runway/apis/runway-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runway/apis/runway-rest-api/revisions/081109863a9a?raw)