HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Terraform
Terraform Home

You are viewing documentation for version v202302-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. Allows querying a list of projects by name. This search is case-insensitive.
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