HashiDays One conference. Three cities. Find a city near you
Terraform
Terraform Home

You are viewing documentation for version v202305-1. View latest version.

Projects API

Create a Project

POST /organizations/:organization_name/projects

ParameterDescription
:organization_nameThe name of the organization to create the project in. The organization must already exist in the system, and the user must have permissions to create new projects.

Note: Project creation is restricted to the owners team, teams with the "Manage Projects" permission, and the organization API token.

Request Body

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

Properties without a default value are required.

Key pathTypeDefaultDescription
data.typestringMust be "projects".
data.attributes.namestringThe name of the project, which can only include letters, numbers, spaces, -, and _. It must be at least 3 characters long and no more than 36 characters long.

Sample Payload

{  "data": {    "attributes": {      "name": "Test Project"    },    "type": "projects"  }}

Sample Response

{  "data": {    "id": "prj-WsVcWRr7SfxRci1v",    "type": "projects",    "attributes": {      "name": "Test Project",      "permissions": {        "can-update": true      }    },    "relationships": {      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        },        "links": {          "related": "/api/v2/organizations/my-organization"        }      }    },    "links": {      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"    }  }}

Update a Project

PATCH /projects/:project_id

ParameterDescription
:project_idThe ID of the project to update

Request Body

These PATCH endpoints require a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data.typestringMust be "projects".
data.attributes.namestring(previous value)A new name for the project, which can only include letters, numbers, spaces, -, and _. It must be at least 3 characters long and no more than 36 characters long.

Sample Payload

{  "data": {    "attributes": {      "name": "Infrastructure Project"    },    "type": "projects"  }}

Sample Request

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

Sample Response

{  "data": {    "id": "prj-WsVcWRr7SfxRci1v",    "type": "projects",    "attributes": {      "name": "Infrastructure Project",      "permissions": {        "can-update": true,        "can-destroy": true,        "can-create-workspace": true      }    },    "relationships": {      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        },        "links": {          "related": "/api/v2/organizations/my-organization"        }      }    },    "links": {      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"    }  }}

List projects

This endpoint lists projects in the organization.

GET /organizations/:organization_name/projects

ParameterDescription
:organization_nameThe name of the organization to list the projects of.

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

ParameterDescription
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 projects per page.
qOptional. A search query string. This query searches projects by name. This search is case-insensitive. If both q and filter[names] are specified, filter[names] will be used.
filter[names]Optional. If specified, returns the project with the matching name. This filter is case-insensitive. If multiple comma separated values are specified, projects matching any of the names are returned.
filter[permissions][create-workspace]Optional. If present, returns a list of projects that the authenticated user can create workspaces in.
filter[permissions][update]Optional. If present, returns a list of projects that the authenticated user can update.

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/organizations/my-organization/projects

Sample Response

{  "data": [    {      "id": "prj-W6k9K23oSXRHGpj3",      "type": "projects",      "attributes": {        "name": "Default Project",        "permissions": {          "can-update": true,          "can-destroy": true,          "can-create-workspace": true        }      },      "relationships": {        "organization": {          "data": {            "id": "my-organization",            "type": "organizations"          },          "links": {            "related": "/api/v2/organizations/my-organization"          }        }      },      "links": {        "self": "/api/v2/projects/prj-W6k9K23oSXRHGpj3"      }    },    {      "id": "prj-YoriCxAawTMDLswn",      "type": "projects",      "attributes": {        "name": "Infrastructure Project",        "permissions": {          "can-update": true,          "can-destroy": true,          "can-create-workspace": true        }      },      "relationships": {        "organization": {          "data": {            "id": "my-organization",            "type": "organizations"          },          "links": {            "related": "/api/v2/organizations/my-organization"          }        }      },      "links": {        "self": "/api/v2/projects/prj-YoriCxAawTMDLswn"      }    }  ],  "links": {    "self": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "first": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "prev": null,    "next": null,    "last": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20"  },  "meta": {    "status-counts": {      "total": 2,      "matching": 2    },    "pagination": {      "current-page": 1,      "page-size": 20,      "prev-page": null,      "next-page": null,      "total-pages": 1,      "total-count": 2    }  }}

Show project

GET /projects/:project_id

ParameterDescription
:project_idThe project ID

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v

Sample Response

{  "data": {    "id": "prj-WsVcWRr7SfxRci1v",    "type": "projects",    "attributes": {      "name": "Infrastructure Project",      "permissions": {        "can-update": true,        "can-destroy": true,        "can-create-workspace": true      }    },    "relationships": {      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        },        "links": {          "related": "/api/v2/organizations/my-organization"        }      }    },    "links": {      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"    }  }}

Delete a project

A project cannot be deleted if it contains workspaces.

DELETE /projects/:project_id

ParameterDescription
:project_idThe ID of the project to delete
StatusResponseReason(s)
204NothingSuccessfully deleted the project
403JSON API error objectNot authorized to perform a force delete on the project
404JSON API error objectProject not found, or user unauthorized to perform project delete

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request DELETE \  https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v