Projects API reference

This topic provides reference information about the projects API.

The scope of the API includes the following endpoints:

Method	Path	Action
`POST`	`/organizations/:organization_name/projects`	Call this endpoint to create a project.
`PATCH`	`/projects/:project_id`	Call this endpoint to update an existing project.
`GET`	`/organizations/:organization_name/projects`	Call this endpoint to list existing projects.
`GET`	`/projects/:project_id`	Call this endpoint to show project details.
`DELETE`	`/projects/:project_id`	Call this endpoint to delete a project.
`GET`	`/projects/:project_id/tag-bindings`	Call this endpoint to list project tag bindings. (For projects, this returns the same result set as the `effective-tag-bindings` endpoint.)
`GET`	`/projects/:project_id/effective-tag-bindings`	Call this endpoint to list project effective tag bindings. (For projects, this returns the same result set as the `tag-bindings` endpoint.)

Requirements

You must be on a team with one of the Owners or Manage projects permissions settings enabled to create and manage projects. Refer to Permissions for additional information.

You can also provide an organization API token to call project API endpoints. Refer to Organization API Tokens for additional information.

Create a Project

POST /organizations/:organization_name/projects

Parameter	Description
`:organization_name`	The 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 path	Type	Default	Description
`data.type`	string	none	Must be `"projects"`.
`data.attributes.name`	string		The name of the project. The name can contain letters, numbers, spaces, `-`, and `_`, but cannot start or end with spaces. It must be at least three characters long and no more than 40 characters long.
`data.attributes.description`	string	none	Optional. The description of the project. It must be no more than 256 characters long.
`data.attributes.auto-destroy-activity-duration`	string	none	Specifies the default for how long each workspace in the project should wait before automatically destroying its infrastructure. You can specify a duration up to four digits that is greater than `0` followed by either a `d` for days or `h` hours. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`. All future workspaces in this project inherit this default value. Refer to Automatically destroy inactive workspaces for additional information.
`data.relationships.tag-bindings.data`	list of objects	none	Specifies a list of tags to bind to the project. Any tag binded to the project will be inherited by the workspaces belonging to it.
`data.relationships.tag-bindings.data.type`	string	none	Must be `tag-bindings` for each object in the list.
`data.relationships.tag-bindings.data.attributes.key`	string	none	Specifies the tag key for each object in the list.
`data.relationships.tag-bindings.data.attributes.value`	string	none	Specifies the tag value for each object in the list.

Sample Payload

{
  "data": {
    "attributes": {
      "name": "Test Project",
      "description": "An example project for documentation.",
    },
    "type": "projects",
    "relationships": {
      "tag-bindings": {
        "data": [
          {
            "type": "tag-bindings",
            "attributes": {
              "key": "environment",
              "value": "development"
            }
          },
        ]
      }
    }
  }
}

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/organizations/my-organization/projects

Sample Response

{
  "data": {
    "id": "prj-WsVcWRr7SfxRci1v",
    "type": "projects",
    "attributes": {
      "name": "Test Project",
      "description": "An example project for documentation.",
      "permissions": {
        "can-update": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        },
        "links": {
          "related": "/api/v2/organizations/my-organization"
        }
      },
      "tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings"
        }
      },
      "effective-tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings"
        }
      }
    },
    "links": {
      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"
    }
  }
}

Update a Project

Call the following endpoint to update a project:

PATCH /projects/:project_id

Parameter	Description
`:project_id`	The 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 path	Type	Default	Description
`data.type`	string	none	Must be `"projects"`.
`data.attributes.name`	string	existing value	A new name for the project. The name can contain letters, numbers, spaces, `-`, and `_`, but cannot start or end with spaces. It must be at least 3 characters long and no more than 40 characters long.
`data.attributes.description`	string	existing value	The new description for the project. It must be no more than 256 characters long.
`data.attributes.auto-destroy-activity-duration`	string	none	Specifies how long each workspace in the project should wait before automatically destroying its infrastructure by default. You can specify a duration up to four digits that is greater than `0` followed by either a `d` for days or `h` hours. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`. When you update this value, all workspaces in the project receive the new value unless you previously configured an override. Refer to Automatically destroy inactive workspaces for additional information.
`data.relationships.tag-bindings.data`	list of objects	none	Specifies a list of tags to bind to the project. Any tag binded to the project will be inherited by the workspaces belonging to it.
`data.relationships.tag-bindings.data.type`	string	none	Must be `tag-bindings` for each object in the list.
`data.relationships.tag-bindings.data.attributes.key`	string	none	Specifies the tag key for each object in the list.
`data.relationships.tag-bindings.data.attributes.value`	string	none	Specifies the tag value for each object in the list.

Sample Payload

{
  "data": {
    "attributes": {
      "name": "Infrastructure Project"
    },
    "type": "projects",
    "relationships": {
      "tag-bindings": {
        "data": [
          {
            "type": "tag-bindings",
            "attributes": {
              "key": "environment",
              "value": "staging"
            }
          }
        ]
      }
    }
  }
}

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",
      "description": null,
      "workspace-count": 4,
      "team-count": 2,
      "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"
        }
      },
      "tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings"
        }
      },
      "effective-tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings"
        }
      }
    },
    "links": {
      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"
    }
  }
}

List projects

This endpoint lists projects in the organization.

GET /organizations/:organization_name/projects

Parameter	Description
`:organization_name`	The 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.

Parameter	Description
`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.
`q`	Optional. 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.
`sort`	Optional. Allows sorting the organization's projects by `"name"`. Prepending a hyphen to the sort parameter reverses the order. For example, `"-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable.

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",
        "description": null,
        "workspace-count": 2,
        "team-count": 1,
        "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"
          }
        },
        "tag-bindings": {
          "links": {
            "related": "/api/v2/projects/prj-W6k9K23oSXRHGpj3/tag-bindings"
          }
        },
        "effective-tag-bindings": {
          "links": {
            "related": "/api/v2/projects/prj-W6k9K23oSXRHGpj3/effective-tag-bindings"
          }
        }
      },
      "links": {
        "self": "/api/v2/projects/prj-W6k9K23oSXRHGpj3"
      }
    },
    {
      "id": "prj-YoriCxAawTMDLswn",
      "type": "projects",
      "attributes": {
        "name": "Infrastructure Project",
        "description": null,
        "workspace-count": 4,
        "team-count": 2,
        "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"
          }
        },
        "tag-bindings": {
          "links": {
            "related": "/api/v2/projects/prj-YoriCxAawTMDLswn/tag-bindings"
          }
        },
        "effective-tag-bindings": {
          "links": {
            "related": "/api/v2/projects/prj-YoriCxAawTMDLswn/effective-tag-bindings"
          }
        }
      },
      "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

Parameter	Description
`:project_id`	The 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",
      "description": null,
      "workspace-count": 4,
      "team-count": 2,
      "permissions": {
        "can-update": true,
        "can-destroy": true,
        "can-create-workspace": true
      },
      "auto-destroy-activity-duration": "2d"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        },
        "links": {
          "related": "/api/v2/organizations/my-organization"
        }
      },
      "tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings"
        }
      },
      "effective-tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings"
        }
      }
    },
    "links": {
      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"
    }
  }
}

Delete a project

A project cannot be deleted if it contains workspaces.

DELETE /projects/:project_id

Parameter	Description
`:project_id`	The ID of the project to delete

Status	Response	Reason(s)
204	No Content	Successfully deleted the project
403	JSON API error object	Not authorized to perform a force delete on the project
404	JSON API error object	Project 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

List project tag bindings

Call the following endpoints to list the tags bound to a project.

GET /projects/:project_id/tag-bindings: Lists the set of tags associated with the project. Tags set on the project are inherited by its workspaces.

Parameter	Description
`:project_id`	The ID of the project.

Sample request

The following request returns all tags bound to a project with the ID prj-WsVcWRr7SfxRci1v.

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

Sample response

{
    "data": [
        {
            "type": "tag-bindings",
            "attributes": {
                "key": "added",
                "value": "new",
                "created-at": "2024-11-20T00:04:47.948Z"
            }
        },
        {
            "type": "tag-bindings",
            "attributes": {
                "key": "aww",
                "value": "aww",
                "created-at": "2024-11-20T00:04:47.948Z"
            }
        }
    ]
}

Add/update Tag Bindings on a project

This endpoint can be used to add key-value Tag Bindings to an existing resource, or to update existing Tag Binding values on the resource. It cannot be used to remove any tag bindings from the resource. This endpoint is useful when you want to ensure a modification is additive.

Tag Bindings have special constraints:

Up to 10 tags can be applied to a project
All workspaces belonging to the project will inherit the Tag Bindings applied to this project.
Keys must be no more than 128 characters, allowing all alphanumeric characters plus the symbols _, ., =, +, -, @, :.
Values allow the same characters, but can be up to 256 characters.
Certain key prefixes, including hc: and hcp: are not allowed.

PATCH /projects/:project_id/tag-bindings

Parameter	Description
`:project_id`	The ID of the project to update

Request Body

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

It is important to note that for each data item, type, as well as attributes.key is required.

Key path	Type	Description
`data[].type`	string	Must be `"tag-bindings"`.
`data[].attributes.key`	string	The key of the tag to add/update.
`data[].attributes.value`	string	The name of the tag to add/update.

Sample Payload

{
  "data": [
    {
      "type": "tag-bindings",
      "attributes": {
        "key": "costcenter",
        "value": "123"
      }
    },
    {
      "type": "tag-bindings",
      "attributes": {
        "key": "bar",
        "value": "baz"
      }
    }
  ]
}

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-82d2281aa259ba09/tag-bindings

Sample Response

Status Code 200

Response body after updating Tag Bindings

{
  "data": [
    {
      "id": "tb-e4a5847b2cf06559",
      "type": "tag-bindings",
      "attributes": {
        "key": "costcenter",
        "value": "123"
      }
    },
    {
      "id": "tb-97ce954636f93a6c",
      "type": "tag-bindings",
      "attributes": {
        "key": "bar",
        "value": "baz"
      }
    }
  ]
}

Move workspaces into a project

This endpoint allows you to move one or more workspaces into a project. You must have permission to move workspaces on the destination project as well as any source project(s). If you are not authorized to move any of the workspaces in the request, or if any workspaces in the request are not found, then no workspaces will be moved.

POST /projects/:project_id/relationships/workspaces

Parameter	Description
`:project_id`	The ID of the destination project

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

Key path	Type	Default	Description
`data[].type`	string		Must be `"workspaces"`
`data[].id`	string		The ids of workspaces to move into the destination project

Status	Response	Reason(s)
204	No Content	Successfully moved workspace(s)
403	JSON API error object	Workspace(s) not found, or user is not authorized to move all workspaces out of their current project(s)
404	JSON API error object	Project not found, or user unauthorized to move workspaces into project

Sample Payload

{
  "data": [
    {
      "type": "workspaces",
      "id": "ws-AQEct2XFuH4HBsmS"
    }
  ]
}

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/projects/prj-zXm4y2BjeGPgHtkp/relationships/workspaces

Sample Error Response

{
  "errors": [
    {
      "status": "403",
      "title": "forbidden",
      "detail": "Workspace(s) not found, or you are not authorized to move them: ws-AQEct2XFuH4HBmS"
    }
  ]
}