»Plan Exports API

Plan exports allow users to download data exported from the plan of a Run in a Terraform workspace. Currently, the only supported format for exporting plan data is to generate mock data for Sentinel.

»Create a plan export

POST /plan-exports

This endpoint exports data from a plan in the specified format. The export process is asynchronous, and the resulting data becomes downloadable when its status is "finished". The data is then available for one hour before expiring. After the hour is up, a new export can be created.

»Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

»Sample Payload

{
  "data": {
    "type": "plan-exports",
    "attributes": {
      "data-type": "sentinel-mock-bundle-v0"
    },
    "relationships": {
      "plan": {
        "data": {
          "id": "plan-8F5JFydVYAmtTjET",
          "type": "plans"
        }
      }
    }
  }
}

{
  "data": {
    "type": "plan-exports",
    "attributes": {
      "data-type": "sentinel-mock-bundle-v0"
    },
    "relationships": {
      "plan": {
        "data": {
          "id": "plan-8F5JFydVYAmtTjET",
          "type": "plans"
        }
      }
    }
  }
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/plan-exports

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/plan-exports

»Sample Response

{
  "data": {
    "id": "pe-3yVQZvHzf5j3WRJ1",
    "type": "plan-exports",
    "attributes": {
      "data-type": "sentinel-mock-bundle-v0",
      "status": "queued",
      "status-timestamps": {
        "queued-at": "2019-03-04T22:29:53+00:00",
      },
    },
    "relationships": {
      "plan": {
        "data": {
          "id": "plan-8F5JFydVYAmtTjET",
          "type": "plans"
        }
      }
    },
    "links": {
      "self": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1",
    }
  }
}

{
  "data": {
    "id": "pe-3yVQZvHzf5j3WRJ1",
    "type": "plan-exports",
    "attributes": {
      "data-type": "sentinel-mock-bundle-v0",
      "status": "queued",
      "status-timestamps": {
        "queued-at": "2019-03-04T22:29:53+00:00",
      },
    },
    "relationships": {
      "plan": {
        "data": {
          "id": "plan-8F5JFydVYAmtTjET",
          "type": "plans"
        }
      }
    },
    "links": {
      "self": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1",
    }
  }
}

»Show a plan export

GET /plan-exports/:id

There is no endpoint to list plan exports. You can find IDs for plan exports in the relationships.exports property of a plan object.

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1

»Sample Response

{
  "data": {
    "id": "pe-3yVQZvHzf5j3WRJ1",
    "type": "plan-exports",
    "attributes": {
      "data-type": "sentinel-mock-bundle-v0",
      "status": "finished",
      "status-timestamps": {
        "queued-at": "2019-03-04T22:29:53+00:00",
        "finished-at": "2019-03-04T22:29:58+00:00",
        "expired-at": "2019-03-04T23:29:58+00:00"
      },
    },
    "relationships": {
      "plan": {
        "data": {
          "id": "plan-8F5JFydVYAmtTjET",
          "type": "plans"
        }
      }
    },
    "links": {
      "self": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1",
      "download": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1/download"
    }
  }
}

{
  "data": {
    "id": "pe-3yVQZvHzf5j3WRJ1",
    "type": "plan-exports",
    "attributes": {
      "data-type": "sentinel-mock-bundle-v0",
      "status": "finished",
      "status-timestamps": {
        "queued-at": "2019-03-04T22:29:53+00:00",
        "finished-at": "2019-03-04T22:29:58+00:00",
        "expired-at": "2019-03-04T23:29:58+00:00"
      },
    },
    "relationships": {
      "plan": {
        "data": {
          "id": "plan-8F5JFydVYAmtTjET",
          "type": "plans"
        }
      }
    },
    "links": {
      "self": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1",
      "download": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1/download"
    }
  }
}

»Download exported plan data

GET /plan-exports/:id/download

This endpoint generates a temporary URL to the location of the exported plan data in a .tar.gz archive, and then redirects to that link. If using a client that can follow redirects, you can use this endpoint to save the .tar.gz archive locally without needing to save the temporary URL.

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --location \
  https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1/download \
  > export.tar.gz

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --location \
  https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1/download \
  > export.tar.gz

»Delete exported plan data

DELETE /plan-exports/:id

Plan exports expire after being available for one hour, but they can be deleted manually as well.

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  -X DELETE \
  https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  -X DELETE \
  https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1